--- title: Configure journeys description: You can configure journeys in the Advanced Identity Cloud admin console or over REST: component: pingoneaic page_id: pingoneaic:am-authentication:configure-authentication-trees canonical_url: https://docs.pingidentity.com/pingoneaic/am-authentication/configure-authentication-trees.html keywords: ["Authentication", "Nodes & Trees", "Journeys", "Setup & Configuration"] section_ids: identity-resource-journeys: Specify the identity object type for a journey disable-authn-tree: Enable and disable an authentication journey disable-child-journey: Disable direct access through an inner journey enable-journey-completion: Configure an authentication journey to always run configure-nosession-tree: Configure a no session journey configure-transactional-auth-journey: Configure a transactional authentication journey configure-journey-session-duration-tree: Configure journey session duration in a journey configure-auth-session-timeouts-tree: Configure authenticated session timeouts in a journey --- # Configure journeys You can configure journeys in the Advanced Identity Cloud admin console or over REST: * Advanced Identity Cloud admin console: 1. Go to Journeys > Journeys > *journey name* > Edit. 2. In the journey editor, click the More ([icon: ellipsis-h, set=fa]) menu at the top right of the page, then click Edit Details and update the journey configuration. * REST: Send a PUT request to update the journey configuration. You must include the journey ID and all the nodes in the journey in the request. This table outlines the high-level tasks for configuring authentication journeys: | Task | Description | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Specify the identity object type for a journey](#identity-resource-journeys) | Specify the identity object a journey should use. For example `Alpha realm - Users`. | | [Enable and disable an authentication journey](#disable-authn-tree) | Disable journeys during development or when they aren't in use to enhance security. | | [Disable direct access through an inner journey](#disable-child-journey) | Prevent an inner journey from being called directly, ensuring it's only used within its parent journey. | | [Configure an authentication journey to always run](#enable-journey-completion) | Force a journey to execute on every authentication attempt, even if a valid session already exists. | | [Configure a no session journey](#configure-nosession-tree) | Create a journey that completes successfully without creating an authenticated session, ideal for tasks like delegated administration. | | [Configure a transactional authentication journey](#configure-transactional-auth-journey) | Indicate a journey can only be used for transactional authentication purposes, including backchannel authentication, OAuth 2.0 app journeys, SAML 2.0 app journeys, and transactional authorization. | | [Configure journey session duration in a journey](#configure-journey-session-duration-tree) | Override the maximum duration of the journey session for a specific journey, for example, to allow more time for an email verification step. | | [Configure authenticated session timeouts in a journey](#configure-auth-session-timeouts-tree) | Set custom session idle and maximum timeout values for authenticated sessions created by a specific journey. | ## Specify the identity object type for a journey Journeys assume a specific *identity object type*. The nodes in the journey use this object type to verify the identity, for example, users, roles, or organizations. Only objects of type *user* can authenticate. The default journeys provided with Advanced Identity Cloud assume the object authenticating through the journey 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 in the Identity Object list. To change the object type of an existing journey: 1. In the Advanced Identity Cloud admin console, go to Journeys > Journeys > *journey name* > Edit. 2. In the journey editor, click the More ([icon: ellipsis-h, set=fa]) menu at the top right of the page, then click Edit Details. 3. Select a new object type from the Identity Object 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 journeys during development and testing, to prevent accidentally allowing access through these journeys. Rather than having unused journeys enabled, you should disable the default journeys until you need them. When a user attempts to authenticate through a disabled journey, Advanced Identity Cloud returns a `Tree does not exist` error. To enable or disable a journey through the Advanced Identity Cloud admin console, follow the steps to [deactivate journeys](../journeys/journeys.html#deactivate-journeys). To enable or disable a journey over REST, send a PUT request to update the journey configuration. Specify the journey ID, the nodes in the journey, and set the `enabled` property. > **Collapse: Example** > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "nodes": { > ... > }, > "enabled": false > }' \ > 'https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree' > { > "_id": "myAuthTree", > "_rev": "2070284866", > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": false, > "noSession": false, > "mustRun": false, > "enabled": false, > "transactionalOnly": false, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` ## Disable direct access through an inner journey An inner (or child) journey lets you nest authentication logic. There is no limit to the depth of nesting. You configure an inner journey like any other journey and call it from a parent journey using an [Inner Tree Evaluator node](https://docs.pingidentity.com/auth-node-ref/latest/inner-tree-evaluator.html). You might want to hide inner journeys as complete services. In other words, you might want to prevent users from authenticating directly through a inner journey, either for security reasons or simply because the inner journey is insufficient as a complete authentication service. Additionally, inner journeys can't be used as [transactional authentication journeys](#configure-transactional-auth-journey). To use the Advanced Identity Cloud admin console to ensure an inner journey is only called from its parent, select the Inner journey checkbox when you create a [custom journey](../journeys/journeys.html#custom-journey) or edit an existing journey. To configure an inner journey over REST, send a PUT request to update the journey configuration. Specify the journey ID, the nodes in the journey, and set the `innerTreeOnly` property to `true`. > **Collapse: Example** > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "nodes": { > ... > }, > "innerTreeOnly": true > }' \ > 'https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree" > { > "_id": "myAuthTree", > "_rev": "2070284866", > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": true, > "noSession": false, > "mustRun": false, > "enabled": true, > "transactionalOnly": false, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To find out if the current journey is configured as an inner journey only, include a Scripted Decision node with a script that calls `journey.innerJourney()`.Learn more in [Get journey details](../am-scripting/script-bindings.html#common-journey). | ## Configure an authentication journey to always run You can set a journey to always execute whether a user has already authenticated successfully and a session exists or not. If enabled, the journey runs even when the session was created through a different journey and irrespective of the value of the [ForceAuth](authn-from-browser.html#authentication-forceAuth) parameter. If you have configured an *app journey*, for example, by associating a journey with a SAML 2.0 application, then you don't need to configure the journey to always run because this is default functionality for app journeys. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can't configure a journey to always run when it's set as the **default** journey.Because the default journey is often used as a fallback option for many authentication flows, for example, for Ping SDKs flows over REST, a forced execution of a journey could inadvertently lead to unexpected behavior.Also, to prevent unexpected behavior in the authentication flow, don't configure a journey to always run when it's mapped to the [default ACR](../am-oidc1/oidc-authentication-requirements.html#acr-claim). | If a user successfully logs in using a specific authentication journey and then tries to reauthenticate to the same journey while the session is still valid, the default behavior is for the authentication flow to skip the processing of the journey. For example, the [Set Session Properties node](https://docs.pingidentity.com/auth-node-ref/latest/set-session-properties.html) is never run in this scenario: ![Authentication journey to demonstrate mustRun property](_images/auth-mustrun-journey.png) To use the Advanced Identity Cloud admin console to make sure the journey always runs, select the Run journey for all users regardless of current session checkbox when you create a [custom journey](../journeys/journeys.html#custom-journey) or edit an existing journey. To use the REST API to configure a journey to always run, send a PUT request to update the journey configuration. Specify the journey ID, the nodes in the journey, and set the `mustRun` property to `true`. > **Collapse: Example** > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "83fa0ce2-1b0f-4f8f-83fb-0d2648339797", > "nodes": { > ... > }, > "mustRun": true > }' \ > 'https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree" > { > "_id": "myAuthTree", > "_rev": "2070284866", > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": false, > "noSession": false, > "mustRun": true, > "enabled": true, > "transactionalOnly": false, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` ## Configure a no session journey A no session journey doesn't result in an authenticated session when it successfully completes. A common use case for a no session journey is a delegated admin task, such as an administrator changing a user's password. In this scenario, you don't want an authenticated session to be created when the administrator enters the credentials of the user whose password they are changing. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This can also be achieved by setting the [`noSession` query parameter](authenticate-endpoint-parameters.html#nosession). However, consider that an end user could remove the query parameter to create a session.If the `noSession` property is set to `true` in either the journey or the query parameter, the resulting journey won't create an authenticated session. | To use the Advanced Identity Cloud admin console to configure a no session journey, select the No Session checkbox when you create a [custom journey](../journeys/journeys.html#custom-journey) or edit an existing journey. To configure a no session journey over REST, send a PUT request to update the journey configuration. Specify the journey ID, the nodes in the journey, and set the `noSession` property to `true`. > **Collapse: Example** > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "nodes": { > ... > }, > "noSession": true > }' \ > "https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree" > { > "_id": "myAuthTree", > "_rev": "2070284866", > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": false, > "noSession": true, > "mustRun": false, > "enabled": true, > "transactionalOnly": false, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` ## Configure a transactional authentication journey In Advanced Identity Cloud, certain advanced authentication flows initiate a temporary, secure process known as a *transaction* to handle a specific authentication or authorization event. You can configure journeys for these flows as *transactional authentication journeys* to manage the user interaction required to complete the transaction. This prevents users from authenticating directly through the journey, either for security reasons or because the transactional journey is insufficient as a complete authentication service. Additionally, transactional authentication journeys can't be used as [child journeys](#disable-child-journey). | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | You don't *have to* configure the journey used in a transactional flow as a transactional authentication journey. | A transactional authentication journey only runs when Advanced Identity Cloud starts a transaction, which happens when Advanced Identity Cloud does one of the following: * Initializes [backchannel authentication](backchannel-authentication.html) using either the `/authenticate/backchannel/initialize` endpoint or the [Backchannel Initialize node](https://docs.pingidentity.com/auth-node-ref/latest/backchannel-initialize.html). * Runs a [SAML 2.0 app](../am-saml2/configure-providers.html#samlapp-journey) journey for a remote SP. * Runs an [OAuth 2.0 app](../am-oauth2/oauth2-register-client.html) journey when Advanced Identity Cloud is acting as an authorization server. * Enforces a [transactional authorization](../am-authorization/transactional-authorization.html) policy. To use the Advanced Identity Cloud admin console to make the journey a transactional authentication journey, select the Transactional Only checkbox when you create a [custom journey](../journeys/journeys.html#custom-journey) or edit an existing journey. To configure a transactional authentication journey over REST, send a PUT request to update the journey configuration. Specify the journey ID, the nodes in the journey, and set the `transactionalOnly` property to `true`. > **Collapse: Example** > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "nodes": { > ... > }, > "transactionalOnly": true > }' \ > "https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree" > { > "_id": "myAuthTree", > "_rev": "1081620278", > "uiConfig": {}, > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": false, > "noSession": false, > "mustRun": false, > "enabled": true, > "transactionalOnly": true, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` ## Configure journey session duration in a journey The maximum duration of a journey session is derived by Advanced Identity Cloud as described in [Maximum duration](suspended-auth.html#maximum-duration). You can override realm level duration values in an individual journey if required. For example, a journey that requires email verification could have a longer duration than a simple journey that authenticates users with a username and password. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Duration values set in a journey can be overridden at the node level. Learn more in [Maximum duration](suspended-auth.html#maximum-duration).Additionally, duration values set on inner journeys are ignored. | Learn more in [Suspend journey progress](suspended-auth.html). To change the authentication journey duration, set the `treeTimeout` property to the required number of minutes in the journey configuration. Send a PUT request to update the journey configuration, including the journey ID and all the nodes in the journey. > **Collapse: Example** > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "nodes": { > ... > }, > "treeTimeout": 10 > }' \ > "https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree" > { > "_id": "myAuthTree", > "_rev": "2070284866", > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": false, > "noSession": false, > "mustRun": false, > "treeTimeout": 10, > "enabled": true, > "transactionalOnly": false, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` ## Configure authenticated session timeouts in a journey Timeout settings for an authenticated session are derived by Advanced Identity Cloud as described in [Configure authenticated session timeout settings](../am-sessions/session-state-session-termination.html#auth-session-termination-config). You can override realm level timeout values in an individual journey if required. For example, a journey that implements MFA could have a longer authenticated session timeout than a simple journey that authenticates users with a username and password. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Session timeouts set in a journey can be overridden at the node or user level. Learn more in [Configure authenticated session timeout settings](../am-sessions/session-state-session-termination.html#auth-session-termination-config).Session timeout values set on child journeys are ignored. However, if session timeouts are set at the *node* level in a child journey, the updated timeouts are used in the parent journey. | Learn more in [Session termination](../am-sessions/session-state-session-termination.html). To use the Advanced Identity Cloud admin console to change the session timeouts, select the Override authenticated session timeout checkbox when you create a [custom journey](../journeys/journeys.html#custom-journey) or edit an existing journey. Then enter the required number of minutes in the Maximum Authenticated Session Time and Maximum Authenticated Session Idle Time fields. To configure the session timeouts over REST, send a PUT request to update the journey configuration. Specify the journey ID, the nodes in the journey, and set the `maximumSessionTime` and `maximumIdleTime` properties to the required number of minutes. > **Collapse: Example** > > The following example sets the `maximumSessionTime` to an hour and the `maximumIdleTime` to 15 minutes for authenticated sessions established through this journey: > > ```bash > $ curl \ > --header "Content-Type: application/json" \ > --header "Authorization: Bearer " \ > --header "Accept-API-Version: protocol=2.1,resource=1.0" \ > --request PUT \ > --data '{ > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "nodes": { > ... > }, > "maximumSessionTime": 60, > "maximumIdleTime": 15 > }' \ > "https:///am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree" > { > "_id": "myAuthTree", > "_rev": "2070284866", > "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef", > "innerTreeOnly": false, > "maximumSessionTime": 60, > "maximumIdleTime": 15, > "noSession": false, > "mustRun": false, > "enabled": true, > "transactionalOnly": false, > "uiConfig": {}, > "nodes": { > ... > } > } > ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To find out if the current journey is configured to always run, include a Scripted Decision node with a script that calls `journey.mustRun()`.Learn more in [Get journey details](../am-scripting/script-bindings.html#common-journey). |