--- title: SP adapter description: Implement SP adapters in Java or scripts to customize SAML 2.0 authentication request processing and assertion handling in PingAM component: pingam version: 8 page_id: pingam:am-saml2:custom-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 revdate: 2026-06-01T14:34:20Z keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Customization", "Java", "Scripts"] page_aliases: ["plugins-sp-adapter.adoc", "saml2-guide:custom-sp-adapter.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/am-saml2/custom-sp-adapter.html section_ids: java_implementation: Java implementation scripted_implementation: Scripted implementation --- # SP adapter Use the SP adapter 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. These steps assume your environment is already correctly configured for single sign-on using SAML 2.0, where AM is the hosted SP. The SP adapter provides hooks at the following points: | Extension 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 authenticated session is still valid. | | postSingleLogoutProcess | Invoked after the single logout process succeeds when the authenticated 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 [extension 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 Complete the following steps to implement an example SP adapter script that updates the `SPNameQualifier` attribute in the authentication request. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Learn about SP adapter scripts from the following resources:- To view the default script, refer to [saml2-sp-adapter.js](../am-scripting/sample-scripts.html#saml2-sp-adapter-js). - To modify the default script, go to Realms > *realm name* > Scripts and select SAML2 SP Adapter Script. - To view the available bindings, refer to the [SP adapter scripting API](../am-scripting/saml2-sp-adapter-api.html). | 1. In the AM admin UI, go to Realms > *realm name* > Scripts, and click SAML2 SP Adapter Script. Alternatively, [create a new script](../am-scripting/manage-scripts-console.html) of type `Saml2 SP Adapter`. 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. Under Adapter, select your customized script from the Adapter Script drop-down list. 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.