diff --git a/docs/identities/get-started/account-recovery.mdx b/docs/identities/get-started/account-recovery.mdx index 7b6e6ece8..a11fbee26 100644 --- a/docs/identities/get-started/account-recovery.mdx +++ b/docs/identities/get-started/account-recovery.mdx @@ -28,7 +28,7 @@ configure account recovery in your Ory project. ``` -**Enable and configure account recovery** +### Enable and configure account recovery 1. Log in to your [Ory Console](https://console.ory.sh/) 2. Select your workspace and project @@ -42,11 +42,21 @@ configure account recovery in your Ory project. ``` -**Recovery strategy** +### Enable SMS account recovery + +Enable the feature flag `choose_recovery_address` to be able to send a recovery code via SMS. + +1. Log in to your [Ory Console](https://console.ory.sh/) +2. Select your workspace and project +3. Navigate to +4. Toggle "Receive a recovery code via SMS" to 'on' +5. Click **Save** + +### Recovery strategy You can choose between the following recovery strategies: -- One-time passwords: Sends a one-time code via email +- One-time passwords: Sends a one-time code via email, or SMS (with the feature flag `choose_recovery_address` enabled) - Magic link: Sends a recovery link via email 1. In the Account recovery section @@ -68,7 +78,7 @@ import BrowserWindow from "@site/src/theme/BrowserWindow" ``` -**Download your current configuration** +### Download your current configuration First, get your current identity configuration: @@ -81,9 +91,14 @@ ory list projects --workspace # Get the configuration ory get identity-config --project --workspace --format yaml > identity-config.yaml + +# Toggle the feature flag 'on' +ory patch project --replace '/services/identity/config/feature_flags/choose_recovery_address=true' + +ory get project --format='jsonpointer=/services/identity/config/feature_flags/choose_recovery_address' ``` -**Edit recovery configuration** +### Edit recovery configuration Add or modify the recovery section in your configuration file: @@ -102,7 +117,7 @@ selfservice: notify_unknown_recipients: false # Define if the system sends automated recovery notifications to unknown email addresses. ``` -**Update your configuration** +### Update your configuration After editing, update your configuration: @@ -135,9 +150,43 @@ When a user initiates account recovery: ### User flow +When the feature flag `choose_recovery_address` is enabled and the `code` method is in use: + +1. They enter their email address on the recovery page +2. If they have multiple recovery addresses, they can pick which one to use +3. They receive a one-time code on their recovery address, via email or SMS, depending on the type of address +4. After entering the code, they're prompted to set a new password +5. Once completed, they regain access to their account with a new password + +--- + +When the feature flag `choose_recovery_address` is disabled, or the `link` method is in use: + 1. They enter their email address on the recovery page 2. They receive either: - A recovery link via email if using the `link` method - A one-time code via email if using the `code` method 3. After clicking the link or entering the code, they're prompted to set a new password 4. Once completed, they regain access to their account with a new password + +## What happens if the address provided by the user is 'wrong'? + +If the address is malformed, or well-formed but not registered as a recovery address for this user: + +- The recovery flow will not complete. This means that no recovery code will be generated and sent. +- The UI will look indistinguishable from the case of a valid recovery address provided. That is to prevent an attacker from + probing the system to discover which addresses are registered. +- If the address is a valid email address but not registered as a recovery address for this user, and the configuration value + `selfservice.flows.recovery.notify_unknown_recipients` is enabled, an email will be sent to this address with this wording (this + can be [customized](../../kratos/emails-sms/sending-emails-smtp#send-emails-using-an-http-server)): + > Hi, + > + > you (or someone else) entered this email address when trying to recover access to an account. + > + > However, this email address is not on our database of registered users and therefore the attempt has failed. + > + > If this was you, check if you signed up using a different address. + > + > If this was not you, please ignore this email. +- If the address is a phone number (meaning a SMS would be sent), or if the configuration value + `selfservice.flows.recovery.notify_unknown_recipients` is disabled, nothing will be sent. diff --git a/docs/kratos/emails-sms/10_sending-sms.mdx b/docs/kratos/emails-sms/10_sending-sms.mdx index 93c1f1c2c..e8c9cfe93 100644 --- a/docs/kratos/emails-sms/10_sending-sms.mdx +++ b/docs/kratos/emails-sms/10_sending-sms.mdx @@ -97,7 +97,7 @@ Read the [Jsonnet documentation](../../kratos/reference/jsonnet.mdx) to learn mo ## Templates -Only the `verification_code` and `login_code` templates support an SMS variant. Use the CLI to configure it: +Only the `recovery_code`, `verification_code`, and `login_code` templates support an SMS variant. Use the CLI to configure it: ```mdx-code-block @@ -132,6 +132,12 @@ Only the `verification_code` and `login_code` templates support an SMS variant. sms: body: plaintext: "base64://WW91ciBsb2dpbiBjb2RlIGlzOiB7eyAuTG9naW5Db2RlIH19" + + recovery_code: + valid: + sms: + body: + plaintext: "base64://WW91ciByZWNvdmVyeSBjb2RlIGlzOiB7eyAuUmVjb3ZlcnlDb2RlIH19CgpAe3sgLlJlcXVlc3RVUkxEb21haW4gfX0gI3t7IC5SZWNvdmVyeUNvZGUgfX0K" ``` 3. Update the Ory Identities configuration using the file you worked with: