Script bindings

Each script type exposes a number of bindings, objects that Advanced Identity Cloud injects into the script execution context. The bindings provide a stable way of accessing Advanced Identity Cloud functionality, without the need to allowlist Java classes. Scripts are provided with all the bindings for their context at the point of execution.

Find information about context-specific bindings in the documentation for each script type.

Advanced Identity Cloud has introduced a next-generation scripting engine that offers several benefits, including enhanced script bindings.

The availability and usage of bindings depend on the script engine version of the script: legacy or next-generation. Both versions are described in this section.

You can find information about migrating to the enhanced scripting engine in Migrate to next-generation scripts.

The following bindings are common to many authentication and authorization scripts. Use these bindings to access data and perform script operations such as logging.

Binding

Description

Availability

Legacy

Next-generation

cookieName

Access the name of the current cookie.

Yes

httpClient

Make outbound HTTP calls, including asynchronous requests and requests using mTLS.

Partial ¹

Yes

logger

Write a message to the Advanced Identity Cloud debug log.

Yes

journey

Identify the current journey and get information about the journey and its configuration.

Partial ³

openidm

Manage an IDM resource.

Yes

policy

Evaluate policies using the policy engine API.

Yes

realm

Access the realm to which the user is authenticating.

Yes

scriptName

Access the name of the running script.

Partial ¹

Yes

systemEnv

Reference system properties.

Yes

utils

Access utility functions such as base64 encoding/decoding, cryptographic operations, and generating random values.

Yes

¹ Available in OAuth 2.0, Scripted Decision node, and SAML 2.0 scripts.

² Available in OAuth 2.0 JWT bearer and Scripted Decision node scripts.

Make sure you don’t use the same name for a local variable as that of a common binding in your script. These names are reserved for common bindings only.

If you have already defined a local variable with the same name as one that’s added to common bindings in a more recent version of Advanced Identity Cloud; for example, utils, you must rename the variable in your scripts.

Retrieve cookie name

The cookieName binding lets you access the name of the cookie as a string. You can use the cookie name to perform session actions such as ending all open sessions for a user.

Next-generation
Legacy

// add cookie name to shared state, for example: 8a92ca506c38f08
nodeState.putShared("myCookie", cookieName);

Not available in Legacy bindings

Access HTTP services

Call HTTP services with the httpClient.send method. HTTP client requests are asynchronous, unless you invoke the get() method on the returned object.

Methods

Next-generation
Legacy

The httpClient binding uses native JavaScript objects to send requests and receive responses, in a similar way to the Fetch API.

To invoke an HTTP request:

ResponseScriptWrapper httpClient.send(String uri, Map requestOptions).get()

Sends a synchronous request to the specified URI with request options. The requestOptions parameter is a native JavaScript object that supports method, headers, form, clientName, token, and body as attributes.

The requestOptions parameter is a native JavaScript object that supports these attributes:

Field Type

Field	Type
`method`	The HTTP request method. For example, `GET`, `POST`, `PUT`, `DELETE`, `HEAD`.
`headers`	The request headers. For example, `"Content-Type": "application/json"`.
`form`	Required for sending a form request. The `form` attribute automatically url-encodes fields, so you don’t need to specify `"Content-Type": "application/x-www-form-urlencoded"` as part of the headers. For example: `var requestOptions = { method: "POST", form: { field1: "value1", field2: "value2" } }`
`clientName`	The HTTP client instance required for sending a request using MTLS.
`token`	The token specified as the Authorization header, for example, when sending a synchronous request.
`body`	The content of the request. Not specified for `GET`, `HEAD`, or `TRACE` methods.

method

The HTTP request method. For example, GET, POST, PUT, DELETE, HEAD.

headers

The request headers. For example, "Content-Type": "application/json".

form

Required for sending a form request.

The form attribute automatically url-encodes fields, so you don’t need to specify "Content-Type": "application/x-www-form-urlencoded" as part of the headers.

For example:

var requestOptions = {
  method: "POST",
  form: {
    field1: "value1",
    field2: "value2"
  }
}

clientName

The HTTP client instance required for sending a request using MTLS.

token

The token specified as the Authorization header, for example, when sending a synchronous request.

body

The content of the request. Not specified for GET, HEAD, or TRACE methods.

ResponseScriptWrapper httpClient.send(String uri).get()

Sends a synchronous GET request with no additional request options.

To access response data:

Map response.formData()
Map response.json()
String response.text()

The following fields provide response status information:

Field Type

headers

Map

ok

boolean

status

integer

statusText

String

The response is similar to Response object behavior.

Field	Type
`headers`	Map
`ok`	boolean
`status`	integer
`statusText`	String

To invoke a synchronous HTTP request:

HTTPClientResponse httpClient.send(Request request).get()

To access response data:
JSON.parse(response.getEntity().getString())

HttpClientResponse methods:

Map<String, String> getCookies()
String getEntity
Map<String, String> getHeaders()
String getReasonPhrase()
Integer getStatusCode()
Boolean hasCookies
Boolean hasHeaders

The httpClient script binding automatically adds the current transaction ID as an HTTP header, X-ForgeRock-TransactionId. This lets you correlate caller and receiver logs when you use httpClient from your script to make requests to other Advanced Identity Cloud products and services.

The following examples demonstrate different ways to send HTTP client requests:

Example: Send a synchronous request (GET)
Example: Send a synchronous request (POST)
Example: Send an asynchronous request
Example: Send a request using basic authentication
Example: Send a request using mTLS and set timeouts

Example: Send a synchronous request (GET)

The following example uses the httpClient binding in a next-generation script to make a GET request to generate random UUIDs.

var BASE_URL = "http://www.randomnumberapi.com/api/v1.0/uuid";

var COUNT = 5;

var options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json; charset=UTF-8"
  }
};
var requestURL = `${BASE_URL}?count=${COUNT}`;

var response = httpClient.send(requestURL, options).get();

if (response.status === 200) {
  var uuids = JSON.parse(response.text());
  nodeState.putShared("UUIDs", uuids);
  action.goTo("true");
} else {
  logger.error("Error generating UUIDs: " + response.statusText);
  action.goTo("false");
}

Use a Debug node to verify the UUIDs stored in nodeState. For example:

{
    ...
    "UUIDs": [
        "d787a51e-7b2a-4eba-9d87-7ec555ec9f32",
        "f561381a-ec03-4b48-8d6d-828c80d43805",
        "6d9ef759-be3d-414d-a942-dce8d3840b59",
        "40737769-0c91-41e9-a0c4-7deab4a15aea",
        "5a40bdb6-62d3-406f-bd23-71be1d5a54f5"
    ]
}

Example: Send a synchronous request (POST)

The following example uses the httpClient binding to send a synchronous authentication request and check for success.

Next-generation
Legacy

This example assumes you’ve created a custom library script (authLib) that handles authentication.

var bearerToken = "Bearer abcd-1234";

var requestOptions = {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  token: bearerToken, // Equivalent to Authorization header
  body: {
    username: "bjensen"
  }
}

var requestURL = "https://my.auth.server/authenticate";
var response = httpClient.send(requestURL, requestOptions).get();

if (response.status === 200) {
    action.goTo("true");
} else {
    action.goTo("false");
}

var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

var requestURL = "https://my.auth.server/authenticate";
var request = new org.forgerock.http.protocol.Request();
request.setUri(requestURL);
request.setMethod("POST");
request.getHeaders().add("Content-Type", "application/json;");
request.getHeaders().add("Authorization", "Bearer abcd-1234");
request.setEntity(JSON.stringify({"username": "bjensen"}));

var response = httpClient.send(request).get();

var responseCode = response.getStatus().getCode();
if (responseCode === 200) {
    action = fr.Action.goTo("true").build();
} else {
    action = fr.Action.goTo("false").build();
}

Example: Send an asynchronous request

The httpclient binding also supports asynchronous requests so that you can perform non-blocking operations, such as recording logging output after the script has completed.

To make an asynchronous request, use the same method signatures to send the request but without calling get() on the returned object. The send() method then initiates a separate thread to handle the response. Callers are unable to control when the asynchronous call is processed, so won’t be able to use the response as part of authentication processing.

Next-generation
Legacy

public Promise<ResponseScriptWrapper, HttpClientScriptException> send(String uri)
public Promise<ResponseScriptWrapper, HttpClientScriptException> send(String uri, Map<String, Object> requestOptions)

public Promise<Response, NeverThrowsException> send(Request request)

For example:

Next-generation
Legacy

var requestURL = "https://my.auth.server/audit";
// creates separate thread to handle response
var response = httpClient.send(requestURL).then((response) => {
  if (!response) {
    logger.error("Bad response from " + requestURL);
    return;
  }
  if (response.status != 200) {
    logger.error("Unexpected response: " + response.statusText);
    return;
  }
  logger.debug("Returned from async request");
});
// continues processing whilst awaiting response
action.goTo("true");

var fr = JavaImporter(
    org.forgerock.http.protocol.Request,
    org.forgerock.http.protocol.Response,
    org.forgerock.openam.auth.node.api.Action);

var request = new fr.Request();
request.setUri("https://my.auth.server/audit");
request.setMethod("GET");

var response = httpClient.send(request).then((response) => {
  if (!response) {
    logger.error("Bad response from " + requestURL);
    return;
  }
  var status = response.getStatus().getCode();

  if (status != 200) {
    logger.error("Unexpected response: " + response.getEntity().getString());
    return;
  }
  logger.message("Returned from async request");
});

action = fr.Action.goTo("true").build();

Example: Send a request using basic authentication

The following script uses the encoded username and password in a basic authentication header to access the http://httpbin.org/basic-auth/{user}/{passwd} service.

Next-generation
Legacy

// password stored as an ESV
var password = systemEnv.getProperty('esv.my.password');

var auth = utils.base64.encode("bjensen:" + password);

var requestURL = "http://httpbin.org/basic-auth/bjensen/passwd";

var requestOptions = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Basic ".concat(auth)
  },
}
var response = httpClient.send(requestURL, requestOptions).get();

if (!response) {
  logger.error("Bad response from " + requestURL);
  action.goTo("false");
} else {
  if (response.status != 200) {
    logger.warn("Authentication not successful. Code: " + response.status);
    action.goTo("false");
  } else {
    logger.debug("Authenticated: " + response.json().authenticated);
    action.goTo("true");
  }
}

To construct the header for basic authorization, make sure you use the concat() function rather than + to append credentials.

To use this sample script, add the following classes to the class allowlist property in the AUTHENTICATION_TREE_DECISION_NODE scripting engine configuration:

org.mozilla.javascript.ConsString
java.util.Base64
java.util.Base64$Encoder

For details, refer to Access Java classes.

var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

// password stored as an ESV
var password = systemEnv.getProperty('esv.my.password');

var auth = java.util.Base64.getEncoder().encodeToString(java.lang.String("bjensen:" + password).getBytes());

var request = new org.forgerock.http.protocol.Request();
request.setMethod("GET");
request.setUri("http://httpbin.org/basic-auth/bjensen/passwd");
request.getHeaders().add("content-type","application/json; charset=utf-8");
request.getHeaders().add("Authorization", "Basic " + auth);

var response = httpClient.send(request).get();
var jsonResult = JSON.parse(response.getEntity().getString());
logger.message("Script result: " + JSON.stringify(jsonResult));

if (jsonResult.hasOwnProperty("authenticated")) {
  action = fr.Action.goTo("success").build();
} else {
  action = fr.Action.goTo("failure").build();
}

Example: Send a request using mTLS and set timeouts

Configure the httpclient to use mTLS to exchange data securely when making an HTTP request to an external service.

Follow these example steps to send an HTTP request using mTLS:

Configure an instance of the HTTP Client service
Map a client certificate to a secret label
Create a script to send the request

Configure the HTTP Client service

Complete these steps to configure an instance of the HTTP Client service.

The instance defines settings such as timeout values and the client certificate or truststore secret labels required by the httpclient script binding to make a TLS connection. You can configure the instance to override default values.

For example, to set connection or response timeout values for a request initiated by the HTTP client, enable Use Instance Timeouts in the service instance and set the timeout accordingly.

You can find information about these settings in the Http Client service configuration.

In the AM native admin console, go to Realms > Realm Name > Services.
Click Add a Service and select Http Client Service from the service type drop-down list.
Enable the service and save your changes.
On the Secondary Configurations tab, click Add a Secondary Configuration.
Provide a name for the HTTP client instance; for example, myHttpClient, and click Create.
Enable the instance and save your changes.

On the TLS Configuration tab, enter an identifier to be used in your secret label in the Client Certificate Secret Label Identifier field.

For example, testCrt creates the dynamic secret label, am.services.httpclient.mtls.clientcert.testCrt.secret.

To specify a truststore to verify the target server’s certificate, provide a value for Server Trust Certificates Secret Label Identifier.

This creates the dynamic secret label, am.services.httpclient.mtls.servertrustcerts.identifier.secret.

Save your changes.

Map a base64-encoded PEM certificate to the secret label

To prepare a certificate for TLS connections, it must be:

Base64-encoded
A file containing both a private and public key
Uploaded as an ESV using the API

Complete these steps to generate a key pair and map the secret to the dynamic secret label created in the previous step.

Generate a private key and a public key, as described in Generate an RSA key pair.

You should now have a .pem file that contains a base64-encoded key pair. Advanced Identity Cloud shares the public key and uses the private key to sign the request.
Get an access token for the realm.

Specify the access token in a REST API call to create a PEM-encoded ESV secret.

For example, to create a secret named esv-mtls-cert:

$ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/secrets/<esv-mtls-cert>' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: protocol=1.0;resource=1.0' \
--data-raw '{
    "encoding": "pem",
    "useInPlaceholders": false,
    "valueBase64": "<base64-encoded PEM-file>"
}'

You must specify the encoding type as pem for the API to recognize the value as a certificate.

Map the secret against the secret label created when you configured the HTTP Client service, for example:

Secret Label

am.services.httpclient.mtls.clientcert.testCrt.secret

alias

esv-mtls-cert

The certificate is now uploaded and mapped to the secret label.

Create a script to send the HTTP request

Write a next-generation decision node script to send a request using the HTTP client instance in the request options.

In your script, specify your HTTP client instance as the value for clientName in requestOptions.

For example:

 var requestOptions = {
    "clientName": "<myhttpclient>"   (1)
 }
var res = httpClient.send("https://example.com",
                                    requestOptions).get(); (2)
action.withHeader(`Response code: ${res.status}`);

if (res.status == 200) {
  action.goTo("true").withDescription(response.text());
} else {
  action.goTo("false");
};

1	The `clientName` attribute must reference an enabled instance of the HTTP Client service.
2	The HTTP client sends the request to an mTLS endpoint that checks for a certificate.

Create a simple journey that includes the scripted decision node to test your changes.
Verify that the HTTP request is sent successfully.

Log script messages

Write messages to Advanced Identity Cloud debug logs by using the logger object.

Scripts that create debug messages have their own logger which is created after the script has executed at least once.

Logger names use the format: scripts.<context>.<script UUID>.(<script name>); for example, `scripts.OIDC_CLAIMS.36863ffb-40ec-48b9-94b1-9a99f71cc3b5.(OIDC Claims Script).

You can find information about debug logs in Get audit and debug logs.

Next-generation
Legacy

The ScriptedLoggerWrapper is based on the SLF4J logging framework. You can log messages at the following levels:

Trace
Debug (default level for development tenant environments)
Info
Warn (default level for staging and production environments)
Error

var traceEnabled = logger.isTraceEnabled();
logger.trace("Trace with arg {}", arg);
var debugEnabled = logger.isDebugEnabled();
logger.debug("Debug with arg {}", arg);
var infoEnabled = logger.isInfoEnabled();
logger.info("Info with arg {}", arg);
var warnEnabled = logger.isWarnEnabled();
logger.warn("Warn with arg {}", arg);
var errorEnabled = logger.isErrorEnabled();
logger.error("Error with arg {}", arg);

The Debug logger lets you log messages at the following levels:

Message
Warning
Error

var messageEnabled = logger.messageEnabled();
logger.message("Message with arg {}", arg);
var warnEnabled = logger.warningEnabled();
logger.warning("Warn with arg {}", arg);
var errorEnabled = logger.errorEnabled();
logger.error("Error with arg {}", arg);

Get journey details

The next-generation journey binding provides information about the current journey.

Call the following methods to access details about the journey and how it’s configured.

Methods

String name(): Returns the name of the current journey. This can be an inner or an outer journey.
String identityResource(): Returns the identity resource of the current journey. For example, managed/alpha_user.
boolean innerJourney(): Returns true if the current journey is configured to run as an inner journey only.
boolean mustRun(): Returns true if the current journey is set to always run regardless of whether the user authenticated successfully and a session exists or not.

Example

Next-generation
Legacy

var currentJourney = journey.name();

logger.info(currentJourney + " identity resource: " + journey.identityResource());

if (journey.innerJourney()){
  logger.info(currentJourney + " is an inner journey.");
}
if(journey.mustRun()){
  logger.info(currentJourney + " is a mustRun journey.");
}

Not available in Legacy bindings

Access IDM scripting functions

The openidm binding lets you manage an IDM resource by calling scripting functions directly from a next-generation script.

The following CRUDPAQ functions are supported:

create
read
update
delete
patch
action
query

For more information, refer to Scripting functions.

The openidm binding provides administrative access to IDM functions. Use it with caution to prevent the exposure of sensitive data.

The following example illustrates how to create a user, update their details, send an email, and finally delete the user:

Next-generation
Legacy

var username = "bjensen";

// CREATE: returns the user identity as a JSON object (wrapped in a MapScriptWrapper)
var newUser = openidm.create("managed/alpha_user", null, {
  "userName": username,
  "mail": "bjensen@example.com",
  "givenName": "Barbara",
  "sn": "Jensen"});

// Access the fields directly, for example: ._id, .sn, .city, .country
var userID = newUser._id;

// READ: returns entire identity as a JSON object
var user = openidm.read("managed/alpha_user/" + userID);

// Debug to output all fields
logger.debug("user: " + JSON.stringify(user));

// UPDATE: replaces entire identity with specified object
// Returns the updated identity as a JSON object
user.description = 'New description';
var updatedUser = openidm.update("managed/alpha_user/" + userID, null, user);

// PATCH: selectively modify object, returns entire identity
var patchedUser = openidm.patch("managed/alpha_user/" + userID, null, [{
        "operation":"replace",
        "field":"/mail",
        "value":"new@example.com"
}]);

// QUERY: returns results array in a map
var queryRes = openidm.query("managed/alpha_user",
    {"_queryFilter":`/userName eq '${username}'`},["*", "_id"]);

// Debug query result count and the requested properties
logger.debug("Query result count: " + queryRes.resultCount);
logger.debug("Queried user: " + queryRes.result[0].givenName);

// ACTION: send email using the action function
var actionRes = openidm.action("external/email", "send", {
    "from": "admin@example.com",
    "to": patchedUser.mail,
    "subject": "Example email",
    "body": "This is an example"
});
// Example response if not null: {"status":"OK","message":"Email sent"}
logger.debug("Status: " + actionRes.status + " : " + actionRes.message);

// DELETE: returns deleted object if successful, throws exception if not
openidm.delete('managed/alpha_user/'+ userID, null);

action.goTo("true");

Not available in Legacy bindings

Output realm name

The realm binding lets you access the name of the realm to which the user is authenticating as a string.

For example, authenticating to the alpha realm returns a string value of /alpha.

Next-generation
Legacy

// log current realm
logger.debug("User authentication realm: " + realm);

// log current realm
logger.message("User authentication realm: " + realm);

Output script name

Use the scriptName binding to get the name of the running script as a string.

Next-generation
Legacy

// log current script name
logger.debug("Running script: " + scriptName);

// or use a library script to log script name
var mylib = require('loggingLibrary');
mylib.debug(logger, scriptName);

// log current script name
logger.message("Running script: " + scriptName);

Reference ESVs in scripts

The systemEnv binding, available to all 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 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.

The defaultValue must not be null.
returnType is one of the following fully-qualified Java class names:
- java.lang.Boolean
- java.lang.Double
- java.lang.Integer
- java.lang.String
- java.util.List
- java.util.Map

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

For example:

var myProperty = systemEnv.getProperty('esv.my.variable');
var myDefault = systemEnv.getProperty('esv.nonexisting.variable', 'defaultValue');
var myDouble = systemEnv.getProperty('esv.double.variable', '0.5', java.lang.Double);
var myBool = systemEnv.getProperty('esv.bool.variable', false, java.lang.Boolean);
var myInt = systemEnv.getProperty('esv.int.variable', 34, java.lang.Integer);
var map = systemEnv.getProperty('esv.map.variable', '{"defaultKey":"defaultValue"}', java.util.Map);

Access utility functions

Use the next-generation utils binding to perform functions such as encoding/decoding and encryption/decryption, type conversion, and cryptographic operations.

The utils binding isn’t available in legacy scripts.

Base64 encode and decode

String base64.encode(String toEncode): Encodes the specified text using base64.
String base64.encode(byte[] toEncode): Encodes the specified bytes using base64.
String base64.decode(String toDecode): Decodes the specified text using base64.
byte[] base64.decodeToBytes(String toDecode): Decodes the specified text using base64 and returns the result as an array of bytes.
Example

var encoded = utils.base64.encode("exampletext")
logger.debug("Encoded text: " + encoded); //ZXhhbXBsZXRleHQ=

var decoded = utils.base64.decode(encoded);
logger.debug("Decoded text: " + decoded);

Base64Url encode and decode

String base64url.encode(String toEncode): Encodes the specified text using base64url.
String base64url.decode(String toDecode): Decodes the specified text using base64url.
Example

var encodedURL = utils.base64url.encode("http://exampletext=")
logger.debug("Encoded URL: " + encodedURL); //aHR0cDovL2V4YW1wbGV0ZXh0PQ

var decodedURL = utils.base64url.decode(encodedURL);
logger.debug("Decoded URL: " + decodedURL);

Generate random values

String crypto.randomUUID(): Returns a type 4 pseudo-random generated UUID.
<JavaScript array> crypto.getRandomValues(<JavaScript array> array): Returns the specified array filled with the same number of generated random numbers.
Example

// generate a pseudorandom UUID (version 4)
var uuid = utils.crypto.randomUUID();
logger.debug("UUID: " + uuid); //eef5b4e1-ae86-4c0a-9160-5afee2b5e791

// generate an array of 5 random values
var array = [0,0,0,0,0];
utils.crypto.getRandomValues(array);
array.forEach(function(element){
  logger.debug("Random value: " + element);
});

Convert types

String types.bytesToString(byte[] toConvert): Converts a byte array to a string.
byte[] types.stringToBytes(String toConvert): Converts a string to a byte array.
Example

var dataBytes = utils.types.stringToBytes("data");
var dataString = utils.types.bytesToString(dataBytes);

Generate keys

Object crypto.subtle.generateKey(String algorithm): Generates a key using the specified algorithm and default values.
Object crypto.subtle.generateKey(Map<String, Object> algorithm): Generates a key using the parameters provided, depending on the algorithm specified.
Parameters

Option Algorithm Description

Option	Algorithm	Description
`name`	All	Required. The name of the algorithm. Possible values: `AES`, `RSA`, `HMAC`, `ECDSA`.
`length`	`AES`	Optional. Default: `256`.
`modulusLength`	`RSA`	Optional. Default: `2048`.
`namedCurve`	`ECDSA`	Optional. Possible values: `P-256` (default), `P-384`, `P-521`.
`hash`	`HMAC`	Optional. Possible values: `SHA-1`, `SHA-256` (default), `SHA-384`, `SHA-512`.

name

All

Required. The name of the algorithm. Possible values: AES, RSA, HMAC, ECDSA.

length

AES

Optional. Default: 256.

modulusLength

RSA

Optional. Default: 2048.

namedCurve

ECDSA

Optional. Possible values: P-256 (default), P-384, P-521.

hash

HMAC

Optional. Possible values: SHA-1, SHA-256 (default), SHA-384, SHA-512.

Example

var aesKey = utils.crypto.subtle.generateKey("AES");

// Optionally specify 'length' (default 256)
var aesKeyCustom = utils.crypto.subtle.generateKey(
  {
    "name": "AES", length: 256
  }
);

var rsaKey = utils.crypto.subtle.generateKey("RSA");

// Optionally specify 'modulusLength' (default 2048)
var rsaKeyCustom = utils.crypto.subtle.generateKey(
  {
    "name": "RSA", modulusLength: 4096
  }
);

var hmacKey = utils.crypto.subtle.generateKey("HMAC");

// Optionally specify 'hash' (default 'SHA-256')
var hmacKeyCustom = utils.crypto.subtle.generateKey(
  {
    "name": "HMAC", "hash": "SHA-384"
  }
);

var ecdsaKey = utils.crypto.subtle.generateKey("ECDSA");

// Optionally specify 'namedCurve' (default P-256)
var ecdsaKeyCustom = utils.crypto.subtle.generateKey(
  {
    "name": "ECDSA", namedCurve: "P-384"
  }
);

logger.debug("AES key: " + aesKey.length);
logger.debug("HMAC key: " + hmacKey.length);
logger.debug("ECDSA key: " + ecdsaKey.publicKey.length + " : " + ecdsaKey.privateKey.length);
logger.debug("RSA keys: " + rsaKey.publicKey.length + " : " + rsaKey.privateKey.length);

Encrypt and decrypt

byte[] crypto.subtle.encrypt(String algorithm, byte[] key, byte[] data): Encrypts the data using the specified key and algorithm (AES or RSA).

byte[] crypto.subtle.decrypt(String algorithm, byte[] key, byte[] data): Decrypts the data using the specified key and algorithm (AES or RSA).

Example

var data = utils.types.stringToBytes("data");

var aesKey = utils.crypto.subtle.generateKey("AES");
var rsaKey = utils.crypto.subtle.generateKey("RSA");

var encryptedAes = utils.crypto.subtle.encrypt("AES", aesKey, data);
var decryptedAes = utils.crypto.subtle.decrypt("AES", aesKey, encryptedAes);

var encryptedRsa = utils.crypto.subtle.encrypt("RSA", rsaKey.publicKey, data);
var decryptedRsa = utils.crypto.subtle.decrypt("RSA", rsaKey.privateKey, encryptedRsa);

logger.debug("decryptedAes: " + decryptedAes + " decryptedRsa: " + decryptedRsa);

Compute digest (hash) values

String crypto.subtle.digest(String algorithm, byte[] data): Returns the digest of the data using the specified algorithm. The algorithm must be one of SHA-1, SHA-256, SHA-384, SHA-512.
Example

var data = utils.types.stringToBytes("data");
var digest = utils.crypto.subtle.digest("SHA-256", data);

logger.debug("Digest length: " + digest.length);

Sign and verify

byte[] sign(String algorithm, byte[] key, byte[] data): Signs the data using the specified algorithm and key.
byte[] sign(Map<String, Object> algorithmOptions, byte[] key, byte[] data): Signs the data using the specified algorithm options and key.
boolean verify(String algorithm, byte[] key, byte[] data, byte[] signature): Verifies the signature of the data using the specified algorithm and key.
boolean verify(Map<String, Object> algorithmOptions, byte[] key, byte[] data, byte[] signature): Verifies the signature of the data using the specified key and map of parameters.
Parameters

Option Algorithm Description

Option	Algorithm	Description
`name`	All	Required. The name of the algorithm. Possible values: `RSA`, `HMAC`, `ECDSA`.
`hash`	`HMAC`, `ECDSA`	Optional. Possible values: `SHA-1` (HMAC only), `SHA-256` (default), `SHA-384`, `SHA-512` ⁽¹⁾.

name

All

Required. The name of the algorithm. Possible values: RSA, HMAC, ECDSA.

hash

HMAC, ECDSA

Optional. Possible values: SHA-1 (HMAC only), SHA-256 (default), SHA-384, SHA-512 ⁽¹⁾.

⁽¹⁾ The namedCurve length must match the hash length for EDCSA keys. For example, P-256 and SHA-256, or P-521 and SHA-512.

Example

var data = utils.types.stringToBytes("data");
var rsaKey = utils.crypto.subtle.generateKey("RSA");
var hmacKey = utils.crypto.subtle.generateKey("HMAC");
var ecdsaKey = utils.crypto.subtle.generateKey("ECDSA");

var signRsa = utils.crypto.subtle.sign("RSA", rsaKey.privateKey, data);
var verifyRsa = utils.crypto.subtle.verify("RSA", rsaKey.publicKey, data, signRsa);

var hmacOpts = {
  "name": "HMAC",
  "hash": "SHA-512"
}
var signHmac = utils.crypto.subtle.sign(hmacOpts, hmacKey, data);
var verifyHmac = utils.crypto.subtle.verify(hmacOpts, hmacKey, data, signHmac);

var ecdsaOpts = {
  "name": "ECDSA",
  "hash": "SHA-256"
}

var signEcdsa = utils.crypto.subtle.sign(ecdsaOpts, ecdsaKey.privateKey, data);
var verifyEcdsa = utils.crypto.subtle.verify(ecdsaOpts, ecdsaKey.publicKey, data, signEcdsa);

logger.debug("RSA key verified: " + verifyRsa);
logger.debug("HMAC key verified: " + verifyHmac);
logger.debug("ECDSA key verified: " + verifyEcdsa);

Evaluate policies

The next-generation policy binding lets you access the policy engine API and evaluate policies from within scripts.

Methods

List<Map<String, Object>> policy.evaluate(subject, application, resources, environment)

Use the evaluate() method to request policy decisions for specific resources.

Parameters

The following parameters are required:

Parameter Type Description

Parameter	Type	Description
`subject`	Map<String, Object>	The subject making the request, specified as an `ssoToken`, a `jwt`, or a `claims` value.
`application`	String	The name of the policy set.
`resources`	List<String>	The resources to request decisions for.
`environment`	Map<String, List<String>>	Specify environment conditions as a map of keys to lists of values, or `{}` to indicate none.

subject

Map<String, Object>

The subject making the request, specified as an ssoToken, a jwt, or a claims value.

application

String

The name of the policy set.

resources

List<String>

The resources to request decisions for.

environment

Map<String, List<String>>

Specify environment conditions as a map of keys to lists of values, or {} to indicate none.

Returns

The method returns evaluation decisions as a list of maps containing the following fields:

Field Description

Field	Description
`resource`	The requested resource.
`actions`	A map of actions and corresponding boolean values. For example: `"actions":{ "POST":false, "PATCH":false, "GET":false, "DELETE":false, "OPTIONS":true, "HEAD":false, "PUT":false }`
`attributes`	A map of attribute names to their values if attributes exist for the policy.
`advices`	A map of advice names to their values if advice exists for the policy.

resource

The requested resource.

actions

A map of actions and corresponding boolean values. For example:

"actions":{
    "POST":false,
    "PATCH":false,
    "GET":false,
    "DELETE":false,
    "OPTIONS":true,
    "HEAD":false,
    "PUT":false
}

attributes

A map of attribute names to their values if attributes exist for the policy.

advices

A map of advice names to their values if advice exists for the policy.

Learn how the evaluate method works and its parameters in Request policy decisions for a specific resource. The policy binding works in a similar way to this REST API call.

Example

The following example script requests a policy decision for a URL resource.

// Set the subject to the ssoToken of an authenticated user
var subject = {
    ssoToken: requestCookies[cookieName]
}
var application = "testPolicySet"

var resources = ["http://example.com:80/test"]

var environment = {
    "myField": ["myValue"]
}

var evaluationResult;
try {
    // policy.evaluate() returns List<Map<String, Object>>
    var results = policy.evaluate(subject, application, resources, environment);
    evaluationResult = results[0];
} catch(e) {
    logger.error(`Policy Evaluation Failed: ${e.message}`)
}

if (evaluationResult && evaluationResult.actions['GET'] === true) {
    action.goTo("authorized")
} else {
    action.goTo("unauthorized")
}

PingOne Advanced Identity Cloud

Script bindings

Retrieve cookie name

Access HTTP services

Methods

Example: Send a synchronous request (GET)

Example: Send a synchronous request (POST)

Example: Send an asynchronous request

Example: Send a request using basic authentication

Example: Send a request using mTLS and set timeouts

Configure the HTTP Client service

Map a base64-encoded PEM certificate to the secret label

Create a script to send the HTTP request

Log script messages

Get journey details

Methods

Example

Access IDM scripting functions

Output realm name

Output script name

Reference ESVs in scripts

Access utility functions

Evaluate policies

Methods

Example