Authenticates the user based on a token generated by an external identity provider (e.g., legacy system)
This step can be used to authenticate users based on an external token. For example, it is useful when migrating users from a legacy system to Mosaic or authenticating users using a custom method via an external identity provider.
To validate external tokens, configure a custom validation service, then select the configured connection in Token Validator. The service evaluates the relevant token claims and validates the token against the user identifier provided by the step. When Validate user IDs mismatch is enabled, the step also verifies that this identifier matches the one in the session context.
This step allows you to define a Custom AMR value to be added to the Mosaic access token's amr claim generated at the end of the authentication process. Tracking a custom value for the amr provides the following benefits:
- Traceability: Maintains a historical record of the authentication method used in the source system, which can be useful for compliance or audit purposes.
- Policy decisions: Enables enforcement of additional actions in future journeys based on the
amrvalue. For example, if the original authentication was weak (e.g., simple password), Mosaic can enforce stronger methods (e.g., passkey or MFA) before granting access. - Risk assessment: In certain contexts, the
amrvalue can be used to determine the risk level associated with a session or transaction. - Reporting: Includes the
amrvalue in reports to provide visibility into the origins and authentication methods of migrated users.
If this field is left empty, the default value flex.login is used.
You can configure custom branches on the token validation service to route the journey according to the validation response. For information about configuring custom branches, see External service integration.
| Field | Description |
|---|---|
| Identifiers | An identifier used to locate the user. Can be an external user ID, email, phone number, username, or a custom identifier, if configured for B2C users in your tenant. This must match the user of the external token. |
| Token to Validate | External token to validate in this step, specified as an expression. |
| Custom AMR | Custom AMR value to be added to the amr claim in the Mosaic access token (JWT). Accepts an interpolated string expression to specify the custom AMR value. This value is used to indicate the authentication method reference in the token payload. If left empty, defaults to flex.login. |
| Token Validator | The custom validation service used to validate the token. |
| Validate user IDs mismatch | When enabled, verifies that the user identifier provided by this step matches the identifier in the session context. Disable only for legacy flows that intentionally pass a different identifier. |
| Branch Name (only when Token Validator is configured) | Name of the custom branch(es) configured on the Token Validator. This label is also used when the branch type is Success or Warning. |
| Behavior (only when Token Validator is configured) | Determines whether the journey uses the custom branch:
|
| Error Output Variable | Name of the variable that stores any errors returned by the token validation service |
| Failure Behavior | Determines the behavior in case of failure, which either aborts the journey (default) or proceeds to a failure branch of the control flow. |
This step can be configured to record step input and output data, or a custom payload, which is then surfaced in journey events in Journey Analytics for diagnostic purposes. For details, see Additional data reporting.
Here's an example of how this step can be used.
Consider a journey that's used to migrate users from a legacy system to Mosaic. For example, after the user logs in using the legacy provider, a journey is initiated to authenticate the user in Mosaic based on the external login and then register passkey biometrics for future authentications (using the Register Passkeys step).
The username and external token can be provided by the client that invokes the journey as part of the request. In our example, the client passes them in the SDK call as additional parameters named username, externalToken and a custom amr:
// Start a journey with the ID 'my-journey-id'
// If SDK was loaded via script tag, invoke functions inside 'window.tsPlatform'
try {
const idoResponse = await ido.startJourney(
'my-journey-id',
{
additionalParams:
{
username: 'username', // User identifier
externalToken: 'external-token', // External token to validate auth
amr: 'your-custom-amr-value' // Optional custom AMR value
}
}
);
// Handle Journey response
} catch(error) {
switch(sdkError.errorCode) ...
}The journey step can access the username using @policy.request().params.username and the external token using @policy.request().params.externalToken, and import through the token a custom amr using @policy.request().params.amr:
