Skip to main content

Account recovery and password reset

Account recovery allows registered users to regain access to their account if they forget their password or lose access to the second authentication factor required for multi-factor authentication (MFA).

To regain access to their account, the user must prove that they're the owner of the account. The verification of ownership is performed using the recovery address defined by the user. When the account recovery flow is started, the system sends a link or a one-time code to the recovery address defined by the user. The user must access the link or enter the code they received to confirm their identity and ownership of the account.

When the user accesses the configured recovery method, they receive a privileged session and are taken to their account's settings page where they must create a new password to regain access to their account.

info

The account recovery flow doesn't reset user's second authentication factor.

Supported recovery methods​

Ory Identities (Ory Kratos) supports two recovery methods:

  • Recovery by one-time codes (code)
  • Recovery by magic links (link)

Comparison​

"One-time code" (code) is the default, preferred, and recommended method by Ory.

Ory supports "magic links", but considers this method a legacy solution. Currently, the method is supported but should be considered deprecated and is set to be removed in future releases.

Consider using the code method as it mitigates many of the drawbacks of "magic links":

  • Some email virus scanners open links in emails to scan them. This invalidates the link and may prevent users from completing the flow even if they have the access to the defined address.
  • Flows initialized by apps on mobile phones or smart devices don't work with links.
  • Depending on the device settings, clicking a link from an email can open a different browser than the one used to initialize the flow. This can confuse your users.
caution

When you change the strategy from link to code in an existing project, you might need to adjust your UI. Make sure the flow works correctly with your UI implementation after changing the strategy.

Configuration​

To enable account recovery and adjust related options, go to Authentication → Account Recovery in the Ory Console.

Require multi-factor for account recovery​

By default, the account recovery process gives users a privileged session without the need to provide the second authentication factor. You can choose to require multi-factor authentication for account recovery.

note

This affect all users, not just those that recover their accounts. If you enable this setting, all users must provide their second authentication to adjust profile settings.

In the Ory Console go to Two-Factor Authentication and disable Allow Self-Service Settings without Second Factor.

Account recovery address​

To start account recovery, Ory Identities must know which address to send the recovery message to. Usually this is the email address the user provides when registering their account. Other fields inside the traits section are supported as well.

info

If the email address used for recovery is the same as the email used for verification and the account isn't activated when the recovery flow is started, completing the recovery flow also verifies the user's email address.

Read this document to learn about the account verification flow.

To specify a trait of the identity to be used for recovery, use the following identity schema:

 {
   "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Person",
   "type": "object",
   "properties": {
     "traits": {
       "type": "object",
       "properties": {
         "email": {
           "type": "string",
           "format": "email",
           "ory.sh/kratos": {
             "credentials": {
               "password": {
                 "identifier": true
               }
             },
+            "recovery": {
+              "via": "email"
+            }
           }
         }
       }
       "additionalProperties": false
     }
   }
 }

Attempted recovery notifications​

When this option is on and users attempt to initiate recovery for unregistered addresses, the system sends an attempted recovery notification to the email address that was used in the attempt. This prevents account enumeration attacks as explained in this blog post by Troy Hunt.

info

By default, this feature is disabled in newly created Ory Network projects.

Follow these steps to enable sending attempted recovery notifications:

Go to Ory Console → Account Recovery to enable and toggle Notify unknown recipients on.

Email templates​

Ory Identities comes with default email templates for recovery flows.

You can replace the defaults and customize the messages to match the look and feel of your solution. Read the email templates documentation to learn more.

Invalidate other sessions​

In some scenarios it can be useful to revoke all active sessions of the user when they recover their account. This forces anyone with access to the account to re-authenticate using the new password set up in the recovery process.

To trigger this behavior, use the after_recovery hook:

  1. Get the Ory Identities config with Ory CLI:

    ## List all available projects
    ory list projects

    ## Get config
    ory get identity-config {project-id} --format yaml > identity-config.yaml

  2. Add the hook configuration to the downloaded file.

    selfservice:
      flows:
        recovery:
          enabled: true
          ui_url: http://your.ui/recovery
    +      after:
    +        hooks:
    +        - hook: revoke_active_sessions

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

    ory update identity-config {project-id} --file identity-config.yaml
tip

Learn how to add and configure hooks for self-service user flows.

Fallback recovery address​

In some scenarios, users may want to recover their account using a different email address than the one they used to register, for example if they no longer have access to the original email address. To use two (or more) recovery email addresses, you need to define a secondary email field, such as email_secondary in the traits section of the identity schema. This field will serve as the fallback email address for account recovery. Read more about identity schemas here.

This is an example of an identity schema with a secondary email address:

{
  "$id": "https://example.com/ory.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "traits": {
      "additionalProperties": false,
      "properties": {
        "email": {
          "format": "email",
          "ory.sh/kratos": {
            "credentials": {
              "password": {
                "identifier": true
              },
              "webauthn": {
                "identifier": true
              },
              "totp": {
                "account_name": true
              }
            },
            "recovery": {
              "via": "email"
            },
            "verification": {
              "via": "email"
            }
          },
          "title": "Email address",
          "type": "string",
          "maxLength": 320
        },
        "email_secondary": {
          "format": "email",
          "ory.sh/kratos": {
            "recovery": {
              "via": "email"
            },
            "verification": {
              "via": "email"
            }
          },
          "title": "Email address secondary",
          "type": "string",
          "maxLength": 320
        }
      },
      "type": "object"
    }
  },
  "title": "Person",
  "type": "object"
}

In this schema, you define both email and email_secondary fields as recovery addresses. This means that Ory will send recovery messages to both addresses when the recovery flow is initiated. The user should provide the email_secondary field during registration or update it later in their account settings so it can be used in the recovery process.

Code examples​

The user interface for the account recovery is a page in your solution that should render the actual form elements for the user.

In contrast to other identity systems, Ory Identities doesn't render this HTML directly. Instead, you implement the HTML code in your solution, which gives you complete flexibility and customizability in your user interface flows and designs. This part of your application then directly interfaces with Ory Identities through the API.

The API responds with a JSON document describing the form elements to render and actions the form should take upon submission, cancellation, etc. The following shows examples for different languages and frameworks.

Account Recovery HTML Form