Users

In Mosaic Orchestration, journeys offer a flexible, secure approach to managing identity workflows. These journeys revolve around the user identity—identifying and authenticating the user impacts the overall journey logic and sequence of steps executed by the app.

Central to user identity is the requirement for authentication, especially when steps involve accessing or modifying user data. By understanding the user's authentication state at each step, you ensure workflows remain secure while minimizing unnecessary re-authentication prompts.

User identity

In Mosaic, user identities are centralized across all applications within a tenant. A new user identity is created as a result of user onboarding. A user recod comprises of various personal data, such as the user's address or language, and identifiers, such as email or phone number, that are required for user authentication. See User management for more details.

Identity journeys leverage the following identifiers to map the current journey session to the authenticated user:

  • user_id – a unique identifier, which is automatically generated by Mosaic when the user is created
  • external_user_id – a unique identifier in Mosaic that represents a user identifier within your app or external IDP

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 identity is confirmed, in other words if the user has been authenticated within the current journey. This 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.

Actions after external authentication or session continuation

In certain situations, Mosaic can proceed with actions that typically require authentication without asking the user to re-authenticate. This is particularly useful in cases such as:

  • External authentication : If the user is authenticated by an external system (e.g., an IDP), you can retrieve the external user ID in one of the following ways:
    • Using the Get Information from Client step to collect it directly from the user.
    • Passing it as an input parameter from the calling application, accessible via @policy.request().params .
    • Accessing it through @policy.sdkSavedData() if it was previously stored using the Save Data on SDK step.
  • Session continuation : If the user has authenticated in a separate journey. To maintain the user’s session across separate journeys, use the Restore User Context step. This step reinstates the full user context, making @policy.userContext() available with the saved user data.

Based on the user’s current authentication state, configure the User Auth State setting as follows:

  • User is not authenticated : Select this option if only partial information, such as an external user ID, is available.
  • User is already authenticated : Choose this option if the full user context has been restored using Restore User Context .

Accessing authenticated user information

When the user is authenticated within the journey, you can access user information like identifiers or tokens through the @policy.userContext() expression. For instance, the user ID can be retrieved with an expression like:

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

This allows the journey to operate on the authenticated user’s record.