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 processing.

Note:

The 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 available parameters.

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 lookupAuthN() 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.

Tip:

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).