--- title: SP adapter description: Customize SAML 2.0 service provider authentication and assertion processing using plugin hooks in PingAM component: pingam version: 7.5 page_id: pingam:am-saml2:plugins-sp-adapter canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/custom-sp-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 keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Customization", "Java", "Scripts"] page_aliases: ["saml2-guide:plugins-sp-adapter.adoc"] section_ids: java_implementation: Java implementation scripted_implementation: Scripted implementation customize_the_sp_adapter_script: Customize the SP adapter script scripting-api-sp-adapter: SP adapter scripting API --- # SP adapter Use this plugin to make changes during the processing of the authentication request, such as updating the `SPNameQualifier` attribute, or during assertion processing after a response has been received. The plugin provides hooks at the following points: | Plugin point | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------- | | preSingleSignOnRequest | Invoked before AM sends the single sign-on request to the IDP. | | preSingleSignOnProcess | Invoked before single sign-on processing begins on the SP side, when AM 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 user session is still valid. | | postSingleLogoutProcess | Invoked after the single logout process succeeds, when the user session has been invalidated. | ## Java implementation To create a custom SP 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 [org.forgerock.openam.saml2.plugins.SPAdapter](../_attachments/apidocs/org/forgerock/openam/saml2/plugins/SPAdapter.html) interface. 3. Add code to one or more of the methods described in the [plugin points table](#sp-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 SP* > Assertion Processing. 2. In the Adapter 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. ## Scripted implementation To explore the default script, including the available script properties, refer to [saml2-sp-adapter.js](../am-scripting/sample-scripts.html#saml2-sp-adapter-js). To view or modify the default script in the AM admin UI, go to Realms > *realm name* > Scripts and select SAML2 SP Adapter Script. ### Customize the SP adapter script Complete the following steps to implement an example SP adapter script that updates the `SPNameQualifier` attribute in the authentication request. If you prefer to create a new script, reference the new script name when you configure the hosted entity provider. For more information, refer to [Manage scripts (UI)](../am-scripting/manage-scripts-console.html). This task assumes your environment is already correctly configured for single sign-on using SAML 2.0, where AM is the hosted SP. 1. In the AM admin UI, go to Realms > *realm name* > Scripts, and click SAML2 SP Adapter Script. 2. In the Script field, 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; } ``` 3. Validate and save your changes. 4. Configure AM to use the updated SP adapter script. 1. In the AM admin UI, go to Realms > *realm name* > Applications > Federation > Entity Providers > *hosted SP* > Assertion Processing. 2. In the Adapter Script field, select SAML2 SP Adapter Script. Alternatively, if you created a script rather than modifying the default, select the new script name. 3. Save your changes. 5. Test your changes using an SP-initiated flow. 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. ## SP adapter scripting API The following properties are available to SP adapter scripts, in addition to the [common SAML 2.0 properties](customize-saml2-plugins.html#scripting-api-saml2). | Binding | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `authnRequest` | The original authentication request sent from the SP.Only available to single sign-on functions.Refer to [AuthnRequest](../_attachments/apidocs/com/sun/identity/saml2/protocol/AuthnRequest.html). | | `binding` | The binding used for the name identifier request: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect` or `urn:oasis:names:tc:SAML:2.0:bindings:SOAP`Not available to single sign-on functions. | | `failureCode` | The failure code associated with the error that has occurred. For possible values, refer to [SPAdapter](../_attachments/apidocs/org/forgerock/openam/saml2/plugins/SPAdapter.html).Only available to `preSendFailureResponse`. | | `idpEntityID` | The entity ID for the IDP that sends the sign-on request. | | `idRequest` | The [ManageNameIDRequest](../_attachments/apidocs/com/sun/identity/saml2/protocol/ManageNameIDRequest.html) object for the name identifier request.Only available to `postNewNameIDSuccess` and `postTerminateNameIDSuccess`. | | `idResponse` | The [ManageNameIDResponse](../_attachments/apidocs/com/sun/identity/saml2/protocol/ManageNameIDResponse.html) object for the name identifier request.Only available to `postNewNameIDSuccess` and `postTerminateNameIDSuccess`. | | `isFederation` | A boolean indicating whether federation is True if using federation, otherwise false.Only available to the `postSingleSignOnSuccess` function. | | `logoutRequest` | The single logout [LogoutRequest](../_attachments/apidocs/com/sun/identity/saml2/protocol/LogoutRequest.html).Only available to `preSingleLogoutProcess` and `postSingleLogoutProcess`. | | `logoutResponse` | The single logout [LogoutResponse](../_attachments/apidocs/com/sun/identity/saml2/protocol/LogoutResponse.html).Only available to `preSingleLogoutProcess` and `postSingleLogoutProcess`. | | `out` | The [PrintWriter](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/PrintWriter.html) for writing to.Only available to `postSingleSignOnSuccess`. | | `profile` | The protocol profile used: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`, `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact` or `urn:oasis:names:tc:SAML:2.0:bindings:PAOS`.Available to `preSingleSignOnProcess`, `postSingleSignOnSuccess`, and `postSingleSignOnFailure`. | | `request` | The [HttpServletRequest](https://tomcat.apache.org/tomcat-7.0-doc/servletapi/javax/servlet/http/HttpServletRequest.html) object.Always present. | | `response` | The [HttpServletResponse](https://tomcat.apache.org/tomcat-7.0-doc/servletapi/javax/servlet/http/HttpServletResponse.html) object.Always present. | | `session` | Contains a representation of the user's single sign-on session object. Refer to the [SSOToken](../_attachments/apidocs/com/iplanet/sso/SSOToken.html) interface for information about SSO token and authentication information, as well as session-related properties.Only available to `postSingleSignOnSuccess`. | | `spAdapterScriptHelper` | The [SpAdapterScriptHelper](../_attachments/apidocs/com/sun/identity/saml2/plugins/scripted/SpAdapterScriptHelper.html) instance contains supporting methods that provide context information when customizing the SP adapter plugin points.Always present. | | `res` | The SSO Response received from the IdP.Available to `preSingleSignOnProcess`, `postSingleSignOnSuccess`, and `postSingleSignOnFailure`. | | `userId` | The unique universal ID of the user associated with the request.Not available to single sign-on functions. |