forgerock-am-scripted-decisions

Production-ready JavaScript and Groovy scripts for ForgeRock Access Management (AM) Scripted Decision Nodes. Full tutorials at IAMDevBox.com →

---

Overview

This repository provides a library of production-grade Scripted Decision Node scripts for ForgeRock Access Management 7.x authentication trees. Each script is tested, includes error handling, logging, and detailed comments explaining the ForgeRock-specific APIs.

What's Included

Script	Language	Purpose
scripts/risk-based-auth.js	JavaScript	Risk score evaluation — allow/step-up/deny
scripts/device-fingerprint.js	JavaScript	Browser fingerprint collection & comparison
scripts/ldap-group-check.groovy	Groovy	LDAP group membership → route to outcome
scripts/custom-attribute-collector.js	JavaScript	Collect custom attributes into sharedState
scripts/jwt-validator.js	JavaScript	Validate and decode external JWT in tree
scripts/http-api-call.js	JavaScript	REST API call with retries and error handling
scripts/mfa-bypass-check.js	JavaScript	Conditional MFA bypass based on trusted IPs
scripts/audit-logger.js	JavaScript	Structured audit event logging to AM log
tests/	Jest	Unit tests for all JavaScript scripts
docker-compose.yml	YAML	ForgeRock AM 7.x dev environment

---

Quick Start

Prerequisites

• ForgeRock AM 7.0+ (or PingOne Advanced Identity Cloud)
• Java 11+
• Docker & Docker Compose (for dev environment)
• Node.js 18+ (for running unit tests)

1. Clone the Repository

git clone https://github.com/IAMDevBox/forgerock-am-scripted-decisions.git
cd forgerock-am-scripted-decisions

2. Start the Dev Environment

docker-compose up -d
# ForgeRock AM will be available at http://localhost:8080/openam
# Default credentials: amadmin / password

3. Install a Script in AM

1. Navigate to Realm → Scripts → New Script
2. Set Script Type to Decision node script for authentication trees
3. Paste the contents of the desired script file
4. Click Save

4. Use the Script in an Authentication Tree

1. Navigate to Realm → Authentication → Trees
2. Create or edit a tree
3. Drag the Scripted Decision node onto the canvas
4. Select your script from the dropdown
5. Wire the true / false outcomes

---

Script Documentation

scripts/risk-based-auth.js

Evaluates risk factors from sharedState and routes the user to low, medium, or high outcomes.

Inputs from sharedState:

• riskScore (Number, 0-100) — pre-calculated risk score
• userAgent (String) — browser user agent string
• geoCountry (String) — ISO country code from IP geolocation

Outcomes: low | medium | high

Usage: Place after an IP Risk node or custom risk scoring node.

// Thresholds are configurable at the top of the script
var LOW_RISK_THRESHOLD = 30;
var HIGH_RISK_THRESHOLD = 70;

---

scripts/device-fingerprint.js

Collects browser attributes into sharedState on first login, then compares on subsequent logins to detect new or suspicious devices.

Outcomes: recognized | new_device | suspicious

For the full tutorial on this pattern, see: Custom Callback Usage and Extension Techniques in ForgeRock AM

---

scripts/ldap-group-check.groovy

Checks if the authenticated user is a member of a specific LDAP group using the ForgeRock idRepository API. Routes to member or not_member.

Configuration (at top of script):

def TARGET_GROUP_DN = "cn=admins,ou=groups,dc=example,dc=com"
def LDAP_ATTRIBUTE = "isMemberOf"

For advanced LDAP patterns, see: Keycloak LDAP User Federation Guide

---

scripts/http-api-call.js

Makes an authenticated REST API call from within a Scripted Decision Node. Includes timeout, retry with exponential backoff, and structured error handling.

Note: ForgeRock AM scripts run in a restricted javax.script sandbox. HTTP calls use the httpClient provided by the ForgeRock scripting context — not Node.js fetch.

// Configure at top of script
var API_ENDPOINT = "https://api.example.com/v1/risk/evaluate";
var API_TIMEOUT_MS = 3000;
var MAX_RETRIES = 2;

---

scripts/audit-logger.js

Writes structured JSON audit events to the AM audit log. Use this to track authentication decisions, policy evaluations, or fraud signals.

// Output format (AM debug log):
// {"event":"SCRIPTED_DECISION","user":"jsmith","outcome":"high_risk","ts":"2026-03-24T10:00:00Z"}

For AM logging configuration, see: Deep Dive: ForgeRock AM Scripted Decision Node Debugging

---

Running Tests

npm install
npm test

Tests use Jest with a mock for ForgeRock's sharedState, transientState, idRepository, and httpClient APIs.

---

ForgeRock Scripted Decision Node API Reference

Object	Type	Description
sharedState	Map	Persistent across nodes in the same tree session
transientState	Map	Cleared after session; use for secrets
idRepository	IdRepository	Read/write user profile attributes
httpClient	HttpClient	Make external HTTP calls
logger	Logger	Write to AM debug/audit logs
outcome	String	Set to one of the configured outcomes
callbacks	Callbacks	Access callback values from the request

---

Related Tutorials on IAMDevBox.com

• Deep Dive: Scripted Decision Node Debugging & Best Practices
• Custom Callback Usage and Extension Techniques in ForgeRock AM
• ForgeRock AM Script Customization: A Practical Guide
• IAM Tools Comparison: Keycloak vs ForgeRock vs Okta
• Browse All ForgeRock Tutorials →

---

License

MIT — see LICENSE