PingAM

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 interface.

  3. Add code to one or more of the methods described in the extension points table 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.

  • 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.

  1. In the AM admin UI, go to Realms > Realm Name > Scripts, and click SAML2 SP Adapter Script. Alternatively, create a new script 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:

    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 Name > 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.