Authentication journeys

Authentication journeys include identification and authentication steps, such as providing identifiers and authentication methods. Unlike other user journeys, they don't include other kinds of steps, such as business processes.

For authentication journeys, the Access component serves as the main entry point. You configure the relying parties (RP) on the Access admin console, which is responsible for validating incoming federated login protocol requests. After validation, Access hands over the request to the user journey orchestration module to perform the actual user authentication.

The user journey orchestration module does not manage any user data. Upon successful authentication, Access connects with an identity store and authentication backend to compile the user claims requested by the relying party. At this point, the user journey orchestration module only supports authentication where Thales hosts the user interface.

Parts of an authentication journey

Each journey follows a basic workflow that you can edit in the journey editor:

Start

The Start is simply the entry point for the journey. There is nothing to configure for the journey start.

Steps

You can configure up to three steps for each journey. Each step translates to a single page, or screen, for the user.

There are the following types of step options:

• Identification (ID): The user provides their identifier and the system performs user lookup. The Identifier is the only step option that provides only the identification requirement.

• Authentication (Authn): The user provides their credential and the system validates it. The available authentication options depend on what is configured for your tenant and brand.

• Identification and authentication: These options either combine the identification and authentication requirements in one step, like Identifier & password, or can be used for both identification and authentication, like IDP from Identity Broker.

A journey is valid only if it includes at least one identification step and one authentication step in every path. The path is the line that progresses through each step in the journey.

Each step can include multiple options. These options are shown in a column, or stack, on the journey editor. For example, you can include multiple authentication methods that the user can choose from, such as SMS OTP, passkey, or password.

The order of the step options on the journey editor is the same order that's shown on the user page.

1st step

The first step can include multiple options, which are organized into groups. The first step can be an identification (Identifier) or identification and authentication step.

The following options are available for the first step:

IDP from Identity Broker

Federate with social or general identity providers that you configured in the identity broker.

Enter the IDP information:

• Name: Enter a name for the IDP that is configured in the identity broker.
• 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
• 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 a second step for authentication.

Enter the identifier and password information:

• Name

• 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 first 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

• 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.

2nd and 3rd steps

The second and third steps can only be authentication steps.

The following options are available for the second and third steps:

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 identity provider (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.

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

• 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 system to verify their identity and proceed. SMS OTP generally 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

• 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.

Groups

Although all steps can include multiple step options, only the first step uses groups. Within the first step, multiple step options are organized into groups. When you add step options that cannot belong to the same group, the system creates a new group. For example, the Identifier option is incompatible with other options, so it is always in a group by itself.

You can add some step options, such as IDP from the identity broker, several times per group or page, and some options, such as Identifier, only once per group or page.

Each group starts a separate path through the authentication journey.

The following example shows a login screen with multiple step options that are separated into groups:

Group separators

A group separator is a line that separates groups of step options.

Group separators do not necessarily create groups on the user login page. In the following example, the group separators on the journey editor are not the same on the user login page.

When you delete a group, the rest of the path is also deleted.

Pages

A page shows the selection of step options that the user sees on a page, or screen.

For the first step, the user sees all of the options on one page. That page includes the groups and group separators, and the options are listed in the same order that you see in the journey editor.

For the second and third steps, each path and step combination becomes a different page for the user.

Conditions

Conditions modify the authentication requirements under different contexts.

You add conditions between steps in an authentication journey. The conditions create branches in the journey, where each branch has different authentication requirements or methods.

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.

The Realm can be federated condition has True and False branches:

• True: This branch leads to the IDP from Identity Broker based on home realm detection authentication method.

• False: This branch leads to any other authentication method, except home realm detection.

Logged in

The result of a successful authentication journey is that the user is logged in.

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 contain one identification step and at least one authentication step. 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

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.

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 use 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.

Add the first step

The first step verifies the user's identity. Some step options also authenticate the user.

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

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

   

2. In this side sheet, select the first step in the authentication journey:

   • IDP from Identity Broker

   • Identifier

   • Identifier + Password

   • Passkey

Add a condition

Add a condition between steps to create branches based on the context. You can add the Realm can be federated condition, which 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. After either the 1st STEP or 2nd STEP columns, select the plus sign.

   

2. On the Add condition side sheet, select Realm can be federated.

   

3. On the Realm can be federated side sheet, enter the Name and Description.

4. Select the plus sign for the TRUE branch and then select IDP from Identity Broker based on home realm detection.

5. Select the plus sign for the FALSE branch, and then select a different authentication method.

Add a second or third step

1. To add a second step, in the 2nd STEP column, select the plus sign.

   

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

2. In this side sheet, select the second step in the authentication journey:

   • Home realm detection

   • Passkey

   • Password

   • SMS OTP

3. To add a third step, in the 3rd STEP column, select the plus sign.

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

4. In this side sheet, select the third step in the authentication journey. The third step has the same authentication options as the second step.

5. 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.

6. To make the journey live in production where users can access it, select Publish.

   Any subsequent updates must be published.

Remove 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.
• Remove the identification step from the incomplete path.

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

2. You can delete a step from the side sheet or the step menu:

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

     

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

     

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.

Trigger an authentication journey

There are several ways to trigger an authentication journey:

• Default journey: The system uses the default authentication journey, unless the journey ID is provided in the ACR value.

• Relying party: The relying party can provide the journey ID as an ACR value, using the following format:

  urn:onewelcome:ujo:v1:auth:journey:id:{Journey ID}

• Default ACR or Authentication Context Class References value: Set the default ACR value for OIDC web clients or set the Authentication Context Class References value for SAML applications. The default ACR or Authentication Context Class References value specifies the journey ID in the following format:

  urn:onewelcome:ujo:v1:auth:journey:id:{Journey ID}

Set the default authentication journey

There can only be one default journey. When you set a journey as default, the previous journey reverts to being a regular, non-default, journey.

You can set a journey as default on the Authentication Journey screen or on the journey editor:

• On the Authentication Journey screen, select the menu for the authentication journey and then select Make default.

• In the top-right corner of the journey editor, select the menu and then select Make default.

Set the authentication journey for an OIDC web client

To ensure that an OIDC web client uses a specific authentication journey, you can set the default ACR value for the web client. For the ACR value, provide the ID for the journey that you want to use in the following format:

urn:onewelcome:ujo:v1:auth:journey:id:{Journey ID}

The web client uses the specified journey, unless the authentication request specifies a different journey ID in its ACR value.

1. On the OneWelcome Identity Platform console, on the Authentication Journey page, copy the journey ID that you want to associate with a specific web client.

   You can also find the Journey ID on the Journey information side sheet, on the right side of the journey editor.

   Note

   To easily get to the Access admin console, in the top-right of the OneWelcome Identity Platform console, select Applications > Access admin. The Access admin console opens in a new tab.

   

2. On the Access admin console, go to Configuration > Web clients.

   The Web clients page lists the clients that are configured for your tenant.

3. Locate the web client that you want to associate with the authentication journey ID that you copied.

4. In the Actions column for that web client, select Edit.

   The Edit Web client page opens and shows the configuration for the selected client.

5. Scroll down to the ACRs section.

6. In the Default ACRs field, select or enter the ACR value with the journey ID in the following format:

   urn:onewelcome:ujo:v1:auth:journey:id:{Journey ID}

   

   You can also include an ACR value with the tenant ID. The order in which you specify them affects the outcome:

   • ACR level + journey ID: The journey is selected and the achieved ACR level is reported back.

   • Journey ID + ACR level: The journey is selected and the executed journey is reported back.

   • ACR level (only): The default journey is selected and the achieved ACR level is reported back.

   • Journey ID (only): The journey is selected and the executed journey is reported back.

7. Select Save.

Set the authentication journey for a SAML application

To ensure that a SAML application uses a specific authentication journey, set the default Authentication Context Class References value for the application. For the Authentication Context Class References value, provide the ID for the journey that you want to use in the following format:

urn:onewelcome:ujo:v1:auth:journey:id:{Journey ID}

The application uses the specified journey, unless the authentication request specifies a different journey ID in its Authentication Context Class References value.

1. On the OneWelcome Identity Platform console, select: Core > Applications.

   

2. On the Applications page, locate the application that you want to update with an ACR value.

3. In the application menu, select Edit.

   You can also specify the Authentication Context Class References when you add a SAML application.

4. On the Edit SAML application page, go to the end of the SAML SP configuration section.

5. In the Default Authentication Context Class References field, select or enter the value with the journey ID in the following format:

   urn:onewelcome:ujo:v1:auth:journey:id:{Journey ID}

   

6. Select Submit.