--- title: Developing IdP adapters description: Developers can use the PingFederate SDK to create identity provider (IdP) adapters. component: pingfederate version: 13.1 page_id: pingfederate:sdk_developers_guide:pf_develop_idp_adapt canonical_url: https://docs.pingidentity.com/pingfederate/13.1/sdk_developers_guide/pf_develop_idp_adapt.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: April 25, 2024 section_ids: the-idp-authentication-adapter-interface: The IdP authentication adapter interface looking-up-user-attributes: Looking up user attributes managing-session-attributes: Managing session attributes designing-adapters-for-use-in-password-reset-or-password-change-policies: Designing adapters for use in password reset or password change policies terminating-sessions: Terminating sessions --- # 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](pf_share_plugin_interface.html), 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 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](pf_develop_auth_api_capable_adapt_selec.html). 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.](_images/smn1662051350052.jpg) IdP-initiated SSO sequence: 1. A user signs on to a local application or domain through an authentication mechanism such as an identity-management system. 2. 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. 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 `[.codeph]`resumePath\`\`\`\` URL. 5. 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.