Script bindings
Each script type exposes a number of bindings, objects that PingOne Advanced Identity Cloud injects into the script execution context. The bindings provide a stable way of accessing PingOne 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.
PingOne 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. For information about migrating to the enhanced scripting engine, refer to Migrating 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 |
||
Make outbound HTTP calls. |
Partial 1 |
Yes |
|
Write a message to the PingOne Advanced Identity Cloud debug log. |
Yes |
Yes |
|
Manage an IDM resource. |
No |
Yes |
|
Access the realm to which the user is authenticating. |
Yes |
Yes |
|
Access the name of the running script. |
Partial 1 |
Yes |
|
Reference secrets and credentials from scripts. |
Partial 2 |
Yes |
|
Access utility functions such as base64 encoding/decoding and generating random values and UUIDs. |
No |
Yes |
|
Reference system properties. |
Yes |
Yes |
1 Available in OAuth 2.0 script types, scripted decision node scripts, and SAML 2.0 SP scripts.
2 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 PingOne Advanced Identity Cloud; for example, |
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, and behaves like 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 supportsmethod
,headers
,form
,clientName
,token
, andbody
as attributes.Use the
requestOptions
attribute,form
, to send a form request. Theform
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" } }
-
`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.
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 |
Example: Send a synchronous request
The following example uses the httpClient
binding to send a synchronous authentication request and check for success.
For an example of how to use |
-
Next-generation
-
Legacy
This example assumes you’ve created a custom library script (authLib
) that handles authentication.
// import the library script that handles authentication
var authLib = require("authLib");
// use the library function to get authentication token
var bearerToken = authLib.generateBearer(nodeState);
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 mTLS
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 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.
For details about these settings, refer to Http Client service configuration.
-
In the AM admin UI (native 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:
|
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. PingOne 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
inrequestOptions
.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)
.
For information about debug logs, refer to 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);
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 |
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);
Access secrets and credentials
Use the secrets
binding to access ESVs configured in the realm’s ESV secret store.
For example, a script can access credentials or secrets to make outbound calls to a third-party REST service without hard-coding those credentials in the script.
Only secret labels that begin with the string scripted.node. are accessible to scripts.
|
Methods
Use the following method to return the value of the specified secret label:
String secrets.getGenericSecret(String secretLabel)
If the secret label is defined at the realm level, its value is returned; otherwise, the script returns the value defined at the global level.
To format the returned secret value, use these supported methods:
-
getAsBytes()
Retrieve the secret value inbyte[]
format. -
getAsUtf8()
Retrieve the secret value in UTF-8 format.
Learn more about the supported methods in the Secret and ScriptedSecrets Javadoc.
Examples
The following example scripts show how to get a password from a secret label named scripted.node.example.secret
.
The scripts use the encoded username (bjensen
) and password (passwd
) in a basic authentication header to access the
http://httpbin.org/basic-auth/{user}/{passwd} service.
-
Next-generation
-
Legacy
// secret [cGFzc3dk] stored as an ESV
var password = secrets.getGenericSecret("scripted.node.example.secret").getAsUtf8();
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 |
To use this sample script, add the following classes to the class allowlist property
in the
For details, refer to Access Java classes. |
var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);
// secret [cGFzc3dk] stored in file system secret store
var password = secrets.getGenericSecret("scripted.node.example.secret").getAsUtf8();
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.error("Script result: " + JSON.stringify(jsonResult));
if (jsonResult.hasOwnProperty("authenticated")) {
action = fr.Action.goTo("success").build();
} else {
action = fr.Action.goTo("failure").build();
}
Access utility functions
Use the next-generation utils
binding to base64 encode or decode text and generate random values or UUIDs.
Methods
- 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.
- String base64.encode(String toEncode)
-
Encodes the specified text using base64.
- String base64.decode(String toDecode)
-
Decodes the specified text using base64.
- String base64url.encode(String toEncode)
-
Encodes the specified text using base64url.
- String base64url.decode(String toDecode)
-
Decodes the specified text using base64url.
-
Next-generation
-
Legacy
// 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);
}
// encode a string
var encoded = utils.base64.encode("exampletext")
logger.debug("Encoded text: " + encoded); //ZXhhbXBsZXRleHQ=
var decoded = utils.base64.decode(encoded);
logger.debug("Decoded text: " + decoded);
// encode a URL
var encodedURL = utils.base64url.encode("http://exampletext=")
logger.debug("Encoded URL: " + encodedURL); //aHR0cDovL2V4YW1wbGV0ZXh0PQ
var decodedURL = utils.base64url.decode(encodedURL);
logger.debug("Decoded URL: " + decodedURL);
Not available in Legacy bindings
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 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
.The
defaultValue
must not benull
. -
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);