Developing IdP adapters

Developers can use the PingFederate SDK to create identity provider (IdP) adapters.

IdP adapters facilitate integration with external authentication systems, allowing user attributes to be looked up and sessions to be terminated during logout. In addition to performing the primary authentication step, IdP adapters can also perform secondary authentication steps to confirm the user’s identity. Administrators can configure IdP adapters in sign-on authentication policies and in policies for resetting or changing passwords.

The IdP authentication adapter interface

Developers can 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 in Shared plugin interfaces, you must define methods for:

User attribute lookup
Session termination

Looking up user attributes

PingFederate invokes the lookupAuthN() method of your IdP adapter to look up user attributes for a request, regardless of whether the request is for IdP- or SP-initiated single sign-on (SSO), an OAuth transaction, or direct IdP-to-SP adapter processing. PingFederate uses the same method to authenticate a user when the adapter is placed in a password reset or password change policy.

AuthnAdapterResponse lookupAuthN(
  HttpServletRequest req,
  HttpServletResponse resp,
  Map<String, Object> inParameters)
  throws AuthnAdapterException, IOException;

The IdpAuthenticationAdapterV2 interface provides an overloaded version of the lookupAuthN() method. The original lookupAuthN() method in the IdpAuthenticationAdapter interface is deprecated, so only use the method in the IdpAuthenticationAdapterV2 interface.

The parameters for the lookupAuthN() method are HttpServletRequest, the HttpServletResponse, and the inParameters map. The inParameters map contains important information about the SSO transaction that an adapter can use. The parameter keys are defined and documented in the IdpAuthenticationAdapterV2 interface.

If an adapter is able to identify the user without further interaction, it can immediately return an AuthnAdapterResponse containing the user attributes. If the adapter needs further interaction, it can write to the HttpServletResponse as appropriate and commit it. Immediately after invoking lookupAuthN(), PingFederate checks if the response has been committed. If it has been committed, PingFederate saves the state it needs and stops processing the current transaction. PingFederate continues processing the transaction when the browser returns to the transaction’s resume path, at which point PingFederate again invokes the lookupAuthN() method. This series of events will be repeated until the method returns without committing the response. When that happens, which could be during the first invocation, PingFederate continues transaction processing using the result of the method.

If the response is committed, then PingFederate ignores the return value. It only uses the return value of an invocation that does not commit the response.

The return type of lookupAuthN() is AuthnAdapterResponse. When the adapter has completed its processing and returns a value, it must populate the authnStatus field of this object. If the authnStatus is SUCCESS, it must also provide the user attributes in the attributeMap field. There are several attribute keys with special meanings, which are defined and documented in the IdpAuthenticationAdapterV2 interface.

Two basic styles of IdP adapter are common. In the first style, the adapter presents the user a form in which the user enters their credentials to authenticate themselves. Such adapters can use the TemplateRendererUtil class to render an HTML template in the user’s browser. An example of such an adapter is template-render-adapter-example, which is in the /sdk/plugin-src directory of PingFederate. That example also shows how you can develop an interactive adapter that supports the PingFederate authentication API. For more information, see Developing authentication API-capable adapters and selectors.

The second style of IdP adapter redirects the user to an external authentication system. After the user has been authenticated, the external system must redirect the user to the resume path for the SSO transaction. This path is provided to the adapter in the inParameters map using the key IN_PARAMETER_NAME_RESUME_PATH.

How the user attributes are returned to the adapter is up to the implementation. If the authentication system provides an API for retrieving user attributes, a reference to the attributes can be passed through a query parameter appended to the resume URL. Alternatively, if the authentication system shares a parent domain with PingFederate, a cookie can be used to communicate the user attributes.

The following diagram and numbered list show the request sequence for an adapter that redirects to an external authentication system.

Diagram with user, application server, and PingFederate server icons that illustrate the SSO request sequence for an IdP adapter that redirects to an external authentication system.

IdP-initiated SSO sequence:

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

Managing session attributes

The PingFederate SDK allows adapters to track session attributes. These attributes are stored in memory and replicated across multiple cluster nodes. They are looked up using the attribute name and the PF cookie from the user’s browser.

Session attributes can be global, spanning multiple SSO transactions, or be linked to a specific transaction. To avoid prompting the user again for credentials, an adapter could use a global session attribute containing the user attributes that were obtained when the user first signed on. A multi-factor authentication (MFA) adapter can use a transaction-scoped attribute to keep track of a one-time passcode that was sent to the user’s mobile device. Use SessionStateSupport to keep track of global attributes and use TransactionalStateSupport to track attributes for the current transaction. It’s important to remove transactional attributes when your adapter is finished processing and about to return a result from lookupAuthN(). This reduces heap usage and, more importantly, helps avoid subtle security issues.

PingFederate can maintain an authentication session on behalf of your adapter. If an authentication session is enabled for your adapter and user attributes were obtained through a previous call to lookupAuthN(), then PingFederate will avoid calling lookupAuthN() during subsequent SSO transactions, provided the session idle or maximum timeout has not been exceeded.

Generally, it’s better to rely on the PingFederate authentication session capability, rather than implementing your own within your adapter. If you do implement an internal session capability, ensure this session is not used when the authentication policy for the transaction indicates that reauthentication is required. The policy for the transaction is passed in the inParameters map using the key IN_PARAMETER_NAME_AUTHN_POLICY.

Designing adapters for use in password reset or password change policies

The HTML Form Adapter can invoke an authentication policy during password reset or password change operations. When your adapter is invoked as part of such a policy, IN_PARAMETER_NAME_USERID refers to the username the user entered at the start of the operation.

Consider the following when designing adapters that will be used in password reset or password change policies.

If your adapter can track an internal session, an existing session should not be used during a password reset or password change transaction. PingFederate will ensure the reauthenticate flag in the transaction policy (IN_PARAMETER_NAME_AUTHN_POLICY in the inParameters map) is set to true. When this flag is true, your adapter should ignore any existing session.

Session attributes that track the progress of the current authentication attempt should be stored using TransactionalStateSupport and must be removed when returning a success or failure result from lookupAuthN(). In particular, if your adapter tracks a session attribute indicating the authentication was successful (for example, to render a "Success" page to the user), you should store that attribute using TransactionalStateSupport and ensure it’s removed before returning AUTHN_STATUS.SUCCESS from lookupAuthN().

Terminating sessions

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(Map authnIdentifiers,
  HttpServletRequest req,
  HttpServletResponse resp,
  String resumePath)
  throws AuthnAdapterException, IOException

Like the lookupAuthN() method, the logoutAuthN() method has access to the HttpServletRequest and HttpServletResponse objects. The user attributes returned earlier from lookupAuthN() are also passed as the input parameter authnIdentifiers.

If your adapter maintains an internal session, it should remove associated session attributes during logoutAuthN(). If the adapter is associated with an external authentication system, it can 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.

PingFederate Server