diff --git a/docs/actions/require-verified-address.mdx b/docs/actions/require-verified-address.mdx index 798e0eccc4..b291080b17 100644 --- a/docs/actions/require-verified-address.mdx +++ b/docs/actions/require-verified-address.mdx @@ -112,6 +112,51 @@ ory patch identity-config --project --workspace \ The `verification` and `show_verification_ui` actions in login flows (but not sign up!) are also deprecated. Use `require_verified_address` instead. +### Verified-address login error (`legacy_require_verified_login_error`) + +When the "require verified address" login hook blocks a login because the address is not yet verified, the response changed. The +legacy behavior returned a `400 Bad Request` with a static error and skipped the check for non-password methods (such as social +sign-in). The new behavior starts a verification flow and returns an actionable `continue_with` entry — `403 Forbidden` with +`continue_with` for API clients, or a `303` redirect to the verification screen for browser clients — and applies to all login +methods. The `feature_flags.legacy_require_verified_login_error` flag restores the old behavior and defaults to `false`. + +#### Am I affected? + +You are affected if any of the following apply: + +- [ ] Your configuration sets `feature_flags.legacy_require_verified_login_error: true`. +- [ ] You enforce verified addresses at login and your client handles the unverified case by checking for a `400 Bad Request` + error rather than parsing `continue_with` (or following the browser redirect). +- [ ] You rely on social sign-in / OIDC logins bypassing the verified-address requirement. + +If your client already parses `continue_with` (or follows the verification redirect) on login, you are not affected. + +#### Why was this change made? + +Returning a verification `continue_with` instead of a terminal error lets users recover from an unverified-address login without a +dead end, and applying the check to all login methods closes a gap where social sign-in could bypass the requirement. + +#### How to adapt to this change? + +Update your login client to handle the new response before disabling the legacy flag: + +- For API / SDK clients, handle `403 Forbidden` and read the `show_verification_ui` action from the `continue_with` array to send + the user into the verification flow. +- For browser clients, follow the `303` redirect to the verification screen. +- If you use social sign-in / OIDC, confirm that requiring a verified address for those logins is acceptable, because the new + behavior no longer exempts them. + + + + After your login client handles the `continue_with` verification response, disable + `feature_flags.legacy_require_verified_login_error` in . + + + After your login client handles the `continue_with` verification response, set + `feature_flags.legacy_require_verified_login_error` to `false` in your Kratos configuration and redeploy. + + + ## Verification on sign up Ory supports two options after sign up: @@ -198,6 +243,61 @@ ory patch identity-config --project --workspace \ --add '/feature_flags/legacy_continue_with_verification_ui=true' ``` +### Verification UI in `continue_with` (`legacy_continue_with_verification_ui`) + +After registration, login, or settings, Kratos can tell the client to show a verification screen by adding a +`show_verification_ui` entry to the flow's `continue_with` array. Previously this entry was added automatically for every +unverified address. Going forward, it is only added when you explicitly enable the `show_verification_ui` hook. The +`feature_flags.legacy_continue_with_verification_ui` flag restores the automatic behavior and defaults to `false`. + +#### Am I affected? + +You are affected if any of the following apply: + +- [ ] Your configuration sets `feature_flags.legacy_continue_with_verification_ui: true`. +- [ ] Your UI or SDK reads `continue_with` for a `show_verification_ui` action **and** you have **not** added the + `show_verification_ui` hook to your post-registration / post-login / post-settings hooks. + +If you already configure the `show_verification_ui` hook, or you do not rely on the verification `continue_with` entry, you are not +affected. + +#### Why was this change made? + +Making the verification screen an explicit hook gives you control over when the verification UI is surfaced, instead of Kratos +always emitting it. It also makes the verification `continue_with` entry behave like other `continue_with` actions, which are +driven by hooks. + +#### How to adapt to this change? + +Add the `show_verification_ui` hook to the `after` hooks of every flow where you want the verification screen surfaced +(registration, login, and settings as applicable). Once the hook is configured, your client receives the same +`show_verification_ui` entry in `continue_with`, and you can set the legacy flag to `false`. + +```yaml +selfservice: + flows: + registration: + after: + hooks: + - hook: show_verification_ui + login: + after: + hooks: + - hook: show_verification_ui +``` + + + + Add the `show_verification_ui` hook to the relevant flows in your project's identity configuration (via the Ory CLI or the Ory + Console configuration editor), then disable + `feature_flags.legacy_continue_with_verification_ui` in . + + + Add the `show_verification_ui` hook to the relevant flows in your Kratos configuration, set + `feature_flags.legacy_continue_with_verification_ui` to `false`, and redeploy. + + + ## Verification on address change When a user updates their email address or phone number in the settings flow, Ory sends a verification code to the new address. By diff --git a/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx b/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx index 0d57e0e397..4ff7905a24 100644 --- a/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx +++ b/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx @@ -4,6 +4,9 @@ title: Trigger custom logic and integrate with external systems with webhooks sidebar_label: Ory Actions --- +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" + Ory Actions supports webhooks, which are HTTP callbacks that can be triggered by specific events in your Ory-powered application. Webhooks allow Ory Actions to notify external systems, such as Hubspot, Mailchimp, when certain events occur, such as a user registration or profile update. Aside from integrating with external systems, webhooks allow you to use custom, external business @@ -625,6 +628,61 @@ trigger these hooks is `after` flows. ::: +### Web hook interrupts (`can_interrupt`) + +The `can_interrupt` option on the `web_hook` allowed a webhook to abort a self-service flow by returning an error response. It has +been replaced by `response.parse`, which is functionally equivalent and lives inside the structured `response` configuration object. +The deprecated `can_interrupt` field still works today but is scheduled for removal. + +#### Am I affected? + +You are affected if any of the following apply to your configuration: + +- [ ] You self-host Ory Kratos and any `web_hook` in your `selfservice` configuration sets `config.can_interrupt: true`. +- [ ] Your Ory Network project configuration contains a `web_hook` with `config.can_interrupt: true`. + +If you do not use webhooks, or none of your webhooks set `can_interrupt`, you are not affected. + +#### Why was this change made? + +The single boolean `can_interrupt` was folded into a structured `response` object so that response-handling behavior can be +configured consistently and extended in the future. The `response` object also exposes `response.ignore` (fire-and-forget +webhooks), and Kratos rejects configurations that set both `response.ignore` and `response.parse` to `true`, because parsing a +response you intend to ignore is contradictory. + +#### How to adapt to this change? + +Replace `can_interrupt: true` with `response.parse: true` in each affected webhook. The behavior is identical: the webhook +response is parsed and can interrupt the flow by returning validation errors. + +```yaml +# Before +- hook: web_hook + config: + url: https://example.com/webhook + method: POST + can_interrupt: true + +# After +- hook: web_hook + config: + url: https://example.com/webhook + method: POST + response: + parse: true +``` + + + + Update your project's identity configuration with the Ory CLI (`ory patch identity-config`) or the configuration editor in the + Ory Console so that each affected webhook uses `response.parse` instead of `can_interrupt`. + + + Edit your Kratos configuration file and replace `can_interrupt: true` with `response.parse: true` for every affected webhook, + then redeploy. + + + ### Webhook retries Sometimes webhook delivery can fail due to issues such as network problems or server errors. To mitigate this, Ory Network diff --git a/docs/identities/sign-in/two-step-registration.mdx b/docs/identities/sign-in/two-step-registration.mdx index 0fe60e0e9f..9b0696676d 100644 --- a/docs/identities/sign-in/two-step-registration.mdx +++ b/docs/identities/sign-in/two-step-registration.mdx @@ -5,6 +5,9 @@ sidebar_label: Two-step registration slug: two-step-registration --- +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" + [Identity traits](../../kratos/manage-identities/managing-users-identities-metadata#traits) are data associated with an identity that can be modified by the user. The traits are configured through the identity schema. @@ -19,3 +22,58 @@ when you have more than two authentication methods enabled. To disable the one-step unified registration, Go to and disable **Enable unified sign up**. + +## One-step registration (`enable_legacy_one_step`) + +The boolean `selfservice.flows.registration.enable_legacy_one_step` is replaced by the string option +`selfservice.flows.registration.style`, which accepts `unified` (one-step) or `profile_first` (two-step). The default is +`profile_first`, so new projects use two-step registration, where users provide their profile information first and their +credentials second. + +### Am I affected? + +You are affected if any of the following apply: + +- [ ] Your configuration sets `selfservice.flows.registration.enable_legacy_one_step`. +- [ ] Your Kratos logs contain the warning `Found use of deprecated configuration key "selfservice.flows.registration.enable_legacy_one_step"`. +- [ ] You have a custom registration UI that assumes a single combined registration form. + +If you do not set `enable_legacy_one_step` and use the default registration UI, you are not affected. + +### Why was this change made? + +A single boolean could not express the growing set of registration layouts. The `style` enum replaces it and leaves room for +additional styles. Two-step registration (`profile_first`) became the default because it produces a clearer experience when +multiple credential methods (password, passkey, code) are enabled. + +### How to adapt to this change? + +Remove `enable_legacy_one_step` and set `style` explicitly. Use `unified` to keep one-step registration, or `profile_first` to +adopt the two-step default. If you operate a custom registration UI, verify it renders correctly for the style you choose — +two-step registration renders profile fields and credential fields on separate screens with a "back" navigation node. + +```yaml +# Before +selfservice: + flows: + registration: + enable_legacy_one_step: true + +# After (keep one-step behavior) +selfservice: + flows: + registration: + style: unified +``` + + + + In , review your registration configuration and set the registration `style` + to `unified` or `profile_first` instead of relying on `enable_legacy_one_step`. Test the registration flow with your UI before + rolling the change out. + + + Replace `enable_legacy_one_step` with the `style` option in your Kratos configuration and redeploy. As long as + `enable_legacy_one_step` is present and `true`, Kratos keeps one-step registration and logs a deprecation warning. + + diff --git a/docs/kratos/concepts/ui-user-interface.mdx b/docs/kratos/concepts/ui-user-interface.mdx index 3eca85c0eb..c1d3b3edc9 100644 --- a/docs/kratos/concepts/ui-user-interface.mdx +++ b/docs/kratos/concepts/ui-user-interface.mdx @@ -96,6 +96,83 @@ Nodes are grouped (using the `group` key) based on the source that generated the You can use the node group to filter out items, re-arrange them, render them differently - up to you! +### OIDC registration node group (`legacy_oidc_registration_node_group`) + +During registration, profile fields collected by the OIDC (social sign-in) method used to be placed in the `oidc` UI node group. +Going forward they are placed in the `default` group, consistent with the other methods. The +`feature_flags.legacy_oidc_registration_node_group` flag restores the old grouping for backwards compatibility and defaults to +`false`. + +#### Am I affected? + +You are affected if any of the following apply: + +- [ ] You enable OIDC / social sign-in for registration **and** your custom registration UI selects, filters, or styles form nodes + by the `oidc` group. +- [ ] Your configuration sets `feature_flags.legacy_oidc_registration_node_group: true`. + +If you use the default Ory UI, or your UI does not branch on node groups, you are not affected. + +#### Why was this change made? + +Placing OIDC profile fields in the `default` group makes registration node grouping consistent across all methods, which +simplifies custom UIs and unifies the experience with two-step registration. + +#### How to adapt to this change? + +Update your custom registration UI to read OIDC profile fields from the `default` node group instead of the `oidc` group. Once your +UI no longer depends on the `oidc` group, set the flag to `false` (or remove it) to adopt the new behavior. + + + + Ory Network projects use the `default` grouping unless the legacy flag was explicitly enabled. Review + to confirm the flag is disabled after your UI is updated. + + + After updating your UI, ensure `feature_flags.legacy_oidc_registration_node_group` is unset or `false` in your Kratos + configuration, then redeploy. + + + +### Password registration node group (`password_profile_registration_node_group`) + +This mirrors the OIDC node-group change for the password method. Profile fields collected by the password method during +registration used to be placed in the `password` UI node group when single-step registration was used; they are now placed in the +`default` group. The `selfservice.methods.password.config.password_profile_registration_node_group` option toggles between +`password` and `default` and defaults to `default`. + +#### Am I affected? + +You are affected if all of the following apply: + +- [ ] Your configuration sets `password_profile_registration_node_group: password`. +- [ ] You use one-step registration (registration `style` is not `profile_first`). +- [ ] Your custom registration UI selects, filters, or styles form nodes by the `password` group. + +If the option is unset (defaults to `default`), or you use two-step registration, you are not affected. + +#### Why was this change made? + +As with the OIDC change, placing password profile fields in the `default` group makes node grouping consistent across methods and +aligns single-step registration with two-step registration. + +#### How to adapt to this change? + +Update your custom registration UI to read password profile fields from the `default` node group, then set +`password_profile_registration_node_group` to `default` or remove it. Adopting two-step registration (`style: profile_first`) +bypasses this option entirely, because profile fields are then collected by the dedicated profile step. + + + + Ory Network projects use the `default` grouping unless the legacy value was explicitly set. After updating your UI, confirm the + option is `default` or unset in . + + + After updating your UI, set `selfservice.methods.password.config.password_profile_registration_node_group` to `default` (or + remove it) in your Kratos configuration, then redeploy. + + + ## UI node types UI Nodes can have several types! diff --git a/docs/kratos/deprecations/index.mdx b/docs/kratos/deprecations/index.mdx new file mode 100644 index 0000000000..e6acdc57cc --- /dev/null +++ b/docs/kratos/deprecations/index.mdx @@ -0,0 +1,59 @@ +--- +id: index +title: Feature deprecations +sidebar_label: Feature deprecations +--- + +This section lists deprecated behavior in Ory Kratos. Check this section regularly to avoid relying on deprecated functionality. + +## Who does this apply to? + +Users of the Ory Network, Ory Kratos (open source) and the OEL (Ory Enterprise License) are affected by this section. + +## How to use this section + +Documentation for each deprecated feature now lives alongside the feature it affects. Each entry provides information about the +deprecated feature, including: + +- A brief description of the feature and its purpose. +- The reason for deprecation, if available. +- The version in which the feature was deprecated. +- Any recommended alternatives or migration paths, if applicable. + +If you're using an Ory Network project, your configuration will not change, unless you have explicitly disabled the deprecated +feature via a project level feature flag. To check which flags are currently enabled, go to + +. + +If you're self-hosting Ory Kratos (either through open source or the OEL), you should review your configuration and codebase to +identify any usage of deprecated features before upgrading to a new version. This will help you avoid any potential issues that +may arise from the removal of deprecated features in future releases. + +## Stay informed + +Subscribe to the [Ory Changelog](https://changelog.ory.com) to receive updates on new releases, including information about +deprecated features and their removal timelines. Additionally, consider joining the Ory community on Slack or GitHub to stay +engaged with other users and developers, and to get support for any questions or issues related to deprecated features. + +## Impacted functionality + +Deprecation notes are documented with the features they affect: + +- **Admin session extension API (`faster_session_extend`)** — + [Refresh sessions](../session-management/20_refresh-extend-session.mdx) +- **Web hook interrupts (`can_interrupt`)** — + [Trigger custom logic and integrate with external systems with webhooks](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) +- **WebAuthn and passkey relying party origin (`rp.origin` and `rp.icon`)** — + [Passkeys & WebAuthN](../passwordless/05_passkeys.mdx) +- **Link strategy base URL (`link.config.base_url`)** — + [Wrong domain in magic links](../../troubleshooting/magic-link-verification-url.mdx) +- **One-step registration (`enable_legacy_one_step`)** — + [Two-step registration](../../identities/sign-in/two-step-registration.mdx) +- **OIDC registration node group (`legacy_oidc_registration_node_group`)** — + [UI node groups](../concepts/ui-user-interface.mdx#ui-node-groups) +- **Password registration node group (`password_profile_registration_node_group`)** — + [UI node groups](../concepts/ui-user-interface.mdx#ui-node-groups) +- **Verification UI in `continue_with` (`legacy_continue_with_verification_ui`)** — + [Address verification](../../actions/require-verified-address.mdx) +- **Verified-address login error (`legacy_require_verified_login_error`)** — + [Address verification](../../actions/require-verified-address.mdx) diff --git a/docs/kratos/passwordless/05_passkeys.mdx b/docs/kratos/passwordless/05_passkeys.mdx index 8e6327be83..5e9c8f631e 100644 --- a/docs/kratos/passwordless/05_passkeys.mdx +++ b/docs/kratos/passwordless/05_passkeys.mdx @@ -111,6 +111,59 @@ Alternatively, use the Ory CLI to enable the passkey strategy: ``` +### WebAuthn and passkey relying party origin (`rp.origin` and `rp.icon`) + +The WebAuthn and passkey relying party (RP) configuration previously accepted a single origin via `rp.origin` and a branding image +via `rp.icon`. The singular `rp.origin` is replaced by `rp.origins`, which accepts a list of origins and supports multi-domain +deployments. The `rp.icon` field is deprecated and ignored for security reasons. + +#### Am I affected? + +You are affected if any of the following apply: + +- [ ] Your `selfservice.methods.webauthn.config.rp` (or `passkey.config.rp`) sets the singular `origin` field. +- [ ] Your relying party configuration sets `rp.icon`. + +If your relying party configuration only sets `id` and `display_name`, you are not affected. + +#### Why was this change made? + +`rp.origins` lets a single project register passkeys and WebAuthn credentials across multiple domains, which the singular +`rp.origin` could not express. The `rp.icon` field was removed because passing an externally controlled image URL into the +credential ceremony was a security concern and had no reliable effect. + +#### How to adapt to this change? + +Move the value of `origin` into a single-element `origins` list and remove `icon`. If your origin is simply the protocol plus +`rp.id`, you can omit `origins` entirely and let Kratos derive it. + +```yaml +# Before +rp: + id: ory.sh + display_name: Ory Foundation + origin: https://www.ory.com + icon: https://www.ory.com/logo.png + +# After +rp: + id: ory.sh + display_name: Ory Foundation + origins: + - https://www.ory.com +``` + + + + Update your project's identity configuration with the Ory CLI (`ory patch identity-config`) or the configuration editor in the + Ory Console: replace `rp.origin` with an `rp.origins` array and remove `rp.icon`. + + + Edit your Kratos configuration file, replace `rp.origin` with `rp.origins`, and remove `rp.icon`, then redeploy. A + configuration that sets both `rp.origin` and `rp.origins` is rejected, so make sure only `rp.origins` remains. + + + ### Identity schema If you want to use a custom identity schema, you must define which field of the identity schema is the display name for the diff --git a/docs/kratos/session-management/20_refresh-extend-session.mdx b/docs/kratos/session-management/20_refresh-extend-session.mdx index 09674e7613..5c1c9e1ff7 100644 --- a/docs/kratos/session-management/20_refresh-extend-session.mdx +++ b/docs/kratos/session-management/20_refresh-extend-session.mdx @@ -69,6 +69,42 @@ To get the Session ID, call the `/sessions/whoami` endpoint or `toSession` SDK m ::: +## Admin session extension API (`faster_session_extend`) + +- Who is impacted by this change? + +This improvement may impact users who are using the `/admin/sessions/{id}/extend` endpoint +([`extendSession`](../../reference/api#tag/identity/operation/extendSession) SDK operation) to extend their users' sessions. The new +implementation may result in faster response times and improved performance when extending sessions. + +- Why was this change made? + +The change was made to improve the performance and efficiency of the session extension process. By decoupling the session +extension from the retrieval of the updated session information, we can reduce the processing time and resource usage for +extending sessions, especially in scenarios with high traffic or large session data. + +- How to adapt to this change? + +If your application is using the updated session returned by the `/admin/sessions/{id}/extend` endpoint after the session +extension, you will need to update your implementation to retrieve the updated session information separately, using the +`/admin/sessions/{id}` endpoint ([`getSession`](../../reference/api#tag/identity/operation/getSession) SDK operation) after the +session extension. + +After you reviewed your usage of this API, follow the instructions below based on your deployment type to ensure that you are +benefiting from the improved session extension process. + + + + Go to and enable the + "Faster session extension" feature flag to benefit from this improvement. + + + Starting with [Ory Kratos v1.3.0](https://github.com/ory/kratos/releases/tag/v1.3.0), the faster session extension process is + enabled by default. If you need to disable this feature for any reason, you can set the `feature_flags.faster_session_extend` + configuration option to `false` in your Kratos configuration file. + + + ## Refresh threshold You can limit the time in which the session can be refreshed by adjusting the `earliest_possible_extend` configuration. diff --git a/docs/superpowers/specs/2026-06-22-deprecated-features-migration-intake-design.md b/docs/superpowers/specs/2026-06-22-deprecated-features-migration-intake-design.md new file mode 100644 index 0000000000..48393b53a8 --- /dev/null +++ b/docs/superpowers/specs/2026-06-22-deprecated-features-migration-intake-design.md @@ -0,0 +1,132 @@ +# Deprecated-features migration intake — design + +**Date:** 2026-06-22 +**Branch:** `jonas-jonas/addDeprecatedFeatures` +**Status:** Implemented as full migration guides (not stubs) per follow-up request. +See "Implementation note" below. + +## Implementation note (2026-06-22) + +The follow-up instruction was to write **full** migration guides for each deprecated +feature — matching the depth of the existing `faster_session_extend` entry and adding +explicit "Am I affected?" checklists — rather than the `TODO(collect)` stubs this +design originally proposed. All seven in-scope features were written as complete +`###` entries in `docs/kratos/deprecations/index.mdx`, plus the +`password_profile_registration_node_group` triage candidate (it is an unambiguous +deprecation that mirrors the OIDC node-group change). Each entry follows the template: +short description → **Am I affected?** checklist → **Why was this change made?** → +**How to adapt?** with `` for Ory Network vs Self-hosted. + +Content was sourced from code-verified research (config getters, schema defaults, +deprecation events). Two genuinely unknown facts were intentionally **not** invented: +exact removal version numbers (phrased as "scheduled for removal" / "a future +release") and per-flag Ory Console deep-link anchors (the entries link to the Advanced +settings page generically). The remaining two triage candidates +(`use_continue_with_transitions`, `choose_recovery_address`) were deferred: they are +V1/V2 behavior switches rather than clear deprecations. + +## Goal + +Produce a repeatable **intake artifact** that, for each in-scope deprecated Ory +Kratos feature, captures what we already know from code research and clearly marks +what still needs to be *collected* from the Ory changelog / engineering / PM before +customer-facing migration advice is finalized. + +This is an **intake/research plan**, not the finished docs and not a standalone +customer migration guide. The stubs it produces are designed to become the published +docs once their gaps are filled, so there is no throwaway work. + +## Background + +- The branch already ships `docs/kratos/deprecations/index.mdx` with one fully-worked + entry, `faster_session_extend`, using a clear template: + **Who is impacted? → Why was this change made? → How to adapt?** with + `` for **Ory Network** vs **Self-hosted (OSS or OEL)**. +- A prior research session traced ~20 config flags/migration toggles in the + kratos-oss codebase. Findings are summarized in the session handoff. Code tracing + is complete and should **not** be re-run. + +## Artifact form + +Per-feature **stub entries** that mirror the existing `faster_session_extend` +template. Each stub: + +- Is appended as a `###` section to `docs/kratos/deprecations/index.mdx` + (matching the single existing entry — see Structure decision). +- Is pre-filled with the code-research facts we already have ("what changed", + affected endpoint/strategy, source-of-truth getter). +- Carries explicit `{/* TODO(collect): ... */}` placeholders for each unfilled gap, + so an editor knows exactly what to chase and from whom. + +Each stub tracks four **collectible gaps**: + +1. **Deprecation + removal version/timeline** — source: Ory changelog / release + notes / engineering. +2. **Official migration-steps wording** — the recommended, customer-safe upgrade + steps per deployment; source: engineering/PM sign-off. +3. **Deployment availability** — confirm Network / OEL / OSS applicability (several + flags are Network-only or behave differently self-hosted). +4. **Customer impact / who is affected** — a concrete signal (config value, API + usage, UI pattern) a customer can self-check against. + +A small **status table** sits at the top of the plan output: one row per feature +with the gaps still outstanding and an owner, so the collection work is assignable +and scannable at a glance. + +## In-scope features + +True deprecations + clean field replacements: + +| # | Feature | Type | Replacement / target | Code reference (from research) | +|---|---|---|---|---| +| 1 | `legacy_continue_with_verification_ui` | deprecation | modern `continue_with` verification UI | `selfservice/hook/verification.go:203-210` | +| 2 | `legacy_require_verified_login_error` | deprecation | new verified-login error behavior | `selfservice/hook/require_verified_address.go` | +| 3 | `legacy_oidc_registration_node_group` | deprecation | `default` node group | `selfservice/strategy/oidc/strategy.go:754-773` | +| 4 | `enable_legacy_one_step` | deprecation | `registration.style` | `SelfServiceFlowRegistrationTwoSteps()` `config.go:693-708` | +| 5 | `web_hook.can_interrupt` | field replacement | `response.parse` | `selfservice/hook/web_hook.go:302-440` | +| 6 | WebAuthn `rp.origin` (+ `rp.icon` ignored) | field replacement | `rp.origins` | `config.go:1534-1548` | +| 7 | `link.config.base_url` | field replacement | remove (request URL used) | no getter (ignored) | + +## Triage candidates + +Legacy-ish but ambiguous; the plan will surface each for an explicit include/exclude +decision **before** stubbing, rather than silently including or dropping them: + +- `password_profile_registration_node_group` (`password` → `default`) — + `selfservice/strategy/password/registration.go:195-235` +- `use_continue_with_transitions` (redirect vs `continue_with` array) +- `choose_recovery_address` (Recovery V1 vs V2) — + `selfservice/flow/recovery/flow.go:153-157` + +## Structure decision + +Stubs are added as `###` sections in the existing +`docs/kratos/deprecations/index.mdx`, matching the one existing entry, because: + +- There is no sidebar wiring for sub-pages under `deprecations/`. +- The page already presents itself as a single list ("Each entry in this section…"). + +Revisit splitting into separate files only if the list outgrows a single readable +page. + +## Out of scope + +- **Silent default changes** (e.g. `verification.use`/`recovery.use` → `code`, + `registration.style` → `profile_first`). +- **Experimental flags** (e.g. login `identifier_first`). +- **Network-only behavior flags** (e.g. `cacheable_sessions`, + `account_linking_mode`). + +(These were deliberately excluded for this intake; they may warrant their own +"upgrade notes" effort later.) + +## Success criteria + +- Every in-scope feature has a stub in `index.mdx` following the established + template, pre-filled with known facts and with a `TODO(collect)` for each of the + four gaps it is missing. +- The three triage candidates are each resolved (included as stubs or explicitly + deferred) with a one-line rationale. +- A status table lists each feature, outstanding gaps, and an owner. +- No code re-tracing; the build/lint for the docs page still passes + (stubs are valid MDX). diff --git a/docs/troubleshooting/15_magic-link-verification-url.mdx b/docs/troubleshooting/15_magic-link-verification-url.mdx index c17868bda9..174215775a 100644 --- a/docs/troubleshooting/15_magic-link-verification-url.mdx +++ b/docs/troubleshooting/15_magic-link-verification-url.mdx @@ -4,6 +4,9 @@ title: Magic links use old custom domain name sidebar_label: Wrong domain in magic links --- +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" + After updating their custom domain, some users reported an error that caused the verification emails to come with magic links generated for the old domain. @@ -30,3 +33,53 @@ Ory recommends using the "one-time code" verification method. Read [this document](../kratos/self-service/flows/verify-email-account-activation.mdx#choosing-the-right-strategy) to learn more. ::: + +## Link strategy base URL (`link.config.base_url`) + +The `selfservice.methods.link.config.base_url` option used to override the base URL for recovery and verification links. It now has +no effect: the base URL for generated links is derived from the incoming request URL instead. + +### Am I affected? + +You are affected if: + +- [ ] Your `selfservice.methods.link.config` sets `base_url`. + +### Why was this change made? + +Deriving the base URL from the request makes recovery and verification links correct across multiple domains and behind reverse +proxies without a static override, so the per-strategy `base_url` became redundant and was removed. + +### How to adapt to this change? + +Remove `base_url` from your link strategy configuration. It is ignored, so removing it does not change behavior. If you need to +control the public base URL globally, set `serve.public.base_url` (self-hosted) and make sure any reverse proxy forwards the +correct `Host` header to Kratos. + +```yaml +# Before +selfservice: + methods: + link: + config: + base_url: https://my-app.com + lifespan: 1h + +# After +selfservice: + methods: + link: + config: + lifespan: 1h +``` + + + + Remove `base_url` from the link method configuration. Recovery and verification links already use the request URL on Ory + Network, so no further action is required. + + + Remove `base_url` from your Kratos configuration. If links need a specific host, configure `serve.public.base_url` and ensure + your proxy forwards the correct `Host` header. + + diff --git a/src/components/ConsoleLink/console-link.tsx b/src/components/ConsoleLink/console-link.tsx index c1a20ecf50..2513d0083a 100644 --- a/src/components/ConsoleLink/console-link.tsx +++ b/src/components/ConsoleLink/console-link.tsx @@ -4,6 +4,7 @@ import { projectPaths, workspacesPaths } from "./console-nav-data" type ConsoleLinkProps = { route: string + hash?: string } const flatConsolePaths = [...projectPaths, ...workspacesPaths].flatMap((p) => { @@ -33,7 +34,7 @@ const flatConsolePaths = [...projectPaths, ...workspacesPaths].flatMap((p) => { * @param route a (possible nested) accesor from the routes object * @returns */ -export default function ConsoleLink({ route }: ConsoleLinkProps) { +export default function ConsoleLink({ route, hash }: ConsoleLinkProps) { const routeObj = route.split(".").reduce((p, c) => p[c], routes) if (!routeObj || (typeof routeObj !== "string" && !("route" in routeObj))) { throw new Error("Route not found: " + route) @@ -61,7 +62,9 @@ export default function ConsoleLink({ route }: ConsoleLinkProps) { // TODO: add current project resolution via the console API const renderedRoute = - "https://console.ory.com" + resolvedRoute.replace("[project]", "current") + "https://console.ory.com" + + resolvedRoute.replace("[project]", "current") + + (hash ? `#${hash}` : "") return ( <>