Authentication nodes and journeys
Authentication journeys provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow. Use them to build complex authorization scenarios, while offering a streamlined login experience to users.
Authentication journeys are made up of authentication nodes, which define actions taken during authentication. Each node performs a single task during authentication; for example, collecting a username or making a simple decision based on a cookie.
Nodes can have multiple outcomes rather than just success or failure. These outcomes let you create complex yet user-friendly authentication experiences by linking nodes together, creating loops and sections for different authentication scenarios, and nesting nodes within a journey.

For additional control of the authentication process, you can assign authentication levels to sections of a journey, with higher levels typically being used to allow access to more restricted resources.
Authentication levels
When a user authenticates successfully, Identity Cloud creates a session which allows Identity Cloud to manage the user’s access to resources. The session is assigned an authentication level. The authentication level is often used as a measure of the strength of the authentication performed. For example, a simple username and password might be assigned a low authentication level, while multi-factor authentication with push and WebAuthn might be assigned a high level.
Authorization policies might require a particular authentication level to access protected resources. When an authenticated user tries to access a protected resource without satisfying the authentication level requirement, Identity Cloud denies access to the resource and returns an advice indicating that the user must reauthenticate at the required level to access the resource.
The policy enforcement point, such as an agent, sends the user back to Identity Cloud for a session upgrade.
Identity Cloud provides the following nodes to manage authentication levels:
-
The Auth Level Decision node checks that the current authentication level is equal to or greater than the level specified in the node.
-
The Modify Auth Level node can raise or lower the authentication level.
Position these nodes to alter the authentication level, depending on the route taken through the authentication flow.
Account lockout
You should limit the number of attempts a user can make at authenticating with credentials. Limiting the number of attempts helps to prevent password-guessing and brute-force attacks.
Authentication journeys have built-in support for account lockout and provide nodes for checking and changing the status of a user:
- Account Active Decision node
-
Use this node to determine whether an account is active or inactive (locked).
- Account Lockout node
-
Use this node to change the account’s status to active or inactive (locked).
When setting an account to active, the node also resets the failed attempts and lockout duration counters.
In addition to these lockout-specific nodes, the Success and Failure nodes include account lockout functionality when lockout is enabled in a realm, as follows:
Success node
This node does the following:
-
Checks the Status property of the user profile, when reached, and fails the authentication with an error message, if the account is marked as
Inactive
:The error message is returned in the JSON response if authenticating to the journey by using REST:
{ "code":401, "reason":"Unauthorized", "message":"User Locked Out.", "detail": { "failureUrl":"" } }
-
Resets the failure count in the user profile, when reached, if the User Status property is set to
Active
.
Failure node
This node does the following:
-
If you select Authentication > Settings > Account Lockout > Login Failure Lockout Mode for the realm (in the AM admin UI), the node checks the invalid attempts property of the user profile. It returns a warning message if the number of failed attempts is equal to or greater than the configured Warn User After N Failures value:
The error message is returned in the JSON response if authenticating to the journey over REST:
{ "code":401, "reason":"Unauthorized", "message":"Warning: You will be locked out after 1 more failure(s).", "detail": { "failureUrl":"" } }
-
Increments the failure count in the user profile, when reached.
-
Returns an error message if the account is marked as
Inactive
:The error message is returned in the JSON response if authenticating to the journey over REST:
{ "code":401, "reason":"Unauthorized", "message":"User Locked Out.", "detail": { "failureUrl":"" } }
Configure authentication journeys
The following table summarizes the high-level tasks required to configure authentication journeys:
Task | Resources |
---|---|
Design your user authentication journey Authentication journeys are very flexible. For example, the same journey can branch for different use cases, or users can be forced to loop though branches until they are able to present the required credentials. It is easy to create a massive journey that is difficult to understand, read, and maintain in the UI. To avoid this, Identity Cloud lets you nest journeys within journeys. The best way to tackle the design decision is to write down a list of required steps users would need to take to log in to your environment, and then check the list of nodes available in Identity Cloud. |
|
Configure your authentication journeys Use the journey editor to put together your journeys quickly. |
|
Configure webhooks, if required If you have configured the |
Specify the identity object type for a journey
Each authentication journey assumes a specific identity object type. The nodes in the journey use this object type to
verify the identity, for example, users, roles, or organizations. The default journeys provided with Identity Cloud assume
the identity object using the journey to authenticate is a realm-name user, for example Alpha realm - Users
or
Bravo realm - Users
.
When you create a new journey, you select the object type from the Identity Object dropdown list.
To change the object type of an existing journey:
-
In the Identity Cloud admin UI select Journeys > Journey name > Edit.
-
On the journey page, click the ellipses () at the top right of the page, then click Edit details.
-
Select a new object type from the Identity Object dropdown list.
Enable and disable an authentication journey
Custom authentication journeys are enabled by default, when they are saved. For security purposes, you can disable custom authentication journeys during development and testing, to prevent accidentally allowing access through these journeys. Rather than having unused authentication journeys enabled, you should disable the default authentication journeys until you need them.
When a user attempts to authenticate through a disabled journey, Identity Cloud returns a Tree does not exist
error.
To enable or disable an authentication journey, set the enabled
flag in the journey configuration:
-
Over REST, send a PUT request to update the journey configuration. You must specify the journey ID and the nodes in the journey. This example disables the
myAuthTree
created previously:
$ curl \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5..." \
--header 'accept-api-version: protocol=2.1,resource=1.0' \
--header "If-Match: *" \
--request PUT \
--data '
{
"entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
"nodes": {
"c11e9cf8-ef48-4740-876f-6300e2f46aef": {
"displayName": "Page Node",
"nodeType": "PageNode",
"x": 147,
"y": 25,
"connections": {
"outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
}
},
"15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
"displayName": "Data Store Decision",
"nodeType": "DataStoreDecisionNode",
"x": 349,
"y": 25,
"connections": {
"true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
"false": "e301438c-0bd0-429c-ab0c-66126501069a"
}
}
},
"enabled": false
}' \
'https://https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree'
{
"_id": "myAuthTree",
"_rev": "2070284866",
"uiConfig": {},
"entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
"nodes": {
"c11e9cf8-ef48-4740-876f-6300e2f46aef": {
"displayName": "Page Node",
"nodeType": "PageNode",
"x": 147,
"y": 25,
"connections": {
"outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
}
},
"15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
"displayName": "Data Store Decision",
"nodeType": "DataStoreDecisionNode",
"x": 349,
"y": 25,
"connections": {
"true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
"false": "e301438c-0bd0-429c-ab0c-66126501069a"
}
}
},
"staticNodes": {
"startNode": {
"x": 50,
"y": 25
},
"70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
"x": 570,
"y": 30
},
"e301438c-0bd0-429c-ab0c-66126501069a": {
"x": 573,
"y": 107
}
},
"enabled": false
}
Configure authentication webhooks
Webhooks are used to send HTTP POST calls to a server with contextual information about an authentication session when a predefined event occurs, for example, logging out.
Webhooks are used from within authentication journeys, by the Register Logout Webhook node.
Create an authentication webhook
-
In the AM admin UI, go to Realms > Realm Name > Authentication > Webhooks.
-
Select Create Webhook, specify a Webhook Name, and select Create.
The webhook configuration screen is displayed:
-
Complete the fields as required:
- Url
-
The URL to which the HTTP POST is sent when the event occurs.
- Body
-
The body of the HTTP POST. To send different data formats, set the correct Content-Type header in the
Header
property, for example:-
Form Data. Enter the body value in the format
parameter=value¶meter2=value2
, and set aContent-Type
header ofapplication/x-www-form-urlencoded
. -
JSON Data. Enter the body value in the format
{"parameter":"value","parameter2":"value2"}
, and set aContent-Type
header ofapplication/json
.
-
- Headers
-
Any HTTP headers to add to the POST.
To add a header, enter the name of the header in the
Key
field, and the value, and then click the Add button (➕).To remove a header, select the Delete button (✖).
The fields in a webhook support variables for retrieving values from the user’s session after successfully authenticating. Specify a variable in the following format:
${variable_name}
.Any custom properties added to the session using the Set Session Properties node can be accessed by using a variable, as well as the following default session properties:
Table 1. Default Session Properties Property Example value Description AMCtxId
22e73c81-708e-4849-b064-db29b68ef943-105372
The audit ID for the session. This is logged as the
trackingIds
field in Identity Cloud access audit logs.authInstant
2022-02-28T14:06:31Z
The exact time that authentication completed.
AuthLevel
5
The authentication level of the session, determined by the login mechanism used to create the session. For example, a journey can have an authentication level of 10.
Step-up authentication is triggered if an authentication level specified by an agent or policy that is designed to protect a resource, is greater than or equal to the value of the
AuthLevel
session property.For more information, refer to Session upgrade with MFA.
CharSet
UTF-8
The character set for the session, set to
UTF-8
.clientType
genericHTML
The type of client, set to
genericHTML
.FullLoginURL
https://example.forgeblocks.com/platform/?realm=alpha
The full login URL, including query parameters.
Host
192.0.2.1
The originating IP address of the authentication request.
HostName
192.0.2.1
The host name that was used when the session was authenticated.
IndexType
service
Based on the value of the
authIndexValue
query parameter during authentication. Typically, this is set toservice
.Locale
en_US
The session locale.
loginURL
/openam/UI/Login
The base login URL. A subset of
FullLoginURL
.OidcSid
g0wmSpoAIwH6HAwCnurvRcfYqh4
Unique session ID used by Identity Cloud to determine whether OIDC ID tokens granted for the same client relate to the same session. This appears when
Enable Session Management
(storeOpsToken
) is set to true in the OAuth 2.0 provider settings.Organization
o=alpha,ou=services,dc=openam,dc=forgerock,dc=org
The DN of the realm where authentication took place.
Principal
id=demo,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org
The value of
sun.am.UniversalIdentifier
.Principals
demo
The username for the session.
Service
Example
The name of the journey that was used to authenticate this session.
successURL
/openam/console
The URL that was redirected to, upon a successful login request.
sun.am.UniversalIdentifier
id=demo,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org
The DN of the user (username is lowercase).
UserId
demo
The
id
value from thePrincipal
property.UserProfile
Required
Can be one of:
Required
,Create
,Ignore
, orCreateWithAlias
. Based on the value of thedynamicProfileCreation
authentication configuration. Values other thanIgnore
indicates that user profile attributes were mapped based on theUser Attribute Mapping to Session Attribute
setting. Refer to authentication configuration for details.Default:
Required
.UserToken
demo
The username, as defined in the
Principal
property.The following figure shows an example webhook, using variable substitutions:
Specifying a variable that is not present in the user’s session places the literal variable text in the HTTP POST, for example
user=${UserId}
, rather thanuser=demo
.