Skip to main content

Lookup Secrets - a MFA fail-safe

Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA fail-safe mechanism, rather than a standalone two-factor authentication method. 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 download a server-generated set of one-time codes. The user should 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.

If you enable Lookup Secrets, users can get a list of codes that they must store securely for future use. This is how it looks in the UI:

note

The screenshots are captured using the Ory Account Experience.

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

Recovery Codes generation in Ory Account Experience

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

Recovery Codes in Ory Account Experience

After the server generates the codes, the user must confirm that they received them. To confirm, the user must have a privileged Session. If the privileged session expired, the user is prompted to authenticate.

danger

The codes are valid only when the user confirms they received the codes. It is the user's responsibility to generate new secretes before they use all the available secrets.

Configuration

  1. Sign in to the Ory Console and go to Two-Factor Authentication.
  2. In the Lookup Secrets section, use the switch to enable WebAuthn.
  3. Click Save to finish.
https://console.ory.sh

Lookup Secrets settings in Ory Console

Identity credentials

When the user generates and/or uses Lookup Secrets, Ory adds the following entries to the credentials object of the associated identity:

credentials:
password:
id: lookup_secret
identifiers:
# This is the identity's ID
- 802471b9-06f5-49d4-a88d-5e7d6bcfed22
config:
recovery_codes:
- code: 3zg9abc
- code: 1bc6bea
used_at: 2021-10-14T07:38:51Z