TOTP Authentication
Authenticates the user using a time-based one-time code (TOTP)
Description
This step is used to authenticate the user with a TOTP code they generated using their mobile device. For example, this can be used as a second-factor for MFA, or to step-up authentication for high-risk operations.
To perform TOTP authentication, a user must have a TOTP authenticator registered for the application (via the Register TOTP step). This also involves registering the TOTP secret in a mobile authenticator app (like Google Authenticator), or in another mobile app that implements a TOTP generator.
Before initiating authentication, the journey must obtain the user identifier and generated TOTP code. For example, a form can be used to collect them from the user. When executed, the step validates the generated code using the authenticator registered for the user. If successful, the journey sets the user context to the authenticated user and continues to the next step. Tokens generated for the authentication can be accessed in subsequent steps using @policy.userTokens().
If it fails (e.g., expired or incorrect code), the journey proceeds to the failure branch (if specified); otherwise, the journey is aborted and an error is sent to the client. When building a TOTP solution, you'll need to consider how to handle the different error cases.
Configuration
| Field | Description |
|---|---|
| Username | User identifier of the authenticating user, specified as an expression. |
| TOTP Code | TOTP code to validate, specified as an expression. |
| Error Output Variable | Name of the variable that stores any errors returned by action |
| Failure Behavior | Determines the behavior in case of failure, which either aborts the journey or proceeds to a failure branch of the control flow (default). |
Example
Suppose a login form is used to collect the user's username and a TOTP code that they'll generate using their mobile authenticator app. In our example, the form ID is loginForm, the input will be stored in a variable named loginData, and only TOTP is enabled. The TOTP branch has the default branch ID (totp) and schema (username and totp_code).
The authentication step obtains the username and TOTP code from the form output (loginData.username and loginData.totp_code). Once the code is validated, the step is complete.
