Version: v0.4

Recovery Link and Password Reset

Before you start

Please read the Account Recover Documentation first.

The link strategy performs account recovery (also known as password reset) by sending an email containing a recovery link to the user.

There are two email types sent by this strategy:

Recovery email sent to unknown address
If the requested email address is a known recovery address, a recovery link is sent to that email address.

Recovery email sent to unknown address
If the requested email address is a known recovery address, a recovery link is sent to that email address.

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

You should also configure how long a session is privileged. The user will only be able to update his/her password (or any other credential) for the specified amount of time after clicking on the recovery link:

path/to/kratos/config.yml
selfservice:
flows:
settings:
privileged_session_max_age: 15m

This strategy does not implement any other flow.

Browser Clients

To initiate the request, point the browser to Self-Service Recovery Endpoint:

<a
href="https://<kratos-public>/self-service/browser/flows/recovery"/>
Recover your account!
</a>

Next, the user is redirected to the Recovery UI set by config variable selfservice.flows.recovery.ui_url with a ?request=... query parameter:

The browser is redirected to, for example: http://127.0.0.1:4455/recovery?request=e219b0ee-58a8-4dc4-aeb6-294e9787dfa9

Choosing a Recovery method

The state parameter follows the state machine

where

  • choose_method indicates that the user has not chosen a recovery method yet. This is useful when link is not the only recovery method active.
  • sent_email implies that the recovery email has been sent out.
  • passwed_challenge is set when the user has clicked the recovery link and completed the account recovery.

If the form validation fails, an error will be included and state will also be set:

Sent form data is invalid

If the form data is valid, the state is set to sent_email and messages will also be set:

Sent form data is invalid

Once the user clicks the link in the E-Mail, she/he will be redirected to the Settings endpoint (e.g. http://127.0.0.1:4455/settings?request=752b6d46-af3d-40d2-9d06-b3e3c0279f02) directing the user to update the password / other credentials:

Recovery email sent to unknown address

If the user clicks an invalid (already used, expired) recovery link, a new recovery request will be initiated and she/he will be asked to retry the flow:

Recovery email sent to unknown address

API Clients

API-based login and registration using this strategy will be addressed in a future release of ORY Kratos.

Security

Account Enumeration Defenses

This flow follows best practices by prevent account enumeration attacks using the recovery flow.

Last updated on by aeneasr