java.util.Map lookupAuthN(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, java.lang.String partnerSpEntityId, AuthnPolicy authnPolicy, java.lang.String resumePath) throws AuthnAdapterException, java.io.IOException
PingFederate invokes the
lookupAuthN() method of your IdP adapter to look up
user-session information to handle a request. This method is invoked regardless of whether the
request is for IdP- or SP-initiated SSO, an OAuth transaction, or direct IdP-to-SP adapter
IdpAuthenticationAdapterV2 interface provides an overloaded version of
lookupAuthN() applicable to PingFederate versions 6.4 and higher. Use this
interface if your adapter requires additional parameters from PingFederate. Refer to the
IdpAuthenticationAdapterV2 interface in the Javadocs for a complete list of
In most implementations, a user's session information
or a reference to it is communicated to PingFederate via the
HttpServletRequest, which is passed to the
method. For example, the user's session information can be passed in by the IdP application as
a cookie or query parameter.
If the request from the user's browser does not contain the necessary information to identify the user, you can use the HttpServletResponse in various ways to retrieve the user's session data—for example, by creating a 302 redirect or presenting a web page asking for credentials. If your adapter implementation uses the HttpServletResponse to retrieve the user's session information, you must return the user's browser to the URL in the resumePath parameter set by the PingFederate runtime server and passed to this method. The resumePath is a relative URL signaling PingFederate that a user is continuing an SSO transaction that has already been initiated.
When creating a custom adapter, you can design it to render a template for processing and
returning HTML to the user's browser using the
TemplateRendererUtil. A sample
(template-render-adapter-example) is included in the
sdk/plugin-src directory of your PingFederate instance.
If your adapter implementation writes to the HttpServletResponse to retrieve the user's session data, we recommend that the browser return to the resumePath URL at all times, whether the retrieval succeeds or fails. Doing so ensures the adapter does not interrupt the “adapter chain” if it is used with the Composite Adapter. The Composite Adapter allows an administrator to “chain” together a selection of available adapter instances for a connection. At runtime, adapter chaining means that SSO requests are passed sequentially through each adapter instance until one or more authentication results are found for the user. If the browser is unable to return to the resumePath URL at all times, then it could interrupt the adapter chain causing unexpected results for the Composite Adapter.
For some authentication mechanisms, not all adapters can return the browser to the resumePath URL. Such adapters should not be used with the Composite Adapter's “Sufficient” chaining policy (see Composite Adapter Configuration).