--- title: SP adapter description: Use this script type to make application-specific changes during the processing of the authentication request on the SP side, such as updating the SPNameQualifier attribute. component: pingoneaic page_id: pingoneaic:am-saml2:custom-sp-adapter canonical_url: https://docs.pingidentity.com/pingoneaic/am-saml2/custom-sp-adapter.html keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Customization", "Scripts"] page_aliases: ["saml2-guide:plugins-sp-adapter.adoc", "plugins-sp-adapter.adoc"] section_ids: example-sp-adapter: Update authentication request using a legacy script create-sp-adapter-script: Create the script configure-sp: Configure the SP test-sp-adapter-script: Test the script example-sp-adapter-ng: Set session properties using a next-generation script create-sp-adapter-ng: Create the script use-sp-adapter-ng: Configure the IdP try-sp-adapter-ng: Test the script --- # SP adapter Use this script type to make application-specific changes during the processing of the authentication request on the SP side, such as updating the `SPNameQualifier` attribute. * Next-generation example script [SAML2 SP Adapter Script (Next Gen)](../am-scripting/sample-scripts.html#saml2-sp-adapter-nextgen-js) * Legacy example script [SAML2 SP Adapter Script](../am-scripting/sample-scripts.html#saml2-sp-adapter-js) * Script bindings [SP adapter scripting API](../am-scripting/saml2-sp-adapter-api.html) The script provides hooks at the following points: | Processing phase | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `preSingleSignOnRequest` | Invoked before Advanced Identity Cloud sends the single sign-on request to the IDP. | | `preSingleSignOnProcess` | Invoked before single sign-on processing begins on the SP side, when Advanced Identity Cloud receives the response from the IDP. | | `postSingleSignOnSuccess` | Invoked when single sign-on processing succeeds. | | `postSingleSignOnFailure` | Invoked when single sign-on processing fails. | | `postNewNameIDSuccess` | Invoked when the processing of a new name identifier succeeds. | | `postTerminateNameIDSuccess` | Invoked when the association of a name identifier between an SP and IDP is successfully terminated. | | `preSingleLogoutProcess` | Invoked before the single logout process starts on the SP side, while the authenticated session is still valid. | | `postSingleLogoutProcess` | Invoked after the single logout process succeeds when the authenticated session has been invalidated. | ## Update authentication request using a legacy script This task assumes your environment is already correctly configured for single sign-on using SAML 2.0, where Advanced Identity Cloud is the hosted SP. Complete the following steps to implement an example SP adapter script that updates the `SPNameQualifier` attribute in the authentication request: * [Create the script](#create-sp-adapter-script) * [Configure the SP](#configure-sp) * [Test the script](#test-sp-adapter-script) ### Create the script 1. In the Advanced Identity Cloud admin console, [create a script](../developer-docs/scripting-auth.html#create-a-new-auth-script) of type SAML2 SP Adapter. 2. In the JavaScript field, paste the template [SAML2 SP Adapter Script](../am-scripting/sample-scripts.html#saml2-sp-adapter-js). 3. Copy the [SAML2 SP Adapter Script](../am-scripting/sample-scripts.html#saml2-sp-adapter-js) and paste in the JavaScript field. 4. Add code to the `preSingleSignOnRequest` function to change the value of `SPNameQualifier` in the authentication request. Optionally, add code to redirect a successful login in the `postSingleSignOnSuccess` function. For example: ```javascript function preSingleSignOnRequest() { logger.error("In preSingleSignOnRequest"); authnRequest.getNameIDPolicy().setSPNameQualifier("mySP-Updated"); } function postSingleSignOnSuccess() { logger.error("In postSingleSignOnSuccess"); response.sendRedirect("https://example.com"); return true; } ``` 5. Save your changes and close the editor. ### Configure the SP 1. Under Native Consoles > Access Management, go to Realms > *Realm Name* > Applications > Federation > Entity Providers > *Hosted SP Name* > Assertion Processing. 2. In the Adapter Script field, select the script you created. 3. Save your changes. ### Test the script 1. Test your changes using an SP-initiated flow. 2. Verify that the SAML2.0 request contains the updated value (`SPNameQualifier="mySP-Updated"`) and that the user is redirected to `https://example.com` on successful login. ## Set session properties using a next-generation script This example uses a next-generation script to set SAML attributes in the current session and conditionally redirects the authenticated user to a website: * [Create the script](#create-sp-adapter-ng) * [Configure the IdP](#use-sp-adapter-ng) * [Test the script](#try-sp-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 SP Adapter` * Evaluator Version `Next Generation` 3. Click Create. 4. In the Script field, paste the template [SAML2 SP Adapter Script (Next Gen)](../am-scripting/sample-scripts.html#saml2-sp-adapter-nextgen-js). 5. Replace the `postSingleSignOnSuccess` function with the following script: ```javascript function postSingleSignOnSuccess() { var redirectOccurred = false; try { if (!ssoResponse || !session) { logger.error("Missing ssoResponse or session object."); return false; } // Set response attributes as session properties var issueInstant = ssoResponse.issueInstant; var issuer = ssoResponse.issuer ? ssoResponse.issuer.value : "Unknown"; session.setProperty("issueInstant", issueInstant); session.setProperty("issuer", issuer); logger.info("[issueInstant]: " + issueInstant + " [issuer]: " + issuer); // get address from assertion's attribute statement var assertion = ssoResponse.assertion[0]; if (assertion && assertion.attributeStatements) { var statements = assertion.attributeStatements; for (var i = 0; i < statements.length; i++) { var attributes = statements[i].attribute; if (attributes && attributes.length > 0) { // Look for the 'Address' attribute for (var j = 0; j < attributes.length; j++) { if (attributes[j].name === "Address") { var addressValue = attributes[j].attributeValueString; if (addressValue && addressValue.length > 0) { var address = addressValue[0]; logger.info("[postaladdress]: " + address); session.setProperty("address", address); // Redirect based on SAML address attribute if (responseHelper) { if (address === 'UK') { responseHelper.sendRedirect("https://loremipsum.io/"); } else { responseHelper.sendRedirect("https://example.com/"); } redirectOccurred = true; } return redirectOccurred; } } } } } } } catch (e) { logger.error("Error in postSingleSignOnSuccess: " + e.toString()); } return redirectOccurred; } ``` ### Configure the IdP 1. Configure Advanced Identity Cloud to use the updated SP adapter script: 1. Go to Applications > Federation > Entity Providers > *hosted IdP* > Advanced. 2. Select your custom next-generation script from the SP Adapter Script list. 3. Save your changes. 2. Map the attributes required for the script: 1. Go to Realms > *realm name* > Applications > Federation > Entity Providers > *hosted IdP* > Assertion Processing. 2. Add the following mapping to the Attribute Map: * SAML Attribute `Address` * Local Attribute `postaladdress` 3. Save your changes. 3. Update a test user and set their address to `UK`: 1. Click Identities > *test user* and set the following attribute: * Home Address `UK` ### Test the script 1. To test your changes, perform an SP-initated SSO flow using your UK test user. Verify that the user is redirected to `https://loremipsum.io` and that the logging output contains values for the SSO response attributes, for example: `INFO: [issueInstant]: 1770649129000 [issuer]: identityprovider1` `INFO: [postaladdress]: UK`