Design your authentication journeys

You can design authentication journeys that range from simple and straightforward to complex with conditions, multiple paths or branches, or post-authentication steps.

After you design an authentication journey, you need to configure how to initiate the journey, such as by making it the default journey.

Unpublished and published journeys

Authentication journeys have these basic states:

• Unpublished: Unpublished journeys are not available for authentication. They include new, draft, or saved journeys and can contain errors. You can save unpublished journeys without publishing them.

• Published: Published journeys are available for user authentication. You can publish a journey only only if all paths in the journey are valid. Valid paths meet both the identification and authentication requirements. Valid paths also connect Start and Logged in.

  When you publish a journey, it immediately goes live in production. After you publish a journey, you must publish all subsequent changes. You cannot save a published journey without publishing the updates.

Assurance levels

For the authentication options, the assurance level reflects the degree or trust or assurance in the authentication that is performed. It is a measure of the confidence in and the strength of an authentication mechanism and its issuing process. A higher assurance level reduces the risk of a fraudulent identity gaining access.

Applications can specify the assurance level that users must attain before access is granted. You can set the assurance level that each authentication step in a journey provides. When a user successfully authenticates with the authentication method for that step, the assurance level is updated to that level.

When you add an authentication method to a journey, you can select the assurance level that the user achieves after they complete that step.

The OneWelcome Identity Platform returns only the assurance level that the application requests, even if the authentication step in the journey provides the highest assurance level. This is because the OneWelcome Identity Platform doesn't provide an assurance level that is more powerful than needed, in accordance with the principle of least privilege. The assurance level that the authentication method provides is stored in the session for future single sign-on (SSO), in case a higher level is requested later.

You can customize the assurance levels that are available to select in authentication journeys. To configure the assurance levels, use the Access configuration and end user APIs. Each assurance level has an ID, a name, and a value.

Add an authentication journey

1. On the OneWelcome Identity Platform console, select Orchestration > Journeys > Authentication.

   The Authentication Journey page lists the existing journeys.

   

2. Select Add journey.

   A new, blank, unpublished journey opens in the journey editor.

   

3. In the side sheet on the right, under Journey information, enter a Name and (optional) Description. To close the side sheet, select Close.

4. To save your progress, select Save.

   Saving the journey means that it remains unpublished, and you can continue to make changes before publishing it.

   After you save, if you make changes that you don't want, select Discard to revert to the last saved version.

5. To make the journey live in production where users can access it, select Publish. Any subsequent updates must be published.

Add user identification

The first step in a journey allows the user to provide their identification. All identification options except Identifier also provide authentication.

1. In the Identification column, select the plus sign in the Step required block.

   The side sheet on the right slides open and shows the Identification options.

   

2. In this side sheet, select an identification option in the authentication journey:

   IDP from Identity Broker

   Federate with social or general identity providers that you configured in the identity broker. You can add multiple instances of the IDP from Identity Broker for different IDPs.

   

   Enter the IDP information:

   • Name: Enter a name for the IDP that is configured in the identity broker. This name is used on both the journey editor and the user login screen, such as Log in with Facebook or Sign in with Google.
   • Description (optional)
   • Identity provider: Lists all of the IDPs that you configured in the identity broker.
   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   Identifier

   Prompt users to provide a unique identifier, which can be either their username, email address, or phone number. This identifier is used to look up and verify the user's account information in the system.

   

   Enter the identifier information:

   • Name: The name is used on the journey editor.
   • Description (optional)
   • User attribute: The options are Username, Email, and Phone number.
   • Account registration link: The link uses this formula https://{{idp_base_url}}/{{brand}}/registration/, but you can override it if necessary. The default link points to the registration flow. The system resolves the placeholders in the link. If left empty, the link is not displayed to users.

   Identifier + Password

   Prompt the user to first provide their unique identifier, such as a username, email, or phone number, to locate their account in the system, and then provide their password to authenticate.

   This option includes both identification and authentication in one step, which means that you don't necessarily need an additional step for authentication.

   

   Enter the identifier and password information:

   • Name: This name is used on the journey editor.

   • Description (optional)

   • User attribute: The options are Username, Email, and Phone number.

   • Account registration link: The link uses this formula https://{{idp_base_url}}/{{brand}}/registration/, but you can override it if necessary. The default link points to the registration flow. The system resolves the placeholders in the link. If left empty, the link is not displayed to users.

   • Forgot password link: The link uses this formula https://{{idp_base_url}}/{{brand}}/passwordreset/, but you can override it if necessary. The default link points to the password reset flow. The system resolves the placeholders in the link. If left empty, the link is not displayed to users.

   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   Passkey

   Generate a challenge and prompt users to provide their passkey authenticator to sign the challenge. The signed challenge is then verified. When necessary, the step also performs a user lookup to confirm the user's identity.

   When passkey is used for the identification step, it is anonymous. This means that any compliant authenticator is accepted and the result is that you identify and authenticate the user.

   

   Enter the passkey information:

   • Name: This name is used on both the journey editor and the user login page.

   • Description (optional)

   • Account registration link: The link uses this formula https://{{idp_base_url}}/{{brand}}/registration/, but you can override it if necessary. The default link points to the registration flow. The system resolves the placeholders in the link. If left empty, the link is not displayed to users.

   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

3. Save or Publish your changes.

Add user authentication

You can add one or two authentication steps to a journey. Each authentication step can have multiple authentication options. If you add conditions, you need to add an authentication for each branch that the condition creates.

1. In an Authentication column, select the Step required plus sign.

   

   The side sheet on the right slides open and shows the Add authentication options.

2. In this side sheet, select an authentication option in the authentication journey:

   IDP from Identity Broker based on home realm detection

   Automatically detect the user's realm based on the provided identifier and forward the user to the appropriate external IDP for authentication. The realm is mapped to a specific IDP.

   Includes only IDPs from the Identity Broker (does not include IDPs configured in the Core).

   A journey can include multiple home-realm detection steps.

   

   Enter the IDP information:

   • Name:
   • Description (optional)

   • Use attribute to send: All home-realm detection steps in a journey must use the same lookup, or login hint, attribute.

     • Pass through the username attribute from the previous step: Forward whatever the user entered in the identifier step.

     • Primary Email Address: After looking up the user by identifier, the system forwards the contents of the email attribute to the external IDP. For example, you can look up by username but forward the email to the external IDP.

     • Username: After looking up the user by identifier, the system forwards the contents of the username attribute to the external IDP. For example, you can lookup by email but forward the username to the external IDP.

   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   IDP from Identity Broker

   Federate with social or general identity providers that you configured in the identity broker. You can add multiple instances of the IDP from Identity Broker.

   

   Enter the IDP information:

   • Name: Enter a name for the IDP that is configured in the identity broker. This name is used on both the journey editor and the user login screen, such as Log in with Facebook or Sign in with Google.
   • Description (optional)
   • Identity provider: Lists all of the IDPs that you configured in the identity broker.
   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   You can add multiple instances of the IDP from the identity broker to a group.

   Passkey

   Generate a challenge and prompt users to provide their passkey authenticator to sign the challenge. The signed challenge is then verified. When necessary, the step also performs a user lookup to confirm the user's identity.

   When passkey is used for the 2nd or 3rd step, the list of allowed FIDO authenticators includes only the the authenticators that the user has enrolled.

   

   Enter the passkey information:

   • Name

   • Description (optional)

   • Account registration link: The link uses this formula https://{{idp_base_url}}/{{brand}}/registration/, but you can override it if necessary. The default link points to the registration flow. The system resolves the placeholders in the link. If left empty, the link is not displayed to users.

   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   Password

   Prompt the user to enter their password to confirm their identity. The password is verified to ensure that the user's credentials match the account information. The password step comes after the user identifier step, because the password needs to authenticate together with the username.

   

   Enter the password information:

   • Name: This name is used on both the journey editor and the user login page.

   • Description (optional)

   • Forgot password link: The link uses this formula https://{{idp_base_url}}/{{brand}}/passwordreset/, but you can override it if necessary. The default link points to the password reset flow. The system resolves the placeholders in the link. If left empty, the link is not displayed to users.

   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   SMS OTP

   Generate a unique, time-sensitive, single-use code and send it to the user's primary phone number by SMS. The user must enter this code into the login page to verify their identity and proceed. SMS OTP comes after a user identifier step, because it needs the user's account information to determine where to send the OTP code.

   

   Enter the SMS OTP information:

   • Name: This name is used on both the journey editor and the user login page.

   • Description (optional)

   • Assurance level: Lists the authentication assurance levels that are configured using the Access configuration and end user APIs. Web clients or applications can request that users meet a specific authentication assurance level.

   Fail

   This option is available only for conditions. Select this option to Fail authentication and prevent users on this path from logging in.

   

3. Save or Publish your changes.

Add a condition

Add an optional condition between steps to modify the authentication requirements under different contexts. The conditions create branches on the path through a journey, where each branch has different authentication requirements or methods. A condition can also have a branch that leads to authentication failure.

1. Select the plus sign between the columns where you want to add the condition.

   

2. On the Add condition side sheet, select a condition:

   

   • Realm can be federated: This condition is based on home realm detection. It checks whether the realm from the email address that the user provides can be federated through an identity provider (IDP) that you configured in the identity broker.

     

     1. On the Condition side sheet, enter the Name and optional Description. The default name is Realm can be federated.

     2. Select the Step required plus sign for the True branch and then select IDP from Identity Broker based on home realm detection.

     3. Select the Step required plus sign for the False branch, and then select a different authentication method.

        The options are the same as for adding user authentication but there is an additional option to Fail authentication and prevent users on this path from logging in.

        

   • Risk level: This condition checks whether there is a low, medium, or high risk level based on the IdCloud Fraud Prevention policies. It creates Low, Medium, and High branches.

     

     1. On the Condition side sheet, enter the Name and an optional Description. The default name is Risk level.

        The authentication options are the same as for adding user authentication but there is an additional option to Fail authentication and prevent users from logging in.

     2. Select the Step required plus sign for the Low branch, and then select an authentication option.

     3. Select the Step required plus sign for the Medium branch, and then select an authentication option.

     4. Select the Step required plus sign for the High branch, and then select an authentication option.

        

3. Save or Publish your changes.

Add a post-authentication step

You can add post-authentication steps to the end of journey. Post-authentication steps are non-authentication processes that are performed before the session is granted.

1. On the journey editor, select the Post-authn plus sign.

   

2. On the Add post-authentication step side sheet, select an option:

   

   • Persona selection: Checks whether the user belongs to more than one organization and prompts the user to select their organization. The user's authorization for specific apps might differ based on the organization.

     

     1. Enter a Name and optional Description.

1. Save or Publish your changes.

Change the order of groups and options

You can move groups and the options in the groups so that they appear in the order that you want to show on the user login pages.

Groups have the following menu items:

• Move group up: Move the entire group up on the journey editor and the user login page.

• Move group down: Move the entire group down on the journey editor and the user login page.

• Delete group and path: When you delete a group, all options in the group are deleted and the rest of the path is also deleted.

The options in the identification and authentication columns have the following menu items:

• Move up: Move the item up on the journey editor and the user login page.

• Move down: Move the item down on the journey editor and the user login page.

• Add group separator above: Moves the option to a new group that is below the current group. Move existing options up or down to add them to the group.

• Add group separator below: Moves the option to a new group that is above the current group. Move existing options up or down to add them to the group.

Delete unwanted steps

The system doesn't automatically clean up unused steps. This means that a journey can end up with unused steps that don't proceed through to the user being Logged in.

In the following example, there is an invalid path, because it has an identification step, but it doesn't have an authentication step. The path has a Step required block, to indicate that it's incomplete. Because the path is incomplete, the journey is invalid and you cannot publish it.

You have several possible courses of action:

• Save the incomplete journey in the unpublished state.

• Add the authentication step to complete the path, and then save or publish it.

• Delete the identification step from the incomplete path.

• Delete the incomplete path.

1. To delete an unwanted step, in the journey editor, select the step that you want to delete. In the example shown above, this is the identification step.

2. You can delete a step using the side sheet, step menu, or group menu:

   • To delete the step using the side sheet, at the bottom-left of the side sheet, select Remove step.

     

   • To delete the step using the step menu, select the menu and and then select Delete.

     

   • To delete the step using the group menu, select the group menu and then select Delete group and path.

     

Duplicate an authentication journey

The easiest way to create a new authentication journey, is to start from a journey that has similar steps.

1. Duplicate a journey from the Authentication Journey screen or from the journey screen:

   • To duplicate a journey from the Authentication Journey screen, locate the journey that you want to duplicate. In the journey menu, select Duplicate.

     

   • To duplicate a journey from the journey screen, select the journey to open it in the journey editor. In the top-right corner of the journey editor, select the menu, and then select Duplicate.

     

2. Update the journey as required, and then Save or Publish.

Update an authentication journey

1. On the Authentication Journey page, select the journey that you want to update, or in the journey menu, select View details.

   The authentication journey opens in the journey editor.

   

2. To view details about the journey, select the Side sheet handle.

   The journey details include the name, description, Journey ID, status, version, and last update date.

   

3. Update the journey and steps as required, and then Save or Publish.

Unpublish an authentication journey

When you unpublish an authentication journey, the journey is taken offline and is no longer available for authentication. You cannot unpublish the default journey.

1. On the Authentication Journey screen, select the journey that you want to unpublish, or in the journey menu, select View details.

2. In the top-right corner of the journey editor, select the menu, and then select Unpublish.

   

Delete an authentication journey

You cannot delete the default journey or published journeys. To delete the default journey, you must first set another journey as default. To delete a published journey, first unpublish the journey.

1. On the Authentication Journey screen, select the journey that you want to delete, or in the journey menu, select View details.

2. In the top-right corner of the journey editor, select the menu, and then select Delete.