Time-based one-time passwords (TOTP)

Time-based one-time passwords are codes made up of digits, that are valid for a short amount of time, usually 30 seconds or less. Users generate these passwords with companion apps such as Google Authenticator or FreeOTP and enter them when asked to provide their second authentication factor.

When accessing resources protected with the second-factor requirement, the paired application generates a one-time password that expires after a certain time. Users must input this password before it expires to authenticate and perform the protected actions.

You can enable Time-Based One-Time Password (TOTP) authentication in Ory Identities (Kratos) to allow users to perform 2FA with TOTP apps such as Google Authenticator, LastPass, or FreeOTP.

When enabled, users can pair a TOTP app to their account:

note

The example screenshot is captured using the Ory Account Experience.

https://playground.projects.oryapis.com/ui

When attempting to perform actions while having 2FA enabled, users are asked to enter the short code in the Ory Identities UI. This proves that they have access to their chosen second factor.

https://playground.projects.oryapis.com/ui

info

In this example, the user identifier (email - alice@example.com) is used. To learn how to enable this behavior, read Distinguishing identities requesting TOTP.

Configuration

Ory Console

1. Sign in to the Ory Console and go to Two-Factor Authentication.
2. In the TOTP Authenticator App section, use the switch to enable TOTP.
3. Define the name of the requesting party in the Display Name. The users see this name in the TOTP application when getting a one-time password.
4. Click Save to finish.

https://console.ory.sh/

Ory CLI

1. Get the Ory Identities configuration from your project and save it to a file:

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config <project-id> --format yaml > identity-config.yaml

2. Find totp in selfservice/methods, set enabled to true, and define the issuer:

   identity-config.yaml

   selfservice:
     methods:
       totp:
         config:
           # The "issuer" is the name in the TOTP application users see when getting a one-time password.
           issuer: ExampleIssuer.com
         enabled: true

3. Update the Ory Identities configuration using the file you worked with:

   ory update identity-config <project-id> --file identity-config.yaml

Distinguishing identities requesting TOTP

To help users distinguish which identity the registered TOTP code belongs to, add a totp section to the identity schema section of the trait you want to show up in the TOTP app.

In this example, the user's email address is the identifier:

note

This configuration is the default behavior on the Ory Network.

sample identity schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "traits": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "title": "Your E-Mail",
          "minLength": 3,
          "ory.sh/kratos": {
            "credentials": {
              // ...
              "totp": {
                "account_name": true
              }
            }
            // ...
          }
        }
        // ...
      }
      // ...
    }
  }
}

Writing E2E tests

When writing end-to-end (E2E) tests for TOTP implementation in your app, you can reference the Cypress tests used in Ory Identities (Ory Kratos).

Identity credentials

When the user enables TOTP, Ory adds the following entries to the credentials object of the associated Identity:

credentials:
  password:
    id: totp
    identifiers:
      - 802471b9-06f5-49d4-a88d-5e7d6bcfed22
    config:
      # This is the TOTP URL which contains the pre-shared key and some additional meta-information.
      totp_url: otpauth://totp/Example:alice@example.org?secret=JBSWY3DPEHPK3PXP&issuer=Example