Identity Cloud

Authentication nodes and journeys

Authentication journeys (previously referred to as trees) 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. This allows you to create complex yet customer-friendly authentication experiences by linking nodes together, creating loops and sections for different authentication scenarios, and nesting nodes within a journey:

Create multiple paths for authentication by linking nodes within journeys.
Figure 1. Example Authentication Journey

To further control the authentication process, you can assign authentication levels to sections of a journey, with higher levels being used typically to allow access to more restricted resources.

Authentication levels for journeys

When a user successfully authenticates, AM creates a session, which allows AM 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, simple username and password may be assigned a low authentication level, whereas multi-factor with push and webAuthn, a high one.

Authorization policies may 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, AM denies access to the resource and returns an advice indicating that the user needs to reauthenticate at the required authentication level to access the resource.

The web or Java agent or policy enforcement point can then send the user back to AM for session upgrade. For more information, see Session upgrade

AM provides the following nodes to manage authentication levels:

Position these nodes to alter the authentication level depending on the route taken through the authentication flow.

Account lockout for journeys

It is recommended to 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 in AM have built-in support for account lockout, and provide nodes for checking the status of a user, and changing their status:

Account Active Decision node

Use this node to determine if an account is marked as active, or inactive (locked).

Account Lockout node

Use this node to alter the user’s status, to either active, or inactive (locked).

When setting an account to active, the node will also reset the failed attempts and lockout duration counters.

In addition to the lockout-specific nodes above, the Success and Failure nodes include account lockout functionality, when lockout is enabled in a realm, as follows:

Success node
  • Checks the User Status property of the user profile, when reached, and fails the authentication with an error message, if the account is marked as Inactive:

    Account locked error when reaching Success node.

    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
  • Checks the invalid attempts property of the user profile, and returns a warning message if the number of failed attempts is equal to or greater than the configured Warn User After N Failures value in the realm:

    Invalid attempts limit warning when reaching Failure node.

    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:

    Account locked error when reaching Failure node.

    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":""
        }
    }

Specify IDM identity resources in journeys

When running AM as part of an integrated platform with IDM, journeys configured to use the platform need to identify the type of identity resource or object the journey is working with. To do this, use the identityResource configuration property. If the property is not included in the journey configuration, it will default to managed/user.

To update identityResource for a journey, use the REST API:

$ curl \
 --request PUT \
 --header 'Accept-API-Version: protocol=2.1,resource=1.0' \
 --header 'Accept: application/json' \
 --header 'If-None-Match: *' \
 --header 'Content-Type: application/json' \
 --header 'Cookie: <omitted for length>' \
 --data '{
   "entryNodeId":"e301438c-0bd0-429c-ab0c-66126501069a",
   "nodes":{},
   "staticNodes":{},
   "description":"Example journey description",
   "identityResource":"managed/newObjectType"
 }' \
 "https://default.iam.example.com/am/json/realms/root/realm-config/authentication/authenticationtrees/trees/ExampleJourney"

In the above example, the journey ExampleJourney has no nodes added to it yet. It includes the identityResource property, set to use a managed object in IDM called newObjectType.

Since this is a PUT request, you need to include the entire journey as part of the request. For more information about using REST with AM, see Introduction to REST in AM.

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. For this reason, AM allows you to 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 AM.

Configure your authentication journeys

Use the journey editor to put together your journeys quickly.

Configure webhooks, if required

If you have configured the Register Logout Webhook node, configure its webhook.

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, AM 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://<tenant-name>.forgeblocks.com/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

This section covers creating webhooks, which 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

Perform the following steps to create a webhook for use within an authentication journey:

  1. In the AM admin UI, go to Realms > Realm Name > Authentication > Webhooks.

    1. To create a new webhook, select Create Webhook, specify a Webhook Name, and select Create.

    2. To edit an existing webhook, select the name of the webhook.

    A screen similar to the following appears:

    Creating a new authentication webhook.
  2. Complete the fields as required:

    Url

    Specifies the URL to which the HTTP POST is sent when the event occurs.

    Body

    Specifies the body of the HTTP POST. You can send different formats by also setting the correct Content-Type header in the Header property, for example:

    • Form Data. Enter the body value in the format parameter=value&parameter2=value2, and set a Content-Type header of application/x-www-form-urlencoded.

    • JSON Data. Enter the body value in the format {"parameter":"value","parameter2":"value2"}, and set a Content-Type header of application/json.

    Headers

    Specifies 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 (✖).

    Each of the fields in a webhook supports 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 AM access audit logs.

    amlbcookie

    01

    The cookie that identifies the AM server that generated the session. For environments with multiple AM servers, this can be used for load balancer stickiness.

    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, see Session upgrade.

    CharSet

    UTF-8

    The character set for the session, set to UTF-8.

    clientType

    genericHTML

    The type of client, set to genericHTML.

    FullLoginURL

    /openam/UI/Login?realm=%2Falpha

    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 to service.

    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 AM 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 the Principal property.

    UserProfile

    Required

    Can be one of: Required, Create, Ignore, or CreateWithAlias. Based on the value of the dynamicProfileCreation authentication configuration. Values other than Ignore indicates that user profile attributes were mapped based on the User Attribute Mapping to Session Attribute setting. See 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:

    Example authentication webhook.

    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 than user=demo.

Copyright © 2010-2022 ForgeRock, all rights reserved.