2FA TOTP (Google Authenticator)

Time-Based One-Time Password (TOTP) is a standardized algorithm (see RFC6238) that is used by apps supported by apps like Google Authenticator (iOS, Android), 1Password, Bitwarden, and many others.

Configuration

Enabling this method is as easy as setting

kratos.config.yml

selfservice:
  methods:
    totp:
      enabled: true
      config:
        # The issuer (e.g. a domain name) will be shown in the TOTP app (e.g. Google Authenticator). It helps the user differentiate between different codes.
        issuer: Example.com

Identity Schema

To help the user identify the correct code in their TOTP authenticator app, you should set the issuer (see code example above) to your brand name or domain name. However, users might have multiple identities registered in your system. To help them distinguish between them, you can specify a traits in your Identity Schema which should be the TOTP account name (in the screenshot above alice@example.org):

identity.schema.json

{
  $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
+             }
            }
            // ...
          }
        }
        // ...
      }
      // ...
    }
  }
}

Identity Credentials

The totp method would generate a credentials block as follows:

credentials:
  password:
    id: totp
    identifiers:
      # This is the identity's ID
      - 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