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 2.0
Customize your SAML 2.0 single sign-on implementation.
IDP adapter
Alter the processing of the authentication request during a SAML 2.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.
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.
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 withesv.
; 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 matchespropertyName
.It must not be
null
. -
returnType
is a fully qualified Java class name likejava.lang.Double
orjava.lang.Boolean
.
The getProperty(String propertyName)
method returns null
when the propertyName
is not valid.