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 |
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.
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
[.codeph]
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 ( Session attributes that track the progress of the current authentication attempt should be stored using |
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.