Identity Cloud

Auth scripting

You can use authentication and authorization (auth) scripting to modify default Identity Cloud behavior in many situations: client-side authentication, policy conditions, handling OpenID Connect claims, and others.

Use JavaScript for auth scripting in Identity Cloud. Groovy scripts are deprecated and will eventually be completely replaced with JavaScript scripts.

For JavaScript examples of all auth script types, review the sample scripts. Each sample script includes a list of available variables.

Scripts can potentially emit the personally identifiable information (PII) of your end users into Identity Cloud logs, and then into external services that consume Identity Cloud logs.

ForgeRock recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Identity Cloud tenant environments.

Auth script types

The auth script types available in Identity Cloud include the following:

Script Type Description

OAuth 2.0 Access Token Modification

Modifies the key-value pairs contained within access tokens before they are issued to a client.

Client-side Authentication

Runs on the client during authentication.

Configuration Provider node

Runs in a Configuration Provider node as a step in an authentication journey.

OAuth 2.0 May Act

Adds the may_act claim to tokens when performing token exchanges.

OIDC Claims

Modifies or overrides OpenID Connect claims when issuing an ID token or in the response from the userinfo endpoint.

Journey Decision Node

Runs in a Scripted Decision node as a step in an authentication journey.

OAuth 2.0 Validate Scope

Modifies how Identity Cloud validates requested OAuth 2.0 scopes.

Social Identity Provider Profile Transformation

Adapts the fields received from a social identity provider to align with the fields expected by Identity Cloud.

Policy Condition

Modifies authorization policy decisions.

Manage auth scripts

To manage your auth scripts, go to Realm > Scripts > Auth Scripts.

On the Scripts page, you can view a list of existing scripts. To edit, duplicate, or delete a script, click its More () menu.

The edit option in the More menu opens the script in a lightweight editor which features syntax highlighting and validation checking. You can maximize the editor to full screen to edit larger scripts:

idcloudui scripts editor

① JavaScript editor
② Fullscreen option
③ Syntax highlighting
④ Syntax error highlighting and validation checking

Create a new auth script

  1. Go to Realm > Scripts > Auth Scripts, then click + New Script.

  2. Choose an auth script type.

    After you select a script type, the editor opens. The editor is prepopulated with a default script for that type, which is intended as a starting point for your custom script.

    If you selected the wrong script type, click Previous to select a different script type.

  3. Enter a unique Name and optional Description for the script, then click Save.

    After you save a script, you cannot change its type.

Journey decision node auth scripts

Refer to Journeys for more information on journeys.

You can create, edit, and validate journey decision node auth scripts directly from within a Scripted Decision node.

  1. Go to Realm > Journeys.

  2. Open a journey in the journey editor.

  3. Find an existing scripted decision node or add a new one.

  4. Select the scripted decision node to open the context pane on the right side.

  5. The following screenshot shows where you can create a new journey decision node script ④ or edit an existing one ⑤:

    idcloudui journeys scripted decision script options

    ① Scripted decision node
    ② Context pane
    ③ Journey decision node script drop-down
    ④ Add new journey decision node script
    ⑤ Edit existing journey decision node script

Copyright © 2010-2023 ForgeRock, all rights reserved.