Register TOTP

Registers a TOTP authenticator for the user

About client-facing steps

A journey is a sequence of steps that are executed when it's invoked by a client application (known as the "client"). Some steps require involvement from the client, such as to collect user input. Other steps, like validating a token, are executed in the backend by the Mosaic journey engine alone.

When invoked, the journey begins executing the steps while the client waits for further instructions. When a journey reaches a client-facing step, the journey asks the client for the required input and then waits for the client to respond. The client presents their own UI if user interaction is required, and returns input to the journey. The journey then proceeds in a similar manner until it's completed.

Description

This client-facing step is used to register an authenticator for TOTP authentication. TOTP is often used as a second-factor for MFA, or to step-up authentication for high-risk operations.

Time-based one-time passcodes (TOTP) codes are unique numeric codes generated based on the current time and a shared secret. Codes are generated by a mobile authenticator app (like Google Authenticator, Microsoft Authenticator, or Twilio Authy), and then validated by the authenticator using the TOTP Authentication step.

A TOTP authenticator is registered to a specific user and application. The user context for the step may be provided implicitly by the journey if the user is already authenticated; otherwise, a user identifier must be specified in the step configuration. A TOTP authenticator should only be registered to a user that has verified their identity—for example, using email OTP, document verification, or externally using a legacy identity provider.

When triggered, this step generates a static secret that will be used for generating codes, and returns it to the client (along with a URI that contains the secret and other TOTP configuration). The client is responsible for ensuring the secret gets registered in the user's authenticator app. For example, the client can embed the returned URI in a QR code and instruct the user to scan it using an authenticator app installed on their mobile device.

Once registered, the client submits an empty response to the journey to indicate that the step was completed and the journey proceeds to the next step. If this step fails, the journey proceeds to a failure branch (if specified); otherwise, the journey is aborted and an error is sent to the client.

Security features for TOTP authentication can be customized in the TOTP method settings for the application. By default, the passcode includes 6 digits and changes every 30 seconds.

Configuration

Example

Suppose a journey registers a TOTP authenticator for a user after they login using password:

When executed, this step returns to the client the idoServiceResponse object. It will have the journeyStepId set to TotpRegistration and the data will include the following:

{
 "data": {
   "payload": {
     "secret": "<secret>", // Secret used to generating codes
     "uri": "<uri>"  // URI containing secret and other TOTP configuration
    },
  }
}

The client shares the secret with the user, who registers it in their mobile authenticator app. For example, the client can embed the URI in a QR code for the user to scan with their mobile app. Once completed, the client send the following empty response to the journey to complete the step:

    window.tsPlatform.ido.submitClientResponse(
        ClientResponseOptionType.ClientInput
    )

TSIdo.submitClientResponse(
  TSIdoClientResponseOptionType.ClientInput.type, 
  null, 
  callback
  )

TSAuthentication.shared.registerTOTP(URI: [URI], securityType: [SECURITY_TYPE]) { result in
    switch result {
    case .success(let response):
        debugPrint("[DEBUG]: UUID: \(response.uuid)")
        
        debugPrint("[DEBUG]: issuer: \(response.issuer)")
        
        debugPrint("[DEBUG]: label: \(response.label)")
    case .failure(let error):
        switch error {
        case .totpError(let error):
            debugPrint("[DEBUG]: \(error.message)")
            // Handle TOTP error
        default:
            debugPrint("[DEBUG]: \(error.message)")
            // Handle other SDK errors
        }
    }    
}