Custom Authentication

Authenticates the user based on a token generated by an external identity provider (e.g., legacy system)

Description

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.

This step validates external tokens using a token validation service configured as an external connection. The service evaluates the relevant claims associated with the token, including verifying that the token corresponds to the username provided by the step. Once validation is complete, the service returns a result, such as valid or invalid.

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 amr value. 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 amr value can be used to determine the risk level associated with a session or transaction.
  • Reporting : Includes the amr value 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.

If token validation succeeds, the journey execution resumes with the next step. If token validation fails (e.g., if the token is invalid or the token validation service fails), the journey terminates.

Configuration

Field Description
Username User identifier, specified as an expression. This must match the user of the external token
Token to Validate External token to validate in this step, specified as an expression.
Token Validator External connection that represents the token validation service.
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.
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.

Examples

Here's an example of how this step can be used.

Example 1: Migrating users

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:

Copy
Copied
// Start a journey with the ID 'my-journey-id'
try {
  const idoResponse = await window.tsPlatform.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: