--- title: IdP adapter description: Use an IdP adapter script to alter the processing of the authentication request, such as to redirect the user before SSO or before sending a failure response. component: pingoneaic page_id: pingoneaic:am-saml2:custom-idp-adapter canonical_url: https://docs.pingidentity.com/pingoneaic/am-saml2/custom-idp-adapter.html keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Scripts"] page_aliases: ["saml2-guide:plugins-idp-adapter.adoc", "plugins-idp-adapter.adoc"] section_ids: example-idp-adapter-legacy: Redirect a journey using a legacy script idp-adapter-policy: Configure a policy create-idp-adapter: Create the script use-idp-adapter: Configure the IdP try-idp-adapter: Test the script example-idp-adapter-nextgen: Set a custom header using a next-generation script create-idp-adapter-ng: Create the script use-idp-adapter-ng: Configure the IdP try-idp-adapter-ng: Test the script --- # IdP adapter Use an IdP adapter script to alter the processing of the authentication request, such as to redirect the user before SSO or before sending a failure response. * Next-generation example script [SAML2 IDP Adapter Script (Next Gen)](../am-scripting/sample-scripts.html#saml2-idp-adapter-nextgen-js) * Legacy example script [SAML2 IDP Adapter Script](../am-scripting/sample-scripts.html#saml2-idp-adapter-js) * Script bindings [IdP adapter scripting API](../am-scripting/saml2-idp-adapter-api.html) The script provides hooks at the following points in assertion processing: | Processing phase | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `preSingleSignOn` | Invoked when Advanced Identity Cloud receives the authentication request. Only applicable to SP-initiated flows. | | `preAuthentication` | Invoked before redirecting the request for authentication. Only applicable to SP-initiated flows. | | `preSendResponse` | Invoked after the user successfully authenticates or makes the request with an existing valid session, and before the response is sent. | | `preSignResponse` | Invoked after Advanced Identity Cloud prepares the response, but before it signs the response. This lets you customize the content of the SAML response. | | `preSendFailureResponse` | Invoked before Advanced Identity Cloud returns a SAML error response. Only applicable to SP-initiated flows. | ## Redirect a journey using a legacy script Before you try the example, configure SSO using SAML 2.0 with Advanced Identity Cloud as the hosted IdP. The following example determines whether to redirect the authentication journey based policy evaluation: * [Configure a policy](#idp-adapter-policy) * [Create the script](#create-idp-adapter) * [Configure the IdP](#use-idp-adapter) * [Test the script](#try-idp-adapter) ### Configure a policy 1. Under Native Consoles > Access Management, go to Realms > *Realm Name* > Authorization > Resource Types and create a [new resource type](../am-authorization/resource-types-ui.html) with the following settings: * Name `SAML SP Access` * Pattern `*` * Action `Assert` (Default State: `Deny`) 2. Go to Policy Sets and create a [new policy set](../am-authorization/policy-sets-ui.html) with the following settings: * Id `saml` * Name `saml` * Resource Types `SAML SP Access` 3. Add a [new policy](../am-authorization/policies-ui.html) with the following settings: * Name `SAML Access Policy` * Resource Types `SAML SP Access` * Resources `*` * Actions `ASSERT:Denied` * Response Attributes `redirect_uri: https://example.com` * Subjects `"type": "AuthenticatedUsers"` ### Create the script 1. In the Advanced Identity Cloud admin console, [create a legacy script](../developer-docs/scripting-auth.html#create-a-new-auth-script) of type SAML2 IDP Adapter. 2. In the JavaScript field, paste the template [SAML2 IDP Adapter Script](../am-scripting/sample-scripts.html#saml2-idp-adapter-js). 3. Insert the following code in the `preSendResponse` function. The script causes Advanced Identity Cloud to redirect or send an error response if the policy for the SP evaluates to false: ```javascript function preSendResponse() { var frJava = JavaImporter( com.sun.identity.saml2.common.SAML2Exception); try { // set realm DN if you want to use an LDAP filter condition in the SAML access policy var env = new java.util.HashMap(); var realmDn = new java.util.HashSet(); realmDn.add("dc=am,dc=example,dc=com"); env.put("am.policy.realmDN", realmDn); var subject = idpAdapterScriptHelper.getSubjectForToken(session); var resources = idpAdapterScriptHelper.getResourcesForToken(authnRequest); var ents = idpAdapterScriptHelper.getEntitlements( "saml", realm, subject, resources, env).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); } } ``` 4. Save your changes and close the editor. ### Configure the IdP 1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > *Hosted IDP Name* > Advanced. 2. In the IDP Adapter Script field, select your script. 3. Save your changes. ### Test the script 1. Perform an SP-initiated flow. 2. Verify the user is redirected to the `redirect_uri` from the policy (`https://example.com`). ## Set a custom header using a next-generation script The following example sets a custom header using the next-generation binding, `responseHelper`: * [Create the script](#create-idp-adapter-ng) * [Configure the IdP](#use-idp-adapter-ng) * [Test the script](#try-idp-adapter-ng) ### Create the script 1. Under Native Consoles > Access Management, go to Realms > *Realm Name* > Scripts, and click +New Script. 2. Provide a suitable name for your script and select the following values: * Script Type `Saml2 IDP Adapter` * Evaluator Version `Next Generation` 3. Click Create. 4. In the Script field, paste the template [SAML2 IDP Adapter Script (Next Gen)](../am-scripting/sample-scripts.html#saml2-idp-adapter-nextgen-js). 5. Replace the `preSendFailureResponse` function with the following script: ```java function preSendFailureResponse() { // set custom header in event of failure try { if (responseHelper) { responseHelper.setHeader("CUSTOM-SAML-FAILURE", "true"); } } catch (e) { logger.error("Error in preSendFailureResponse: " + e.message); } logger.error("CUSTOM-SAML-FAILURE response header set"); } ``` 6. Validate and save your changes. ### Configure the IdP 1. Configure Advanced Identity Cloud to use the updated IdP adapter script: 1. Go to Applications > Federation > Entity Providers > *hosted IdP* > Advanced. 2. Select your custom next-generation script from the IDP Adapter Script list. 3. Save your changes. ### Test the script 1. Test your changes using an SP-initiated flow that ends in failure. 2. Verify that the response contains the custom header, for example: ```bash HTTP/1.1 500 X-Frame-Options: SAMEORIGIN ... CUSTOM-SAML-FAILURE: true ... ```