--- title: IDP adapter plugin description: Use this plugin to alter the processing of the authentication request at a particular point in the SAML journey, such as to redirect the user before single sign-on takes place, or before a failure response is sent. component: pingam version: 7.2 page_id: pingam:saml2-guide:plugins-idp-adapter canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/custom-idp-adapter.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pingam/8.1/am-saml2/custom-idp-adapter.html section_ids: java_implementation: Java implementation scripted_implementation: Scripted implementation customize_the_idp_adapter_script: Customize the IDP adapter script scripting-api-idp-adapter: IDP adapter scripting API --- # IDP adapter plugin Use this plugin to alter the processing of the authentication request at a particular point in the SAML journey, such as to redirect the user before single sign-on takes place, or before a failure response is sent. The plugin provides hooks at the following points in assertion processing: **IDP adapter plugin points** | Plugin point | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | preSingleSignOn | Invoked when the authentication request is first received. Only applicable to SP-initiated flows. | | preAuthentication | Invoked before the request is redirected for authentication. Only applicable to SP-initiated flows. | | preSendResponse | Invoked after the user has successfully authenticated or for an existing valid session, before the response is sent. | | preSignResponse | Invoked after the response has been constructed, but before the response is signed, to let you customize the content of the SAML response. | | preSendFailureResponse | Invoked before a SAML error response is returned. Only applicable to SP-initiated flows. | ## Java implementation To create a custom IDP adapter in Java, follow these high-level steps: 1. Include the `openam-federation-library` as a dependency in your Maven project. 2. Write a Java class that implements the `com.sun.identity.saml2.plugins.SAML2IdentityProviderAdapter` interface, or extends the `com.sun.identity.saml2.plugins.DefaultIDPAdapter` class. 3. Override one of the methods described in the [plugin points table](#idp-adapter-points) to customize the authentication journey. 4. Package your custom class in a JAR file and copy to the `/WEB-INF/lib` folder where you deployed AM. 5. Configure AM to use the new Java plugin. 1. In the AM admin UI, go to Realms > *Realm Name* > Applications > Federation > Entity Providers > *Hosted IDP Name* > Advanced. 2. In the IDP Adapter Class field, type the fully qualified name of your custom class. 3. Save your changes. 6. Restart AM or the container in which it runs. 7. Test your changes using an appropriate mode of single-sign on. For example, note that some of the plugin points are only invoked during SP-initiated flows. * Java interface `SAML2IdentityProviderAdapter` * Default Java class `com.sun.identity.saml2.plugins.DefaultIDPAdapter.java` ## Scripted implementation To view the default script, including the available script properties, see [saml2-idp-adapter.js](../scripting-guide/sample-scripts.html#saml2-idp-adapter-js). To view or modify the default script in the AM admin UI, go to Realms > *Realm Name* > Scripts and select SAML2 IDP Adapter Script. ### Customize the IDP adapter script Complete the following steps to implement an example IDP adapter script that determines whether the authentication journey should be redirected, based on the evaluation of a policy. If you prefer to create a new script, reference the new script name when you configure the hosted entity provider. For more information, see [Manage scripts (UI)](../scripting-guide/manage-scripts-console.html). This task assumes your environment is already correctly configured for single sign-on using SAML v2.0, where AM is the hosted IDP. 1. For this example, configure a policy that belongs to a policy set named `saml`: 1. In the AM admin UI, go to Realms > *Realm Name* > Authorization > Resource Types to create a [new resource type](../authorization-guide/resource-types-ui.html) with the following values: * **Name**: `SAML SP Access` * **Pattern**: `*` * **Action**: Assert (Default State: Deny) 2. Go to Policy Sets to create a [new policy set](../authorization-guide/policy-sets-ui.html): * **Id**: `saml` * **Name**: `saml` * **Resource Types**: `SAML SP Access` 3. Add a [new policy](../authorization-guide/policies-ui.html): * **Name**: `SAML Access Policy` * **Resource Types**: `SAML SP Access` * **Resources**: `*` * **Actions**: `ASSERT:Denied` * **Response Attributes**: `redirect_uri: https://example.com` * **Subjects**: `"type": "AuthenticatedUsers"` 2. To modify the default script, go to Scripts, and click SAML2 IDP Adapter Script. Alternatively, create a new script of type `Saml2 IDP Adapter`. 1. In the Script field, add code to the `preSendResponse` function to redirect or send an error response if the policy for the SP evaluates to false. For example: ```javascript function preSendResponse () { var frJava = JavaImporter( com.sun.identity.saml2.common.SAML2Exception); try { var ents = idpAdapterScriptHelper.getEntitlements( "saml", realm, session, authnRequest).iterator(); while(ents.hasNext()){ var entitlement = ents.next(); var isAllowed = entitlement.getActionValue("Assert"); if(isAllowed != null && isAllowed == true){ return false; } else{ var redirectUris = entitlement.getAttributes().get("redirect_uri"); if (redirectUris == null || redirectUris.isEmpty()){ logger.error("No redirect_uri"); response.sendError(403); } else{ var redirectUri = redirectUris.iterator().next(); response.sendRedirect(redirectUri); } return true; } } } catch(error) { logger.error("Error in preSend reponse. " + error); throw new frJava.SAML2Exception(error); } } ``` 2. Validate and save your changes. 3. Configure AM to use the updated IDP adapter script. 1. Still in the AM admin UI, go to Applications > Federation > Entity Providers > *Hosted IDP Name* > Advanced. 2. In the IDP Adapter Script field, select SAML2 IDP Adapter Script. If you created a new script rather than modifying the default, select your script name. 3. Save your changes. 4. Test your changes using an SP-initiated flow and verify that the user is redirected to the `redirect_uri` (in this example, https\://example.com). ## IDP adapter scripting API The following properties are available to IDP adapter scripts, in addition to the [common SAML v2.0 properties](customize-saml2-plugins.html#scripting-api-saml2). > **Collapse: Show script properties** > > * `authnRequest` > > The original authentication request sent from the SP. Not available to the `preSendFailureResponse` function. See [AuthnRequest](../_attachments/apidocs/com/sun/identity/saml2/protocol/AuthnRequest.html). > > * `faultCode` > > The fault code returned in the SAML response. > > Only available to the `preSendFailureResponse` function. > > * `faultDetail` > > Contains the details of the fault returned in the SAML response. > > Only available to the `preSendFailureResponse` function. > > * `idpAdapterScriptHelper` > > The IdpAdapterScriptHelper instance contains supporting methods that provide context information when customizing the IDP adapter plugin points. See the [idpAdapterScriptHelper](../_attachments/apidocs/com/sun/identity/saml2/plugins/scripted/IdpAdapterScriptHelper.html) interface. > > Always present. > > * `relayState` > > A String representing the relayState used in the redirect. > > Not available to the `preSingleSignOn` or `preSendFailureResponse` functions. > > * `reqId` > > The id to use for continuation of processing if the adapter redirects. > > Not available to the `preSignResponse` or `preSendFailureResponse` functions. > > * `request` > > The `HttpServletRequest` object. Always present. > > * `res` > > The SAML response. For information, see [Response](../_attachments/apidocs/com/sun/identity/saml2/protocol/Response.html). > > Only available to the `preSignResponse` function. > > * `response` > > The `HttpServletResponse` object. > > Not available to the `preSignResponse` function. > > * `session` > > Contains a representation of the user's single sign-on session object. See the [SSOToken](../_attachments/apidocs/com/iplanet/sso/SSOToken.html) interface for information about SSO token and authentication information, as well as session-related properties. > > Not available to the `preSingleSignOn` or `preSendFailureResponse` functions.