Use SP adapter to alter authentication request processing

Use this script type to make application-specific changes during the processing of the authentication request on the SP side, such as updating the SPNameQualifier attribute.

The script provides hooks at the following points:

Processing phase Description

Processing phase	Description
`preSingleSignOnRequest`	Invoked before Identity Cloud sends the single sign-on request to the IDP.
`preSingleSignOnProcess`	Invoked before single sign-on processing begins on the SP side, when Identity Cloud 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.

preSingleSignOnRequest

Invoked before Identity Cloud sends the single sign-on request to the IDP.

preSingleSignOnProcess

Invoked before single sign-on processing begins on the SP side, when Identity Cloud 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.

Demonstrate an SP adapter

This task assumes your environment is already correctly configured for single sign-on using SAML v2.0, where Identity Cloud is the hosted SP.

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

Create the script
Configure the SP
Test the script

Create the script

Under Native Consoles > Access Management, go to Realms > Realm Name > Scripts, and click +New Script.
Enter a unique name for your script, select Saml2 SP Adapter from the Script Type drop-down list, and click Create.
Copy the saml2-sp-adapter.js script and paste in the Script field.

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

Validate and save your changes.

Configure the SP

Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted SP Name > Assertion Processing.
In the Adapter Script field, select the script you created.
Save your changes.

Test the script

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.

Available objects

Identity Cloud injects the following objects into the execution context of an SP adapter script:

Binding Information

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.

Possible values

Constant	Value
`SUCCESS`	0
`INVALID_RESPONSE`	1
`FEDERATION_FAILED_WRITING_ACCOUNT_INFO`	3
`SSO_FAILED_SESSION_ERROR`	4
`SSO_FAILED_ATTRIBUTE_MAPPING`	5
`SSO_FAILED_NO_USER_MAPPING`	6
`SSO_FAILED_AUTH_USER_INACTIVE`	7
`SSO_FAILED_AUTH_USER_LOCKED`	8
`SSO_FAILED_AUTH_ACCOUNT_EXPIRED`	9
`SSO_FAILED_SESSION_GENERATION`	10
`SSO_FAILED_META_DATA_ERROR`	11

Only available to preSendFailureResponse.

hostedEntityId

The entity ID for the hosted IDP.

idpEntityID

The identifier of the IDP for which the sign-on request is sent.

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 used, otherwise false.

Only available to the postSingleSignOnSuccess function.

logger

Write a message to the Identity Cloud am-core log source. The logger identifier takes the form scripts.script-type.script-id. For details, refer to Debug.

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.

realm

The realm the user authenticates to.

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 object contains supporting methods that provide context information when customizing the SP adapter plugin points.

Always present.

SsoResponse

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.