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:
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. |
For a template script, including the available script properties, refer to 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.
-
In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP Name > Advanced.
-
In the IDP Adapter Script field, select the script you created.
-
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.Refer to 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.
Refer to the idpAdapterScriptHelper interface.
Always present.
relayState
-
A String representing the relayState used in the redirect.
Not available to the
preSingleSignOn
orpreSendFailureResponse
functions. reqId
-
The id to use for continuation of processing if the adapter redirects.
Not available to the
preSignResponse
orpreSendFailureResponse
functions. request
-
The
HttpServletRequest
object. Always present. res
-
The SAML response. For information, refer to 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. Refer to the SSOToken interface for information about SSO token and authentication information, as well as session-related properties.
Not available to the
preSingleSignOn
orpreSendFailureResponse
functions.