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, see 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, see policy-condition.js.
For more information, see 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, see oauth2-access-token-modification.js.
-
Authorize endpoint data provider
Return additional data from an authorization request.
For a sample script, see oauth2-authorize-endpoint-data-provider.js.
-
Scope evaluator
Evaluate and return an OAuth 2.0 access token’s scope information.
For a sample script, see 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, see 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, see oidc-claims-extension.js.
For information about configuring the OAuth 2.0 scripts, see 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, see 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, see 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]'