Access Management 7.3.2

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

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

To explore the default script, including the available script properties, refer to 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).

This task assumes your environment is already correctly configured for single sign-on using SAML v2.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:

    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. 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 v2.0 properties.

Binding Description

authnRequest

The original authentication request sent from the SP.

Only available to single sign-on functions.

Refer to AuthnRequest.

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.

Only available to preSendFailureResponse.

idpEntityID

The entity ID for the IDP that sends the sign-on request.

idRequest

The ManageNameIDRequest object for the name identifier request.

Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

idResponse

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

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

logoutResponse

The single logout LogoutResponse.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

out

The PrintWriter 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 object.

Always present.

response

The HttpServletResponse object.

Always present.

session

Contains a representation of the user’s single sign-on session object. Refer to the SSOToken interface for information about SSO token and authentication information, as well as session-related properties.

Only available to postSingleSignOnSuccess.

spAdapterScriptHelper

The SpAdapterScriptHelper instance contains supporting methods that provide context information when customizing the SP adapter plugin points.

Always present.

ssoResponse

The SSO Response received from the Identity Provider.

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.