Scripting API

AM provides the following scriptable extension points.

Client-side authentication

Run a script in the user-agent to capture additional information during authentication.

Not used in Identity Cloud.

Configuration provider scripts

Build a configuration map with custom values and add it to the authentication flow.

An authentication journey calls the script through a Configuration Provider node.

For a sample script, refer to config-provider-node.js.

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.

The AM OAuth 2.0 provider service calls the script you configure:

In AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select your script in the Access Token Modification Script drop-down.

For a sample script, refer to oauth2-access-token-modification.js.

Authorize endpoint data provider

Return additional data from an authorization request.

The AM OAuth 2.0 provider service calls the script you configure:

In AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select SCRIPTED in the Authorize Endpoint Data Provider Plugin Type drop-down.
Select your script in the Authorize Endpoint Data Provider Script drop-down.

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

May act

Add a may_act claim for delegation or impersonation when performing token exchange.

For details, refer to the section on authorizing token exchange.

For a sample script, refer to oauth2-may-act.js.

OIDC claims

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

The AM OAuth 2.0 provider service calls the script you configure:

In AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select your script in the OIDC Claims Script drop-down.

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

Scope evaluator

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

The AM OAuth 2.0 provider service calls the script you configure:

In AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select SCRIPTED in the Scope Evaluation Plugin Type drop-down.
Select your script in the Scope Evaluation Provider Script drop-down.

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.

The AM OAuth 2.0 provider service calls the script you configure:

In AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Plugins.
Select SCRIPTED in the Scope Validation Plugin Type drop-down.
Select your script in the Scope Validation Provider Script drop-down.

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

SAML v2.0

Customize your SAML v2.0 single sign-on implementation.

IDP adapter

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

For details, refer to IDP adapter plugin.

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 details, refer to IDP attribute mapper plugin.

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

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.

An authentication journey can call the script through a Scripted Decision node, for example.

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.

An AM policy calls the script as part of an environment condition. For more information, refer to scripted policy conditions.

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

Social identity provider profile transformation

Adapt the profile from the provider to align with the profile expected by the platform.

An authentication journey calls the script through a Social Provider Handler node.

For a sample script, refer to normalized-profile-to-managed-user.js.

ESVs in AM scripts

The systemEnv binding, available to all AM script types, provides the following methods shown with their Java signatures:

String getProperty(String propertyName);
String getProperty(String propertyName, String defaultValue);
<T> T getProperty(String propertyName, String defaultValue, Class<T> returnType);

where:

propertyName refers to an ESV. For details, refer to Introduction to ESVs.

The propertyName always starts with esv.; for example, esv.my.variable.

Make sure the propertyName is specific enough to distinguish it from all other ESVs defined.
defaultValue is a default value to use when no ESV matches propertyName.

It must not be null.
returnType is a fully qualified Java class name like java.lang.Double or java.lang.Boolean.

The getProperty(String propertyName) method returns null when the propertyName is not valid.