Authentication state

In Mosaic Orchestration, journeys offer a flexible, secure approach to managing identity workflows. Central to these workflows is the requirement for authentication, especially when steps involve accessing or modifying user data. Ensuring these actions align with the user’s authentication status is essential to maintaining a secure, adaptable workflow.

By understanding the authentication state at each step, you ensure workflows remain secure while minimizing unnecessary re-authentication prompts.

Key actions requiring authentication

User authentication is typically required for steps involved in the following operations:

  • Reading or writing user data – for instance, updating custom user information, as in Write custom user data .
  • Registering authenticators – for example, adding security credentials, such as passkeys, with steps like Registering Passkeys .
  • Managing devices – such as checking for known devices or associating a device with a user profile, for example, Phone Registration or verifying Is Known Device .

The behavior of these authentication-dependent steps varies not only based on their individual functions but also on the overall structure of the journey — including the sequence of steps, their configurations, and the logical flow they create. The User Authentication State control in Mosaic Orchestration allows you to manage authentication requirements dynamically, adapting to the logic of the flow.

Understanding authentication states

The Authentication State indicates whether a user has been authenticated within the current journey, which determines whether the journey can proceed to steps that access or modify user records. By default, the journey starts in an unauthenticated state and only transitions to an authenticated state after a successful authentication. Once authenticated, the journey can securely allow subsequent steps to access or modify the user’s data as needed.

To ensure security, the User Auth State control appears in steps that involve accessing or modifying user data. This control allows you to define the expected authentication state for each step, so that the journey can adapt dynamically to the user’s current status. The User Auth State control provides two options:

  • The user is already authenticated : This is the default setting, indicating that the journey can rely on an existing authenticated session because the user’s authentication was executed in a prior step of the journey. This indicates that access to user data without requiring re-authentication is secure.
  • The user is not authenticated : this option should be selected in steps that require a user identifier but cannot rely on an active authentication session established earlier in the journey. As prior user authentication is absent, selecting this option prompts a field to specify an external user ID . Here, the journey designer enters an expression that retrieves a trusted identifier (e.g., @policy.sdkSavedData().external_user_id ) stored in the SDK. This configuration enables the journey to proceed based on the external user ID, allowing actions to be performed without direct authentication within the journey.

Journey context for authentication scenarios

To understand how the state of user authentication impacts the system's requirements for authentication, let's explore the three main scenarios:

After creating a user

In some journeys, a new user is created before any authentication occurs, typically using the Create user step. This user creation step generates a new user record and is often followed by steps that register additional data and authenticators to that record. Since these subsequent steps require the user to be authenticated, you can set the User Auth State to Set as authenticated to allow them to proceed based on the initial user creation. This approach is ideal for workflows where user creation and verification occur within the same session.

After user authentication

In many workflows, user authentication occurs within a dedicated step where the user provides credentials, which the system then validates. Once authenticated, the journey treats the session as fully authenticated, allowing any subsequent steps to access or modify user data without further authentication. These steps are typically configured with the User Auth State set to its default, The user is already authenticated, allowing them to rely on the initial authentication completed earlier in the flow.

Action required after external authentication

In certain cases, actions such as verifying a known device or accessing a specific user record need to occur without direct user authentication, as the user has been authenticated by other means—such as through an external identity provider (IDP) or a legacy authentication flow. To ensure the journey can still proceed with steps that require authentication, the system may require an external user ID. The external user ID can be obtained in various ways:

  • Collecting it from the user through a Get Information from Client step.
  • Passing it as an input parameter from the calling application, accessible via the @policy.request().params expression.
  • Retrieving it via @policy.sdkSavedData() , if it was previously stored within the journey, such as through a Save data on SDK step.

In this scenario, the User Auth State setting should be adjusted to User is not authenticated, and the external user ID should be provided as described above.

Accessing authenticated user information

When the user is authenticated within the journey, you can access user information like identifiers or tokens using the authscript expression the @policy.userContext() expression. For instance, the user ID can be retrieved by using an expression like the one that follows:

Copy
Copied
{
  "user_id": "@policy.userContext().user_id"
}

This allows the journey to continue operating on the authenticated user's record.