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 multifactor authentication (MFA).

To regain access to their account, the user must prove that they are 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 initiated, 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.

Enforce multifactor authentication​

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 multifactor authentication for account recovery.

note

This affect all users, not only 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 (Ory Kratos) must know which address to send the recovery message to. In most cases 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 is not activated when the recovery flow is initiated, completing the recovery flow also verifies the user's email address.

Read this document to learn about the account activation 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
     }
   }
 }

Email templates​

Ory Identities (Ory Kratos) comes with default email templates for recovery flows.

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

note

When users attempt to initiate recovery for unregistered addresses, the system sends a message to the email address that was used in the attempt.

This prevents account enumeration attacks as explained in this blog post by Troy Hunt.

Invalidate other sessions​

In some scenarios it can be useful to revoke all active sessions of the user when they successfully 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 updated_config.yaml
tip

For more information see the hooks configuration documentation.

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 (Ory Kratos) doesn't render this HTML directly. Instead, you need to 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 a few different languages and frameworks.

Account Recovery HTML Form