IdP authentication adapter interface

Create an IdP adapter by implementing the IdpAuthenticationAdapterV2 interface. Implementing this interface requires the following Java packages:

  • org.sourceid.saml20.adapter.idp.authn
  • org.sourceid.saml20.adapter.gui
  • org.sourceid.saml20.adapter.conf

For each IdP adapter implementation, in addition to the methods described under Shared plugin interfaces, you must define the following:

  • Session lookup
  • Session logout

IdP adapter session lookup

PingFederate invokes the lookupAuthN() method of your IdP adapter to look up user-session information to handle a request, regardless of whether the request is for IdP- or service provider (SP)-initiated single sign-on (SSO), an OAuth transaction, or direct IdP-to-SP adapter processing.

Note: The IdentityStoreUserProvisioner interface is deprecated. Developers should implement either the IdentityStoreProvisionerWithFiltering or IdentityStoreProvisioner interfaces.
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
Note:

The IdpAuthenticationAdapterV2 interface provides an overloaded version of the lookupAuthN() method. The other overloaded lookupAuthN() version is deprecated; you should only use the one within the IdpAuthenticationAdapterV2 interface. Use this interface if your adapter requires additional parameters from PingFederate. For a complete list of available parameters, see the IdpAuthenticationAdapterV2 interface in the Javadocs.

In most implementations, a user's session information or a reference to it is communicated to PingFederate using the HttpServletRequest parameter, which is passed to the lookupAuthN() method. For example, the implementation can pass the user's session information from 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 parameter in various ways to retrieve the user's session data, such as creating a 302 redirect or presenting a web page asking for credentials. If your adapter implementation uses the HttpServletResponse parameter to retrieve the user's session, you must, return the user's browser to the URL declared in the resumePath parameter that was set by the PingFederate runtime server. The resumePath parameter is a relative URL signaling PingFederate that a user is continuing an already initiated SSO transaction.

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 class. 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 returning the URL specified by the resumePath parameter at all times, whether the retrieval succeeds or fails. This 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. Do not use such adapters with the composite adapter's “Sufficient” chaining policy. For more information, see Composite Adapter.

The following diagram illustrates the request sequence of an IdP-initiated SSO scenario that uses the URL specified by the resumePath parameter.
Diagram with a user, application server, and PingFederate server icons that illustrate the SSO request sequence for an IdP adapter that redirects to an external authentication system.

Processing steps

  1. User logs in to a local application or domain through an authentication mechanism such as an identity-management system.
  2. User requests access to a protected resource located in the service provider (SP) domain. The link or other mechanism invokes the PingFederate SSO service.
  3. PingFederate invokes the designated adapter's lookup method, including the resumePath parameter.
  4. The application server returns the session information and redirects the browser along with the returned information to the resumePath URL.
  5. PingFederate generates a SAML assertion and sends the browser with the SAML assertion to the SP's SAML gateway.

IdP adapter session logout

During single logout (SLO) request processing, PingFederate invokes your IdP adapter's logoutAuthN() method to terminate a user's session. This method is invoked during IdP- or SP-initiated SLO requests.

boolean  logoutAuthN(java.util.Map authnIdentifiers,
  javax.servlet.http.HttpServletRequest req, 
  javax.servlet.http.HttpServletResponse resp,     
  java.lang.String  resumePath)    
  throws AuthnAdapterException, java.io.IOException

Like the lookupAuthN() method, the logoutAuthN() method has access to the user's HttpServletRequest and HttpServletResponse objects. Use these objects to retrieve data about the user's session and to redirect the browser to an endpoint used to terminate the session at the application. The resumePath parameter contains the URL to which the user is redirected to complete the SLO process.