diff --git a/docs/actions/notify-previous-addresses.mdx b/docs/actions/notify-previous-addresses.mdx new file mode 100644 index 0000000000..bff77e4269 --- /dev/null +++ b/docs/actions/notify-previous-addresses.mdx @@ -0,0 +1,70 @@ +--- +id: notify-previous-addresses +title: Notify previous addresses +--- + +```mdx-code-block +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +``` + +The `notify_previous_addresses` action sends a notification to a user's previous email or phone addresses when they change a +verifiable address through the settings flow. Use it to alert users to address changes on their account so they can react if a +change was not made by them. + +The action runs on the `after` settings flow for the `profile` method, after the change is persisted. Notification delivery never +blocks or fails the settings flow: if a message can't be queued, Ory logs a warning and the flow still succeeds. + +## Choose which addresses to notify + +The `recipients` configuration controls which of the user's previous addresses receive a notification: + +| Value | Notifies | +| :------------- | :----------------------------------------------------------------------- | +| `removed` | Only the addresses that were removed by the change. This is the default. | +| `all_verified` | All of the user's previously verified addresses. | +| `all` | All of the user's previous addresses, whether or not they were verified. | + +Only email and phone (SMS) addresses are notified. Ory sends notifications only when the set of verifiable addresses actually +changes. Changing a verification status alone does not trigger a notification. + +## Enable the action + +Enable `notify_previous_addresses` using either the Ory Console or the Ory CLI. + +```mdx-code-block + + +``` + +1. Go to . +2. Enable **Self-service Settings: Notify previous addresses**. +3. Select which addresses to notify under **Notify previous addresses recipients**. +4. Click **Save**. + +```mdx-code-block + + +``` + +Run: + +```shell +ory patch identity-config --project --workspace \ + --add '/selfservice/flows/settings/after/profile/hooks/0/hook="notify_previous_addresses"' \ + --add '/selfservice/flows/settings/after/profile/hooks/0/config/recipients="all_verified"' +``` + +Set `recipients` to `removed`, `all_verified`, or `all`. If you omit it, Ory uses `removed`. + +```mdx-code-block + + +``` + +:::tip + +To require verification of the new address before the change is applied, combine this action with +[`verify_new_address`](verify-new-address.mdx). + +::: diff --git a/docs/actions/require-verified-address.mdx b/docs/actions/require-verified-address.mdx index 798e0eccc4..a20a2f0712 100644 --- a/docs/actions/require-verified-address.mdx +++ b/docs/actions/require-verified-address.mdx @@ -204,6 +204,13 @@ When a user updates their email address or phone number in the settings flow, Or default, the settings flow will display a success message when the profile is updated, but the address remains unverified until the user completes the verification process. +:::tip + +To require verification _before_ the new address replaces the old one, use the [`verify_new_address`](verify-new-address.mdx) +action. Unlike `show_verification_ui`, it defers the change until the user verifies the new address. + +::: + ### Show verification screen after address change If you want users to be immediately redirected to verify their new address after changing it, you can configure the diff --git a/docs/actions/verify-new-address.mdx b/docs/actions/verify-new-address.mdx new file mode 100644 index 0000000000..5123afefb7 --- /dev/null +++ b/docs/actions/verify-new-address.mdx @@ -0,0 +1,123 @@ +--- +id: verify-new-address +title: Verify address changes +--- + +```mdx-code-block +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +``` + +By default, when a user changes their email address or phone number in the settings flow, Ory applies the change immediately and +sends a verification code to the new address. The address stays unverified until the user completes verification, but the old +address is already replaced. + +The `verify_new_address` action makes address changes safer: it defers the change until the user verifies the new address. The +identity's traits are only updated after verification completes. This prevents users from locking themselves out by entering an +address they don't control, and keeps the previous verified address in place until the new one is confirmed reachable. + +## Enable verification before applying address changes + +The `verify_new_address` action runs on the `after` settings flow for the `profile` method. You can enable it using either the Ory +Console or the Ory CLI. + +```mdx-code-block + + +``` + +1. Go to . +2. Enable **Self-service Settings: Verify new addresses**. +3. Click **Save**. + +```mdx-code-block + + +``` + +Run: + +```shell +ory patch identity-config --project --workspace \ + --add '/selfservice/flows/settings/after/profile/hooks/0/hook="verify_new_address"' +``` + +```mdx-code-block + + +``` + +## Behavior + +When the action is enabled and a user changes a verifiable address in the settings flow: + +- Ory keeps the current traits and creates a pending change instead of applying the update immediately. +- Ory starts a verification flow for the new address and sends a verification code to it. +- The traits update only after the user completes verification. Until then, the previous address remains in effect. + +The action enforces these rules: + +- **Privileged session required.** Changing an address is a sensitive update. If the session is no longer privileged, Ory asks the + user to re-authenticate before continuing. +- **One address at a time.** Ory can only verify one new address per settings submission. If the user changes more than one + verifiable address at once, the flow returns an error and applies no change. +- **No duplicate addresses.** If the new address already belongs to another identity, Ory rejects the change immediately on + submission with a duplicate credentials error, instead of failing later on the verification screen. + +```mdx-code-block + + +``` + +For browser clients using native forms, Ory redirects to the verification flow with HTTP 302. + +```mdx-code-block + + +``` + +The settings endpoint returns the settings flow with a `continue_with` field that contains the verification flow for the new +address: + +```json +{ + "id": "...", + "ui": { + "action": "...", + "method": "...", + "nodes": [ + /* ... */ + ] + }, + "continue_with": [ + { + "action": "show_verification_ui", + "flow": { + "id": "d859f6af-1dfe-453e-9320-d572e10edeea", + "verifiable_address": "new-address@ory.com", + "url": "https://ory.example.org/verification?flow=d859f6af-1dfe-453e-9320-d572e10edeea" + } + } + ] +} +``` + +Send the user to the verification flow to confirm the new address. Ory applies the trait change once verification succeeds. + +```mdx-code-block + + +``` + +:::note + +The `verify_new_address` action defers the change until the new address is verified. This differs from the `show_verification_ui` +action described in [Verification on address change](require-verified-address.mdx#verification-on-address-change), which applies +the change immediately and only redirects the user to the verification screen afterwards. + +::: + +## Notify previous addresses + +To also notify the user's previous addresses when an address changes, combine this action with +[`notify_previous_addresses`](notify-previous-addresses.mdx). diff --git a/docs/kratos/hooks/01_configure-hooks.mdx b/docs/kratos/hooks/01_configure-hooks.mdx index 05e7a3d6dd..ae1fde878a 100644 --- a/docs/kratos/hooks/01_configure-hooks.mdx +++ b/docs/kratos/hooks/01_configure-hooks.mdx @@ -91,7 +91,7 @@ social sign-in provider. ### Available actions -There are 4 actions you can use to extend self-service user flows. The `web_hook` action allows you to trigger any custom, +There are 6 actions you can use to extend self-service user flows. The `web_hook` action allows you to trigger any custom, external logic. :::info @@ -100,12 +100,14 @@ Some actions can only be used for specific flows and methods. ::: -| Action | Description | Details | -| :----------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`session`](../../actions/session.mdx) | Signs in the user immediately after they create an account. | For use only with the `after` registration flow. To use it, you must define secrets for secret rotation. | -| [`revoke_active_sessions`](../../actions/revoke-active-sessions.mdx) | Revokes all other active sessions of the user on successful login. | For use only with the login flow. | -| [`require_verified_address`](../../actions/require-verified-address.mdx) | Allows users to sign in only when they verified their email address. | For use only with the `after` login flow, `password` method only. | -| [`web_hook`](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) | Allows to trigger external and custom logic. Can be used with all flows and methods except error and logout. | Requires providing webhook configuration. This is the only action type available for the `after` settings flow. See an example of using webhooks [here](../../guides/integrate-with-ory-cloud-through-webhooks.mdx). | +| Action | Description | Details | +| :------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`session`](../../actions/session.mdx) | Signs in the user immediately after they create an account. | For use only with the `after` registration flow. To use it, you must define secrets for secret rotation. | +| [`revoke_active_sessions`](../../actions/revoke-active-sessions.mdx) | Revokes all other active sessions of the user on successful login. | For use only with the login flow. | +| [`require_verified_address`](../../actions/require-verified-address.mdx) | Allows users to sign in only when they verified their email address. | For use only with the `after` login flow, `password` method only. | +| [`verify_new_address`](../../actions/verify-new-address.mdx) | Defers an address change until the user verifies the new address. | For use only with the `after` settings flow, `profile` method only. | +| [`notify_previous_addresses`](../../actions/notify-previous-addresses.mdx) | Notifies the user's previous addresses when they change a verifiable address. | For use only with the `after` settings flow, `profile` method only. Accepts a `recipients` configuration. | +| [`web_hook`](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) | Allows to trigger external and custom logic. Can be used with all flows and methods except error and logout. | Requires providing webhook configuration. It is the most common action type for the `after` settings flow. See an example of using webhooks [here](../../guides/integrate-with-ory-cloud-through-webhooks.mdx). | ### Trigger precedence diff --git a/sidebars-network.ts b/sidebars-network.ts index 50725c3b7b..ea17f72239 100644 --- a/sidebars-network.ts +++ b/sidebars-network.ts @@ -340,6 +340,8 @@ const networkSidebar = [ "actions/revoke-active-sessions", "actions/session", "actions/require-verified-address", + "actions/verify-new-address", + "actions/notify-previous-addresses", { type: "category", label: "Integrations",