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 SSO 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 SSO request to the IdP.

preSingleSignOnProcess

Invoked before SSO processing begins on the SP side, when AM receives the response from the IdP.

postSingleSignOnSuccess

Invoked when SSO processing succeeds.

postSingleSignOnFailure

Invoked when SSO 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 SLO process starts on the SP side, while the authenticated session is still valid.

postSingleLogoutProcess

Invoked after the SLO process succeeds when the authenticated session has been invalidated.

Java example

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 examples

Learn about SP adapter scripts from the following resources:

Legacy example script

SAML2 SP Adapter Script

Next-generation example script

SAML2 SP Adapter Script (Next Gen)

Scripting API

SP adapter scripting API

Redirect a journey using a legacy script

Complete the following steps to implement an example SP adapter script that updates the SPNameQualifier attribute in the authentication request.

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

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.

  1. In the AM admin UI, create a new script on the hosted SP with the following values:

    Name

    Example Next-Generation SP Adapter

    Script Type

    Saml2 SP Adapter

    Evaluator Version

    Next Generation

  2. In the Script field, replace the postSingleSignOnSuccess function with the following script:

    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;
}

  3. On the remote IdP, 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.

  4. Update a test user and set their address to UK:

    1. Click Identities > test user and set the following attribute:

      Home Address

      UK

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