Use IDP adapter to alter authentication request process

Use this script type to alter the processing of the authentication request; for example, redirect the user before single sign-on, or before sending a failure response.

The script provides hooks at the following points in assertion processing:

Processing phase Description

Processing phase	Description
`preSingleSignOn`	Invoked when Identity Cloud receives the authentication request. Only applicable to SP-initiated flows.
`preAuthentication`	Invoked before redirecting the request for authentication. Only applicable to SP-initiated flows.
`preSendResponse`	Invoked after the user successfully authenticates or makes the request with an existing valid session, and before the response is sent.
`preSignResponse`	Invoked after Identity Cloud prepares the response, but before it signs the response. This lets you customize the content of the SAML response.
`preSendFailureResponse`	Invoked before Identity Cloud returns a SAML error response. Only applicable to SP-initiated flows.

preSingleSignOn

Invoked when Identity Cloud receives the authentication request. Only applicable to SP-initiated flows.

preAuthentication

Invoked before redirecting the request for authentication. Only applicable to SP-initiated flows.

preSendResponse

Invoked after the user successfully authenticates or makes the request with an existing valid session, and before the response is sent.

preSignResponse

Invoked after Identity Cloud prepares the response, but before it signs the response. This lets you customize the content of the SAML response.

preSendFailureResponse

Invoked before Identity Cloud returns a SAML error response. Only applicable to SP-initiated flows.

For a template script, refer to saml2-idp-adapter.js.

Demonstrate an IDP adapter

Before you try the example, configure single sign-on using SAML v2.0 with Identity Cloud as the hosted IDP.

The following example determines whether to redirect the authentication journey based policy evaluation:

Configure a policy
Create the script
Configure the IDP
Test the script

Configure a policy

In the AM admin UI, go to Realms > Realm Name > Authorization > Resource Types and create a new resource type with the following settings:

Name

SAML SP Access

Pattern

*

Action

Assert (Default State: Deny)
Go to Policy Sets and create a new policy set with the following settings:

Id

saml

Name

saml

Resource Types

SAML SP Access
Add a new policy with the following settings:

Name

SAML Access Policy

Resource Types

SAML SP Access

Resources

*

Actions

ASSERT:Denied

Response Attributes

redirect_uri: https://example.com

Subjects

"type": "AuthenticatedUsers"

Create the script

In the AM admin UI, go to Realms > Realm Name > Scripts, click + New Script, add these settings, and click Create:

Name

A unique name for your script

Script Type

Scroll down to select Saml2 IDP Adapter
In the Script text field for the new script, paste the template saml2-idp-adapter.js script.

Insert the following code in the preSendResponse function. The script causes Identity Cloud to redirect or send an error response if the policy for the SP evaluates to false:

function preSendResponse() {

  var frJava = JavaImporter(
    com.sun.identity.saml2.common.SAML2Exception);

  try {
    var ents = idpAdapterScriptHelper.getEntitlements(
      "saml", realm, session, authnRequest).iterator();
    while (ents.hasNext()) {
      var entitlement = ents.next();
      var isAllowed = entitlement.getActionValue("Assert");

      if (isAllowed != null && isAllowed == true) {
        return false;
      } else {
        var redirectUris = entitlement.getAttributes().get("redirect_uri");

        if (redirectUris == null || redirectUris.isEmpty()) {
          logger.error("No redirect_uri");
          response.sendError(403);
        } else {
          var redirectUri = redirectUris.iterator().next();
          response.sendRedirect(redirectUri);
        } return true;
      }
    }
  } catch (error) {
    logger.error("Error in preSend reponse. " + error);
    throw new frJava.SAML2Exception(error);
  }
}

Click Validate, make any necessary corrections, and click Save Changes.

Configure the IDP

In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted IDP Name > Advanced.
In the IDP Adapter Script field, select your script.
Save your changes.

Test the script

Perform an SP-initiated flow.
Verify the user is redirected to the redirect_uri from the policy (https://example.com).

Available objects

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

Binding Information

Binding	Information
`authnRequest`	The original authentication request from the SP. For details, refer to AuthnRequest. Not available to the `preSendFailureResponse` function.
`faultCode`	The fault code in the SAML response. Only available to the `preSendFailureResponse` function.
`faultDetail`	The details of the fault in the SAML response. Only available to the `preSendFailureResponse` function.
`hostedEntityId`	The entity ID for the hosted IDP.
`idpAdapterScriptHelper`	An object with methods to provide context when customizing the IDP adapter plugin points. For details, refer to IdpAdapterScriptHelper.
`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.
`realm`	The realm the user authenticates to.
`relayState`	A String representing the `relayState` in the redirect. Not available to the `preSingleSignOn` or `preSendFailureResponse` functions.
`reqId`	The identifier to continue processing if the adapter redirects. Not available to the `preSignResponse` or `preSendFailureResponse` functions.
`request`	The `HttpServletRequest` object.
`res`	The SAML response. For details, refer to Response. Only available to the `preSignResponse` function.
`response`	The `HttpServletResponse` object. Not available to the `preSignResponse` function.
`session`	Represents the user’s single sign-on session object. For details, refer to SSOToken. Not available to the `preSingleSignOn` or `preSendFailureResponse` functions.

authnRequest

The original authentication request from the SP. For details, refer to AuthnRequest.

Not available to the preSendFailureResponse function.

faultCode

The fault code in the SAML response.

Only available to the preSendFailureResponse function.

faultDetail

The details of the fault in the SAML response.

Only available to the preSendFailureResponse function.

hostedEntityId

The entity ID for the hosted IDP.

idpAdapterScriptHelper

An object with methods to provide context when customizing the IDP adapter plugin points. For details, refer to IdpAdapterScriptHelper.

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.

realm

The realm the user authenticates to.

relayState

A String representing the relayState in the redirect.

Not available to the preSingleSignOn or preSendFailureResponse functions.

reqId

The identifier to continue processing if the adapter redirects.

Not available to the preSignResponse or preSendFailureResponse functions.

request

The HttpServletRequest object.

res

The SAML response. For details, refer to Response.

Only available to the preSignResponse function.

response

The HttpServletResponse object.

Not available to the preSignResponse function.

session

Represents the user’s single sign-on session object. For details, refer to SSOToken.

Not available to the preSingleSignOn or preSendFailureResponse functions.