IDP adapter plugin

Use this plugin to alter the processing of the authentication request at a particular point in the SAML journey, such as to redirect the user before single sign-on takes place, or before a failure response is sent.

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

Table 1. IDP Adapter Plugin Points
Plugin point	Description
preSingleSignOn	Invoked when the authentication request is first received. Only applicable to SP-initiated flows.
preAuthentication	Invoked before the request is redirected for authentication. Only applicable to SP-initiated flows.
preSendResponse	Invoked after the user has successfully authenticated or for an existing valid session, before the response is sent.
preSignResponse	Invoked after the response has been constructed, but before the response is signed, to let you customize the content of the SAML response.
preSendFailureResponse	Invoked before a SAML error response is returned. Only applicable to SP-initiated flows.

To view a template script, including the available script properties, see saml2-idp-adapter.js.

Create a custom IDP adapter script

Complete the following steps to implement an example IDP adapter script that determines whether the authentication journey should be redirected, based on the evaluation of a policy.

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

You will also need to configure a policy that belongs to a policy set named saml, and has the following example configuration:

Actions: ASSERT:Denied
Response Attributes: redirect_uri: https//example.com
Subjects: "type": "AuthenticatedUsers"

In the AM admin UI, go to Realms > Realm Name > Scripts, and click New Script.
Enter a unique name for your script, select SAML2 IDP Adapter from the Script Type drop-down list, and click Create.
Copy the saml2-idp-adapter.js script and paste in the Script field.

Insert the following code for the preSendResponse function to redirect or send an error response if the policy for the SP evaluates to false. For example:

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

Validate and save your changes.
Configure AM to use the updated IDP adapter script.
1. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP Name > Advanced.
2. In the IDP Adapter Script field, select the script you created.
3. Save your changes.
Test your changes using an SP-initiated flow and verify that the user is redirected to the redirect_uri (in this example, https://example.com).

IDP adapter scripting API

The following properties are available to IDP adapter scripts, in addition to the common SAML v2.0 properties.

Show script properties

authnRequest: The original authentication request sent from the SP. Not available to the preSendFailureResponse function.

See AuthnRequest.
faultCode: The fault code returned in the SAML response.

Only available to the preSendFailureResponse function.
faultDetail: Contains the details of the fault returned in the SAML response.

Only available to the preSendFailureResponse function.
idpAdapterScriptHelper: The IdpAdapterScriptHelper instance contains supporting methods that provide context information when customizing the IDP adapter plugin points.

See the idpAdapterScriptHelper interface.

Always present.
relayState: A String representing the relayState used in the redirect.

Not available to the preSingleSignOn or preSendFailureResponse functions.
reqId: The id to use for continuation of processing if the adapter redirects.

Not available to the preSignResponse or preSendFailureResponse functions.
request: The HttpServletRequest object. Always present.
res: The SAML response. For information, see Response.

Only available to the preSignResponse function.
response: The HttpServletResponse object.

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

Not available to the preSingleSignOn or preSendFailureResponse functions.

Identity Cloud

IDP adapter plugin

Create a custom IDP adapter script

IDP adapter scripting API