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:
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
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;
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
The parameters for the
lookupAuthN() method are
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
AuthnAdapterResponsecontaining the user attributes. If the adapter needs further interaction, it can write to the
HttpServletResponseas 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
AuthnAdapterResponse. When the adapter has completed its processing
and returns a value, it must populate the
authnStatus field of this
object. If the
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
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
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.
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
- The application server returns the session information and redirects the browser
along with the returned information to the
- 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
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
Designing adapters for use in password reset or password change policies
IN_PARAMETER_NAME_USERIDrefers 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
true, your adapter should ignore any existing
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
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
lookupAuthN() method, the
method has access to the
HttpServletResponse objects. The user attributes returned earlier
lookupAuthN() are also passed as the input parameter
If your adapter maintains an internal session, it should remove associated session
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
contains the URL to which the user is redirected to complete the SLO process.