Overview

Multi-factor authentication (MFA) provides an additional layer of security that helps ensure that the accounts of your users can't be easily compromised by malicious actors.

Nowadays, many of the passwords in use can be easily compromised because:

• They are re-used across multiple websites and applications.
• They were leaked to the web and sold to malicious actors.
• They are considered "weak" by being short, having obvious connections to their owners, containing easy-to-guess character strings, etc.

info

Ory Identities (Kratos) allows you to enable two-factor authentication (2FA).

By enabling two-factor authentication in your project, you introduce an additional verification step that can guard user login or user self-service - operations such as updating account password or the account's main email address.

Available methods

Ory offers these second-factor authentication methods for all projects and self-hosted instances:

Time-Based One-Time Password (TOTP)

This method requires users to pair a companion app such as Google Authenticator or the OnePassword password manager on their mobile device. The app is responsible for generating one-time, time-based passwords.

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.

WebAuthn

This method uses the Web Authentication Browser API, also known as WebAuthn, which allows servers to register and authenticate users using public-key cryptography.

This method is used with:

• USB, NFC, or Bluetooth Low Energy devices, for example YubiKey
• OS-level biometric authentication protocols, such as TouchID, FaceID, Windows Hello, or Android Biometric Authentication

When accessing resources protected with the second-factor requirement, the browser presents the user with a prompt asking to engage the configured authentication method, for example, to touch the fingerprint reader.

note

WebAuthn is a browser-only standard. It does not work in native mobile apps. To learn more about this standard and its constraints, read this document.

Lookup Secrets

Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA failsafe rather than a standalone two-factor authentication mechanism. They can be used to complete the second factor when users lose access to their selected 2FA method.

If you enable Lookup Secrets, users can get a server-generated set of one-time codes. The user must store these codes in a secure place and use them when they cannot use their selected 2FA method.

Each code is valid for single use only. The codes don't expire after a set amount of time. When the user generates a new set of codes, previously generated codes become invalid.

tip

To ensure maximum security, these codes should be periodically re-generated by the user.

Terminology

Learn more about the terms and concepts used when talking about 2FA in Ory and looking into the Ory Identities configuration.

Authentication Method Reference (AMR)

The Authentication Method Reference (AMR) is an array of authentication methods used over the lifetime of an Ory Session.

The following methods can be saved in a Session:

• password - When the user authenticated with their password.
• oidc- When the user authenticated by signing in with a social sign-in provider
• totp- When the user authenticated by entering a one-time password
• webauthn - When the user authenticated through an OS-level biometric authentication method
• lookup_secret - When the user entered a valid one-time recovery code

This is how the information is saved in the Ory Session:

Sample Ory Session JSON Payload

{
  id: "6b51a3f2-6a2c-4557-90a8-4e23de7072aa",
  active: true,
  // ...
  authenticator_assurance_level: "aal2",
  authentication_methods: [
    {
      method: "password",
      completed_at: "2021-10-14T09:37:53.872104Z",
    },
    {
      method: "lookup_secret",
      completed_at: "2021-10-14T09:41:16.771859Z",
    },
  ],
  // ...
}

Every method can be saved in a Session multiple times, for example when the Identity refreshes their Ory Session by re-authenticating:

Sample Ory Session JSON Payload

{
  id: "6b51a3f2-6a2c-4557-90a8-4e23de7072aa",
  active: true,
  // ...
  authenticator_assurance_level: "aal2",
  authentication_methods: [
    {
      method: "password",
      completed_at: "2021-10-14T09:37:53.872104Z",
    },
    {
      method: "lookup_secret",
      completed_at: "2021-10-14T09:41:16.771859Z",
    },
    {
      method: "password",
      completed_at: "2021-10-14T12:00:00.134567Z",
    },
  ],
  // ...
}

Authenticator Assurance Level (AAL)

The Authenticator Assurance Level (AAL) is a parameter that shows how many authentication factors the given Identity has completed.

Authentication methods are classified into factors:

Authentication method	Factor
password	first
oidc	first
totp	second
webauthn	second
lookup_secret	second

info

If you enable webauthn for passwordless authentication, passwordless flows are used instead of MFA. In such setups, webauthn is considered a first authentication factor.

The parameter can take one of two values:

• aal1: The Identity completed only the first authentication factor(s).
• aal2: The Identity completed the first and the second authentication factor(s).

danger

Completing two first authentication factors doesn't give the Identity aal2. For example, password + oidc = aal1.