Scripting API

AM provides the following scriptable extension points:

Scripted decision node API

This extension point lets you write a script to determine the path of an authentication journey. The script provides bindings for accessing data in request headers, shared state, and user session data. This data helps to provide the context for you to decide the possible paths a user could take.

For more information, refer to the scripted decision node API.

Scripted policy condition API

Use this scriptable extension point to tailor the actions that AM takes as part of policy evaluation. The script lets you access a user’s profile information, use that information in HTTP calls, and make a policy decision based on the outcome.

For a sample script, refer to policy-condition.js.

For more information, refer to scripted policy conditions.

OAuth 2.0 scripts

Extend authorization server behavior with the OAuth 2.0 scripts:

Access token modification

Modify the key-value pairs contained within an OAuth 2.0 access token.

For a sample script, refer to oauth2-access-token-modification.js.
Authorize endpoint data provider

Return additional data from an authorization request.

For a sample script, refer to oauth2-authorize-endpoint-data-provider.js.
Scope evaluator

Evaluate and return an OAuth 2.0 access token’s scope information.

For a sample script, refer to oauth2-evaluate-scope.js.
Scope validator

Customize the set of requested scopes for authorize, access token, refresh token, and back channel authorize requests.

For a sample script, refer to oauth2-validate-scope.js.
OIDC claims

Populate claims in a request when issuing an ID token or making a request to the OpenID Connect userinfo endpoint.

For a sample script, refer to oidc-claims-extension.js.

For information about configuring the OAuth 2.0 scripts, refer to the OAuth2 provider configuration.

SAML v2.0 scripts

Customize your SAML v2.0 single sign-on implementation with the SAML v2.0 scripts:

IDP adapter

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

For a sample script, refer to saml2-idp-adapter.js.
IDP attribute mapper

Map user-configured attributes to SAML attribute objects to insert into the generated SAML assertion.

For a sample script, refer to saml2-idp-attribute-mapper.js.

Reference substituted properties in scripts

The systemEnv binding, available to all AM script types, includes an instance of the ScriptPropertyResolver class. This interface exposes the following methods:

String getProperty(String propertyName);
String getProperty(String propertyName, String defaultValue);

where:

propertyName is the configuration expressions, for example, email.from.address
defaultValue is the default value set for that property in the configuration expression

To reference a substituted property in a script, the property name must include a specific prefix. This prefix decreases the risk that random property values are resolved in scripts. Because property value substitution is often used to change secrets, you must be intentional about which properties you want to be able to resolve in scripts. The default prefix, for all script types, is script. You can change this prefix in the script type configuration. Select Configure > Global Services > Scripting > Secondary Configurations > Script Type > Secondary Configurations > Engine Configuration > Property Name Prefix.

Example: Property value resolution in a scripted decision node

These examples assume that the property name prefix script has been set in the script engine configuration for this script type. The scripts are used in a scripted decision node to get the values of the user’s email, hostname, port, and so on. The scripts also show type transformation where the type is not a string.

// Properties should get resolved (set in AM)
var email = systemEnv.getProperty('script.tree.decision.node.email');
var name = systemEnv.getProperty('script.tree.decision.node.hostname', 'defaultHostname');
var port = systemEnv.getProperty('script.tree.decision.node.port', '587', java.lang.Integer);
var double = systemEnv.getProperty('script.tree.decision.node.double, '2.0', java.lang.Double);
var hasPort = systemEnv.getProperty('script.tree.decision.node.hasPort', 'false', java.lang.Boolean);
var map = systemEnv.getProperty('script.tree.decision.node.map', '{"defaultKey":"defaultValue"}', java.util.Map);
var list = systemEnv.getProperty('script.tree.decision.node.list', 'defaultValue', java.util.List);

// Properties should get resolved to their defaults (not set in AM)
var defaultName = systemEnv.getProperty('script.tree.decision.node.hostname.unresolved', 'defaultHostname');
var defaultPort = systemEnv.getProperty('script.tree.decision.node.port.unresolved', '587', java.lang.Integer);
var defaultDouble = systemEnv.getProperty('script.tree.decision.node.double.unresolved', '2.0', java.lang.Double);
var defaultHasPort = systemEnv.getProperty('script.tree.decision.node.hasPort.unresolved', 'false', java.lang.Boolean);
var defaultMap = systemEnv.getProperty('script.tree.decision.node.map.unresolved', '{"defaultKey":"defaultValue"}', java.util.Map);
var defaultList = systemEnv.getProperty('script.tree.decision.node.list.unresolved', 'defaultFirstValue,defaultSecondValue', java.util.List);

// Assert all property values - set the appropriate outcome
if (email === 'test@example.com' && name === 'testHostname' && port === 25 && double === 1.0 && hasPort === true
    && map.get('testKey') == 'testValue' && list == '[testFirstValue, testSecondValue]'

Identity Cloud