Identity Cloud

Auth scripting

Overview

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.

Auth scripting introduction

For an introduction to auth scripting, read this scripting guide.

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, view these sample scripts. Each sample script includes a list of available variables.

Auth script types

The following auth script types are available in Identity Cloud:

Script Type Description

Client-side Authentication

Scripts that are executed on the client during authentication.

Journey Decision Node

Scripts that are included in an authentication node within a journey, and are executed on the server during authentication.

Policy Condition

Scripts that are used as conditions within policies.

OIDC Claims

Scripts that gather and populate the claims in a request when issuing an ID token or making a request to the userinfo endpoint.

OAuth 2.0 Access Token Modification

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

OAuth 2.0 "May Act"

Scripts that can add the may_act claim to tokens when performing token exchanges.

Social Identity Provider Profile Transformation

Scripts that adapt the fields received by a social identity provider to align with the fields expected by Identity Cloud.

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 will open 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
④ Validation checking

Create a new auth script

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

  2. Choose an auth script type.

  3. After you select a script type, the editor will open. 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 repeat step 2 and select a different script type.

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

When you save a script, it fixes the script type for the lifetime of the script.

Journey decision node auth scripts

See Journeys for more information on journeys.

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

  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 (4) or edit an existing one (5):

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-2022 ForgeRock, all rights reserved.