From 8b55564269b20da09336b145b3ed032db04daa3a Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Wed, 18 Feb 2026 08:42:45 -0500 Subject: [PATCH 1/6] chore: add page on feature deprecations --- docs/kratos/deprecations/index.mdx | 80 +++++++++++++++++++++ src/components/ConsoleLink/console-link.tsx | 7 +- src/sidebar.ts | 1 + 3 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 docs/kratos/deprecations/index.mdx diff --git a/docs/kratos/deprecations/index.mdx b/docs/kratos/deprecations/index.mdx new file mode 100644 index 0000000000..8d9d7401ed --- /dev/null +++ b/docs/kratos/deprecations/index.mdx @@ -0,0 +1,80 @@ +--- +id: index +title: Feature Deprecations +sidebar_label: Feature Deprecations +--- + +This section lists all behavior that has been deprecated in Ory Kratos. It is recommended to check this section regularly to stay +up-to-date with the latest changes and to avoid relying on deprecated functionality in your implementation. While Ory Kratos is +designed to be backward compatible, some improvements require changes to the underlying implementation, which may lead to the +deprecation of certain functionality. + +Ory is committed to maintaining a high level of quality and performance in our products, and deprecating features is a rare but +necessary step to ensure that we can continue to innovate and improve our offerings. We understand that deprecations can be +disruptive, and we strive to provide clear communication and ample time for users to adapt to changes. We encourage users to +review the deprecation information provided in this section and to reach out to our support channels if they have any questions or +concerns about the deprecation of features in any Ory product. + +## 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 + +Each entry in this section 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. + +## Staying 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 + +### 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. + + diff --git a/src/components/ConsoleLink/console-link.tsx b/src/components/ConsoleLink/console-link.tsx index 5bfe249d4c..92dcd748ff 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.sh" + resolvedRoute.replace("[project]", "current") + "https://console.ory.sh" + + resolvedRoute.replace("[project]", "current") + + (hash ? `#${hash}` : "") return ( <> diff --git a/src/sidebar.ts b/src/sidebar.ts index d934da6619..0ff7861465 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -564,6 +564,7 @@ const kratos: SidebarItemsConfig = [ "identities/sign-in/login-hint", "identities/sign-in/actions", "identities/sign-in/code-submission-limit", + "kratos/deprecations/index", ], }, { From 015ea7eb05bc6255cdc4261e44861ac4f8665aad Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 24 Apr 2026 12:24:11 -0300 Subject: [PATCH 2/6] chore: apply suggestions from code review Co-authored-by: Vincent --- docs/kratos/deprecations/index.mdx | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/docs/kratos/deprecations/index.mdx b/docs/kratos/deprecations/index.mdx index 8d9d7401ed..4b0d40089c 100644 --- a/docs/kratos/deprecations/index.mdx +++ b/docs/kratos/deprecations/index.mdx @@ -1,19 +1,11 @@ --- id: index -title: Feature Deprecations -sidebar_label: Feature Deprecations +title: Feature deprecations +sidebar_label: Feature deprecations --- -This section lists all behavior that has been deprecated in Ory Kratos. It is recommended to check this section regularly to stay -up-to-date with the latest changes and to avoid relying on deprecated functionality in your implementation. While Ory Kratos is -designed to be backward compatible, some improvements require changes to the underlying implementation, which may lead to the -deprecation of certain functionality. +This section lists deprecated behavior in Ory Kratos. Check this section regularly to avoid relying on deprecated functionality. -Ory is committed to maintaining a high level of quality and performance in our products, and deprecating features is a rare but -necessary step to ensure that we can continue to innovate and improve our offerings. We understand that deprecations can be -disruptive, and we strive to provide clear communication and ample time for users to adapt to changes. We encourage users to -review the deprecation information provided in this section and to reach out to our support channels if they have any questions or -concerns about the deprecation of features in any Ory product. ## Who does this apply to? @@ -36,7 +28,7 @@ If you're self-hosting Ory Kratos (either through open source or the OEL), you s 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. -## Staying Informed +## 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 @@ -46,19 +38,19 @@ engaged with other users and developers, and to get support for any questions or ### Admin session extension API (`faster_session_extend`) -**Who is impacted by this change?** +- 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?** +- 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?** +- 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 From f1615cbb7f5d7084ae7f53893bf97ac0c46b46fc Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Sun, 21 Jun 2026 17:10:30 -0400 Subject: [PATCH 3/6] chore: rm sidebar --- src/sidebar.ts | 1350 ------------------------------------------------ 1 file changed, 1350 deletions(-) delete mode 100644 src/sidebar.ts diff --git a/src/sidebar.ts b/src/sidebar.ts deleted file mode 100644 index 0ff7861465..0000000000 --- a/src/sidebar.ts +++ /dev/null @@ -1,1350 +0,0 @@ -// Copyright © 2022 Ory Corp -// SPDX-License-Identifier: Apache-2.0 - -import { - SidebarItem, - SidebarItemConfig, -} from "@docusaurus/plugin-content-docs/src/sidebars/types" - -type SidebarItemsConfig = SidebarItemConfig[] - -const homeLink: SidebarItem = { - type: "link", - href: "/welcome", - className: "all-docs-link", - label: "Go to Start Page", -} - -const polisLink: SidebarItem = { - type: "link", - href: "/polis", - className: "all-docs-link", - label: "Go to Polis Page", -} - -const oidcSSO: SidebarItemConfig = { - type: "category", - label: "OpenID Connect SSO", - link: { - type: "doc", - id: "guides/oauth2-openid-connect", - }, - items: [ - "kratos/social-signin/overview", - { - type: "category", - label: "Social Sign-in Providers", - items: [ - "kratos/social-signin/generic", - "kratos/social-signin/ory", - "kratos/social-signin/google", - "kratos/social-signin/facebook", - "kratos/social-signin/microsoft", - "kratos/social-signin/github", - "kratos/social-signin/apple", - "kratos/social-signin/gitlab", - "kratos/social-signin/auth0", - "kratos/social-signin/salesforce", - "kratos/social-signin/slack", - "kratos/social-signin/spotify", - "kratos/social-signin/discord", - "kratos/social-signin/twitch", - "kratos/social-signin/netid", - "kratos/social-signin/yandex", - "kratos/social-signin/vk", - "kratos/social-signin/dingtalk", - "kratos/social-signin/lark", - "kratos/social-signin/patreon", - "kratos/social-signin/linkedin", - "kratos/social-signin/x-twitter", - "kratos/social-signin/line", - "kratos/social-signin/amazon", - ], - }, - "kratos/social-signin/data-mapping", - "kratos/social-signin/account-linking", - "kratos/social-signin/get-tokens", - "identities/sign-in/social-sign-in/redirect-url", - "kratos/social-signin/native-apps", - "kratos/social-signin/oidc-pkce", - "kratos/social-signin/fedcm", - ], -} - -const api: SidebarItemsConfig = [ - homeLink, - "reference/api", - - "ecosystem/api-design", - { - type: "category", - label: "Operations", - collapsed: false, - collapsible: false, - link: { - type: "generated-index", - slug: "/category/operations-reference", - }, - items: [ - "concepts/personal-access-token", - "guides/cors", - "guides/api-rest-pagination", - "guides/rate-limits", - "guides/ip-allowlist", - "api/eventual-consistency", - "kratos/reference/jsonnet", - "guides/user-impersonation", - ], - }, -] - -const polisApi: SidebarItemsConfig = [polisLink, "polis/reference/api"] - -const sdk: SidebarItemsConfig = [ - homeLink, - "sdk", - { - type: "category", - label: "Identity SDKs", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "kratos/sdk/overview", - }, - items: ["kratos/self-hosted/go"], - }, - { - type: "category", - label: "OAuth2 SDKs", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "hydra/sdk/overview", - }, - items: ["hydra/self-hosted/go", "hydra/self-hosted/js"], - }, - { - type: "category", - label: "Permission SDKs", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "keto/sdk/overview", - }, - items: ["keto/self-hosted/go", "keto/sdk/python"], - }, -] -const cli: SidebarItemsConfig = [ - homeLink, - { - type: "category", - label: "Ory CLI reference", - collapsed: false, - collapsible: false, - link: { - type: "generated-index", - }, - items: [ - "guides/cli/installation", - "guides/cli/cli-basics", - "guides/cli/identity-cli", - "guides/cli/oauth2-cli", - "guides/cli/configure-permission-service", - "guides/cli/proxy-and-tunnel", - "guides/cli/config-with-cli", - { - type: "category", - label: "CLI commands reference", - link: { - type: "generated-index", - }, - items: [ - { - type: "autogenerated", - dirName: "cli", - }, - ], - }, - ], - }, -] - -const quickstart: SidebarItemsConfig = [ - "welcome", - "intro", - "getting-started/local-development", - { - type: "category", - label: "Quickstart", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "getting-started/overview", - }, - items: [ - { - type: "autogenerated", - dirName: "getting-started/integrate-auth", - }, - ], - }, - { - type: "category", - label: "Migrate to Ory", - collapsed: false, - collapsible: false, - items: [ - { - type: "category", - label: "Migrate to Ory Network", - collapsed: true, - collapsible: true, - items: [ - { - type: "category", - label: "Phase 1: Plan & prepare", - collapsed: true, - collapsible: true, - items: [ - "migrate-to-ory/migrate/index", - "migrate-to-ory/migrate/map-to-orycap", - "migrate-to-ory/migrate/migrate-strategies", - //"migrate-to-ory/migrate/faq-migrate", - ], - }, - { - type: "category", - label: "Phase 2: Migrate", - collapsed: true, - collapsible: true, - items: [ - "migrate-to-ory/migrate/create-project", - "migrate-to-ory/migrate/design-id-schema", - "migrate-to-ory/migrate/integrate-frontend", - "migrate-to-ory/migrate/integrate-backend", - "migrate-to-ory/migrate/migrate-identities", - ], - }, - { - type: "category", - label: "Phase 3: Test & validate", - collapsed: true, - collapsible: true, - items: ["migrate-to-ory/migrate/test-validate"], - }, - { - type: "category", - label: "Phase 4: Go live", - collapsed: true, - collapsible: true, - items: ["migrate-to-ory/migrate/go-live"], - }, - ], - }, - "migrate-to-ory/auth0", - ], - }, -] - -const troubleshooting: SidebarItemsConfig = [ - homeLink, - { - type: "category", - label: "Troubleshooting", - collapsible: false, - collapsed: false, - link: { - type: "generated-index", - slug: "/category/troubleshooting", - }, - items: [ - { - type: "autogenerated", - dirName: "troubleshooting", - }, - "oauth2-oidc/identity-provider-integration-settings", - "guides/upgrade/sdk-v1", - "hydra/debug", - "hydra/debug/logout", - "hydra/debug/token-endpoint-auth-method", - ], - }, -] - -const operations: SidebarItemsConfig = [ - homeLink, - { - type: "category", - label: "Operations", - link: { - type: "doc", - id: "guides/operations", - }, - collapsed: false, - collapsible: false, - items: [ - "guides/workspaces", - "console/roles-and-permissions", - "guides/custom-domains", - "console/usage-billing", - "guides/manage-project-via-api", - "console/change-owner", - "guides/gitops", - "actions/live-events", - ], - }, -] - -const kratos: SidebarItemsConfig = [ - homeLink, - "identities/index", - { - type: "category", - label: "Get Started", - collapsed: true, - link: { - type: "doc", - id: "identities/get-started/index", - }, - items: [ - "identities/get-started/setup", - "identities/get-started/sign-up", - "identities/get-started/sign-in", - "identities/get-started/sign-out", - "identities/get-started/session-management", - "identities/get-started/account-recovery", - "identities/get-started/mfa", - "identities/get-started/social-sign-in", - "identities/get-started/passwordless", - ], - }, - { - type: "category", - label: "Concepts", - collapsed: false, - collapsible: false, - link: { - type: "generated-index", - }, - items: [ - "security-model", - "identities/native-browser", - "concepts/redirects", - "kratos/hooks/configure-hooks", - ], - }, - { - type: "category", - label: "Guides", - collapsed: false, - collapsible: false, - link: { - type: "generated-index", - }, - items: [ - { - type: "category", - label: "Authentication", - link: { - type: "generated-index", - slug: "guides/authentication", - }, - items: [ - "kratos/concepts/credentials", - "kratos/concepts/credentials/username-email-password", - "kratos/passwordless/passwordless", - "kratos/passwordless/one-time-code", - "kratos/passwordless/passkeys", - "kratos/organizations/organizations", - "kratos/emails-sms/custom-email-templates", - ], - }, - oidcSSO, - { - type: "category", - label: "Flows", - link: { - type: "doc", - id: "kratos/self-service", - }, - items: [ - "kratos/concepts/browser-redirect-flow-completion", - "kratos/self-service/flows/user-registration", - "kratos/self-service/flows/user-login", - "kratos/self-service/flows/user-logout", - "kratos/self-service/flows/user-settings", - "kratos/self-service/flows/verify-email-account-activation", - "kratos/self-service/flows/account-recovery-password-reset", - "kratos/self-service/flows/user-facing-errors", - ], - }, - { - type: "category", - label: "Session", - link: { - type: "doc", - id: "kratos/session-management/overview", - }, - items: [ - "kratos/session-management/session-management", - "identities/sign-in/check-session", - "kratos/session-management/session-lifespan", - "kratos/session-management/refresh-extend-sessions", - "kratos/session-management/revoke-sessions-hook", - "identities/session-to-jwt-cors", - "concepts/cache", - ], - }, - { - type: "category", - label: "Multi-factor authentication", - link: { - type: "doc", - id: "kratos/mfa/overview", - }, - items: [ - "kratos/mfa/lookup-secrets", - "kratos/mfa/totp", - "kratos/mfa/webauthn-fido-yubikey", - "kratos/mfa/mfa-via-sms", - "kratos/mfa/step-up-authentication", - ], - }, - { - type: "category", - label: "Emails and SMS", - collapsed: true, - collapsible: true, - link: { - type: "doc", - id: "guides/email-sms", - }, - items: [ - "kratos/emails-sms/sending-emails-smtp", - "kratos/emails-sms/sending-sms", - ], - }, - { - type: "category", - label: "Ory Actions", - link: { - type: "doc", - id: "guides/integrate-with-ory-cloud-through-webhooks", - }, - items: [ - { - type: "category", - label: "Identity management", - items: [ - "identities/sign-in/actions", - "actions/revoke-active-sessions", - "actions/session", - "actions/require-verified-address", - { - type: "category", - label: "Integrations", - items: [ - "actions/integrations/hubspot", - "actions/integrations/mailchimp", - "actions/integrations/segment", - ], - }, - ], - }, - ], - }, - { - type: "category", - label: "Search", - items: [ - "kratos/manage-identities/search/identity-search-console", - "kratos/manage-identities/search/identity-search-api", - ], - }, - { - type: "category", - label: "Identity management", - link: { - type: "doc", - id: "kratos/manage-identities/overview", - }, - items: [ - "kratos/manage-identities/create-users-identities", - "kratos/manage-identities/import-user-accounts-identities", - "identities/model/identity-state", - "kratos/manage-identities/invite-users", - "kratos/manage-identities/account-recovery", - "kratos/manage-identities/export-user-accounts-identities", - - { - type: "category", - label: "SCIM", - link: { - type: "doc", - id: "kratos/manage-identities/scim", - }, - items: [ - "kratos/manage-identities/scim/ms-entra", - "kratos/manage-identities/scim/okta", - "kratos/manage-identities/scim/google-workspace", - ], - }, - - "kratos/manage-identities/external-id", - ], - }, - { - type: "category", - label: "Identity schema", - link: { - type: "doc", - id: "kratos/manage-identities/identity-schema", - }, - items: [ - "kratos/manage-identities/managing-users-identities-metadata", - "identities/model/manage-identity-schema", - "kratos/manage-identities/customize-identity-schema", - "identities/model/identity-schema-selection", - "kratos/manage-identities/best-practices", - ], - }, - - { - type: "category", - label: "User interface", - link: { - type: "doc", - id: "kratos/bring-your-own-ui/custom-ui-overview", - }, - items: [ - "account-experience/index", - "kratos/bring-your-own-ui/configure-ory-to-use-your-ui", - "kratos/bring-your-own-ui/custom-vs-built-in-ui", - { - type: "doc", - id: "elements/index", - label: "Ory Elements", - className: "external-link", - }, - { - type: "category", - label: "Build your own UI", - link: { - type: "doc", - id: "getting-started/custom-ui", - }, - items: [ - "kratos/bring-your-own-ui/custom-ui-basic-integration", - "kratos/bring-your-own-ui/custom-ui-advanced-integration", - "kratos/concepts/ui-user-interface", - { - type: "doc", - id: "elements/index", - label: "Ory Elements", - className: "external-link", - }, - ], - }, - ], - }, - ], - }, - { - type: "category", - label: "Configuration", - collapsed: false, - collapsible: false, - items: [ - "identities/sign-in/two-step-registration", - "identities/sign-in/identifier-first-authentication", - "identities/sign-in/login-hint", - "identities/sign-in/actions", - "identities/sign-in/code-submission-limit", - "kratos/deprecations/index", - ], - }, - { - type: "category", - label: "Self-Hosted", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "kratos/quickstart", - }, - items: [ - "kratos/install", - "kratos/quickstart", - { - type: "category", - label: "Configuration", - items: [ - "kratos/configuring", - "kratos/guides/configuring-cookies", - "kratos/guides/multi-domain-cookies", - "self-hosted/kratos/configuration/password", - "kratos/self-hosted/mfa", - "kratos/guides/setting-up-cors", - "self-hosted/kratos/configuration/oidc", - "kratos/guides/setting-up-password-hashing-parameters", - "kratos/guides/select-cipher-algorithm", - "kratos/self-hosted/email-http", - "kratos/reference/configuration-editor", - ], - }, - { - type: "category", - label: "Guides", - items: [ - "kratos/guides/docker", - "kratos/guides/deploy-kratos-example", - "kratos/guides/upgrade", - "kratos/guides/production", - "kratos/guides/multi-tenancy-multitenant", - "self-hosted/operations/scalability", - "kratos/self-hosted/mail-courier-templates", - "kratos/guides/tracing", - "kratos/guides/zero-trust-iap-proxy-identity-access-proxy", - "kratos/guides/https-tls", - "kratos/guides/hosting-own-have-i-been-pwned-api", - "kratos/guides/secret-key-rotation", - { - type: "category", - label: "Troubleshooting", - items: [ - { - type: "autogenerated", - dirName: "kratos/debug", - }, - ], - }, - ], - }, - { - type: "category", - label: "Reference", - items: [ - "kratos/reference/api", - { - "Command Line Interface (CLI)": [ - { - type: "autogenerated", - dirName: "kratos/cli", - }, - ], - }, - { - SDK: ["kratos/sdk/overview", "kratos/self-hosted/go"], - }, - "kratos/reference/configuration", - "kratos/reference/json-schema-json-paths", - "kratos/reference/html-forms", - ], - }, - ], - }, -] - -const hydra: SidebarItemsConfig = [ - homeLink, - "oauth2-oidc/index", - { - type: "category", - label: "Start", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "getting-started/ory-network-oauth2", - }, - items: [ - "getting-started/oauth2-openid/expressjs", - "hydra/guides/using-oauth2", - ], - }, - { - type: "category", - label: "Concepts", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "oauth2-oidc/index", - }, - items: [ - "oauth2-oidc/overview/oauth2-concepts", - "oauth2-oidc/overview/oidc-concepts", - "hydra/concepts/before-oauth2", - "hydra/security-architecture", - ], - }, - - { - type: "category", - label: "Guides", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "hydra/guides/oauth2-token-introspection", - }, - items: [ - { - type: "category", - label: "Flows", - link: { - type: "doc", - id: "oauth2-oidc/authorization-code-flow", - }, - items: [ - "oauth2-oidc/authorization-code-flow", - "oauth2-oidc/client-credentials", - "oauth2-oidc/device-authorization", - "oauth2-oidc/resource-owner-password-grant", - "oauth2-oidc/refresh-token-grant", - "oauth2-oidc/userinfo-oidc", - "oauth2-oidc/oidc-logout", - "oauth2-oidc/wellknown-endpoint-discovery", - ], - }, - { - type: "category", - label: "Token management", - link: { - type: "generated-index", - slug: "guides/token-management", - }, - items: [ - "hydra/guides/oauth2-token-introspection", - "oauth2-oidc/revoke-consent", - "oauth2-oidc/skip-consent", - "oauth2-oidc/jwt-access-token", - "hydra/guides/audiences", - "hydra/guides/jwt", - "hydra/guides/client-token-expiration", - "hydra/guides/graceful-token-refresh", - "oauth2-oidc/claims-scope", - ], - }, - { - type: "category", - label: "Ory Actions", - items: ["hydra/guides/claims-at-refresh"], - }, - { - type: "category", - label: "Client management", - items: [ - "hydra/guides/oauth2-clients", - "hydra/jwks", - "hydra/guides/openid", - "oauth2-oidc/issuer-url", - ], - }, - { - type: "category", - label: "User Interface", - link: { - type: "doc", - id: "hydra/guides/custom-ui-oauth2", - }, - items: ["oauth2-oidc/custom-login-consent/flow", "hydra/guides/logout"], - }, - ], - }, - - { - type: "category", - label: "Self-Hosted", - collapsed: false, - collapsible: false, - items: [ - "hydra/self-hosted/install", - "hydra/self-hosted/quickstart", - - { - type: "category", - label: "Configuration", - items: [ - "hydra/reference/configuration", - "hydra/reference/configuration-editor", - "hydra/self-hosted/configure-deploy", - "hydra/self-hosted/dependencies-environment", - "hydra/self-hosted/production", - "hydra/self-hosted/hsm-support", - "self-hosted/operations/scalability", - "hydra/self-hosted/merge-multiple-db-secrets", - "hydra/self-hosted/gitlab", - "hydra/self-hosted/secrets-key-rotation", - "hydra/self-hosted/kubernetes-helm-chart", - "hydra/self-hosted/ssl-https-tls", - "self-hosted/operations/tracing", - "hydra/guides/cookies", - "hydra/guides/cors", - "self-hosted/hydra/debug/csrf", - ], - }, - { - type: "category", - label: "Guides", - items: [ - "hydra/self-hosted/deploy-hydra-example", - "hydra/self-hosted/upgrade", - ], - }, - { - type: "category", - label: "Reference", - items: [ - "hydra/reference/api", - { - "Command Line Interface (CLI)": [ - { - type: "autogenerated", - dirName: "hydra/cli", - }, - ], - }, - { - SDK: [ - "hydra/sdk/overview", - "hydra/self-hosted/go", - "hydra/self-hosted/js", - ], - }, - ], - }, - ], - }, -] - -const keto: SidebarItemsConfig = [ - homeLink, - "keto/index", - { - type: "category", - label: "Start", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "guides/permissions/overview", - }, - items: ["keto/quickstart", "keto/examples/olymp-file-sharing"], - }, - { - type: "category", - label: "Concepts", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "keto/index", - }, - items: [ - "keto/guides/rbac", - { - type: "autogenerated", - dirName: "keto/concepts", - }, - "keto/reference/ory-permission-language", - ], - }, - { - type: "category", - label: "Guides", - collapsed: false, - collapsible: false, - items: [ - "keto/guides/simple-access-check-guide", - "keto/modeling/create-permission-model", - "keto/guides/list-api-display-objects", - "keto/guides/expand-api-display-who-has-access", - ], - }, - { - type: "category", - label: "Self-Hosted", - collapsed: false, - collapsible: false, - items: [ - "keto/install", - "keto/quickstart", - { - type: "category", - label: "Configuration", - items: [ - "keto/reference/configuration", - "keto/reference/configuration-editor", - ], - }, - { - type: "category", - label: "Guides", - items: [ - "keto/guides/production", - "keto/guides/v0.7-migration", - "keto/guides/migrating-legacy-policies", - "keto/guides/upgrade", - ], - }, - { - Reference: [ - "keto/reference/rest-api", - "keto/reference/proto-api", - { - "Command Line Interface (CLI)": [ - { - type: "autogenerated", - dirName: "keto/cli", - }, - ], - }, - { - SDK: ["keto/sdk/overview", "keto/self-hosted/go"], - }, - ], - }, - ], - }, -] - -const polis: SidebarItemsConfig = [ - homeLink, - "polis/index", - { - type: "category", - label: "Self-Hosted", - collapsed: false, - collapsible: false, - items: [ - "polis/install", - "polis/quickstart", - "polis/reference/api", - { - type: "category", - label: "Enterprise SSO", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "polis/saml-federation/index", - }, - items: [ - { - type: "category", - label: "Concepts", - link: { - type: "doc", - id: "polis/sso-flow/index", - }, - items: [ - "polis/sso-flow/index", - "polis/sso-flow/example-flow", - "polis/security", - ], - }, - { - type: "category", - label: "Configuration", - items: [ - "polis/deploy/env-variables", - "polis/guides/configuring-saml-sso", - "polis/guides/login-with-saml-sso", - "polis/deploy/pre-loaded-connections", - ], - }, - { - type: "category", - label: "Guides", - link: { - type: "doc", - id: "polis/guides/service", - }, - items: [ - "polis/guides/service", - "polis/guides/npm-library", - "polis/upgrade", - "polis/guides/examples", - "polis/sbom", - "polis/container-signing", - "polis/events", - "polis/observability", - { - type: "category", - label: "Frameworks", - items: [ - { - type: "autogenerated", - dirName: "polis/guides/frameworks", - }, - ], - }, - { - type: "category", - label: "Deployment", - items: [ - { - type: "autogenerated", - dirName: "polis/guides/deployment", - }, - ], - }, - ], - }, - { - type: "category", - label: "SAML SSO Providers", - link: { - type: "doc", - id: "polis/sso-providers/index", - }, - items: [ - { - type: "autogenerated", - dirName: "polis/sso-providers", - }, - ], - }, - ], - }, - { - type: "category", - label: "Directory Sync", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "polis/directory-sync/index", - }, - items: [ - "polis/directory-sync/quickstart", - "polis/directory-sync/api-reference", - { - type: "category", - label: "Guides", - collapsed: true, - link: { - type: "generated-index", - slug: "polis/directory-sync/guides", - }, - items: [ - "polis/directory-sync/webhooks", - "polis/directory-sync/events", - "polis/directory-sync/observability", - "polis/directory-sync/examples", - "polis/directory-sync/faq", - { - type: "category", - label: "Directory providers", - link: { - type: "generated-index", - slug: "polis/directory-sync/providers", - }, - items: [ - { - type: "autogenerated", - dirName: "polis/directory-sync/providers", - }, - ], - }, - { - type: "category", - label: "Frameworks", - items: [ - { - type: "autogenerated", - dirName: "polis/directory-sync/guides", - }, - ], - }, - ], - }, - ], - }, - { - type: "category", - label: "Admin Portal", - collapsed: false, - collapsible: false, - link: { - type: "doc", - id: "polis/admin-portal/index", - }, - items: [ - { - type: "category", - label: "Guides", - collapsed: true, - link: { - type: "generated-index", - slug: "polis/admin-portal/guides", - }, - items: [ - "polis/admin-portal/enterprise-sso", - "polis/admin-portal/setup-links-enterprise-sso", - "polis/admin-portal/directory-sync", - "polis/admin-portal/setup-links-directory-sync", - ], - }, - ], - }, - ], - }, -] - -const oathkeeper: SidebarItemsConfig = [ - homeLink, - "oathkeeper/index", - "oathkeeper/install", - "oathkeeper/reference/api", - { - type: "category", - label: "Concepts", - collapsed: false, - collapsible: false, - items: [ - "oathkeeper/api-access-rules", - { - type: "category", - - label: "Handlers", - items: [ - "oathkeeper/pipeline", - "oathkeeper/pipeline/authn", - "oathkeeper/pipeline/authz", - "oathkeeper/pipeline/mutator", - "oathkeeper/pipeline/error", - ], - }, - "oathkeeper/grpc-middleware", - ], - }, - { - type: "category", - label: "Guides", - collapsed: false, - collapsible: false, - items: [ - "oathkeeper/configure-deploy", - "oathkeeper/guides/proxy-websockets", - "oathkeeper/guides/traefik-proxy-integration", - "oathkeeper/guides/upgrade", - ], - }, - { - type: "category", - label: "Reference", - collapsed: false, - collapsible: false, - items: [ - "oathkeeper/reference/configuration", - "oathkeeper/reference/configuration-editor", - { - "Command Line Interface (CLI)": [ - { - type: "autogenerated", - dirName: "oathkeeper/cli", - }, - ], - }, - "oathkeeper/sdk", - ], - }, -] - -const opensource: SidebarItemsConfig = [ - homeLink, - "ecosystem/projects", - { - type: "category", - label: "Open source", - items: [ - "open-source", - "ecosystem/community", - "ecosystem/contributing", - "open-source/commitment", - "ecosystem/software-architecture-philosophy", - { - type: "category", - label: "Guidelines", - items: [ - "open-source/guidelines/rest-api-guidelines", - "kratos/guides/e2e-integration-tests", - ], - }, - ], - }, - { - type: "doc", - label: "Ory Kratos", - id: "kratos/quickstart", - }, - { - type: "doc", - label: "Ory Hydra", - id: "hydra/self-hosted/quickstart", - }, - { - type: "doc", - label: "Ory Keto", - id: "keto/quickstart", - }, - { - type: "doc", - label: "Ory Polis", - id: "polis/quickstart", - }, - { - type: "doc", - label: "Ory Oathkeeper", - id: "oathkeeper/index", - }, - "self-hosted/deployment", - "ecosystem/configuring", - { - type: "category", - label: "Operations and SRE", - items: [ - { - type: "autogenerated", - dirName: "self-hosted/operations", - }, - ], - }, - "ecosystem/upgrading", - "ecosystem/sqa", - "ecosystem/changelog", - { - type: "link", - label: "Search", - href: "https://www.ory.com/docs/search", - }, -] - -const oel: SidebarItemsConfig = [ - homeLink, - "self-hosted/oel/index", - "self-hosted/oel/quickstart", - { - type: "category", - label: "Ory Hydra OAuth2", - items: [ - "self-hosted/oel/oauth2/migrate", - "self-hosted/oel/oauth2/upgrade", - "self-hosted/oel/oauth2/changelog", - "self-hosted/oel/oauth2/token-prefix", - "self-hosted/oel/oauth2/stateless-jwt", - "self-hosted/oel/oauth2/migrate-postgresql-ttl", - "self-hosted/oel/oauth2/revert-database-migrations", - "self-hosted/oel/oauth2/configuration", - ], - }, - { - type: "category", - label: "Ory Oathkeeper Zero Trust", - items: [ - "self-hosted/oel/oathkeeper/upgrade-oathkeeper", - "self-hosted/oel/oathkeeper/changelog", - "self-hosted/oel/oathkeeper/configuration", - ], - }, - { - type: "category", - label: "Ory Kratos Identities", - items: [ - "self-hosted/oel/kratos/upgrade", - "self-hosted/oel/kratos/changelog", - "self-hosted/oel/kratos/configuration", - ], - }, - { - type: "category", - label: "Ory Keto Permissions", - items: [ - "self-hosted/oel/keto/changelog", - "self-hosted/oel/keto/configuration", - ], - }, - { - type: "category", - label: "Ory Polis", - items: ["self-hosted/oel/polis/changelog"], - }, - "self-hosted/oel/monitoring/monitoring", - "self-hosted/oel/high-performance-pooling", -] - -const security: SidebarItemsConfig = [ - homeLink, - "security-compliance/compliance-and-certifications", - "security-compliance/personal-data-location", - "ecosystem/security", - "kratos/concepts/security", - "security-compliance/token-formats", - "concepts/password-policy", - "hydra/security-architecture", - "security-compliance/gdpr", -] - -const elements: SidebarItemsConfig = [ - homeLink, - "elements/index", - { - type: "category", - label: "Guides", - collapsible: false, - link: { - type: "generated-index", - title: "Quickstarts", - description: "Learn how to use Ory Elements in your application!", - slug: "/elements/guides", - keywords: ["guides"], - }, - items: [ - { - type: "autogenerated", - dirName: "elements/guides", - }, - ], - }, - { - type: "category", - label: "Reference", - collapsible: false, - link: { - type: "generated-index", - title: "Ory Elements Reference", - description: "Learn about the most important Ory Elements concepts!", - slug: "/elements/reference", - keywords: ["guides"], - }, - items: [ - ...require("../docs/elements/reference/typedoc-sidebar.ts").items, - "elements/css-reference", - ], - }, -] - -module.exports = { - quickstart, - troubleshooting, - operations, - opensource, - oel, - kratos, - hydra, - keto, - polis, - oathkeeper, - api, - polisApi, - sdk, - cli, - security, - elements, -} From c5ea136704c7c3e9ca87e13f8e9207815a0ad32f Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Mon, 22 Jun 2026 12:59:02 -0400 Subject: [PATCH 4/6] docs: spec for deprecated-features migration intake plan Co-Authored-By: Claude Opus 4.8 (1M context) --- ...ecated-features-migration-intake-design.md | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-22-deprecated-features-migration-intake-design.md 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..a17e6eefcf --- /dev/null +++ b/docs/superpowers/specs/2026-06-22-deprecated-features-migration-intake-design.md @@ -0,0 +1,111 @@ +# Deprecated-features migration intake — design + +**Date:** 2026-06-22 +**Branch:** `jonas-jonas/addDeprecatedFeatures` +**Status:** Approved (design); ready for implementation plan + +## 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). From 277495c10dde117a58daec978020c63d8b7b5d02 Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Mon, 22 Jun 2026 13:13:15 -0400 Subject: [PATCH 5/6] chore: add descriptions for additional features --- docs/kratos/deprecations/index.mdx | 390 +++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) diff --git a/docs/kratos/deprecations/index.mdx b/docs/kratos/deprecations/index.mdx index 03fc3cd23a..14a9b60cc7 100644 --- a/docs/kratos/deprecations/index.mdx +++ b/docs/kratos/deprecations/index.mdx @@ -71,3 +71,393 @@ benefiting from the improved session extension process. configuration option to `false` in your Kratos configuration file. + +### 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. + + + +### 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. + + + +### 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. + + + +### 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. + + + +### 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. + + + +### 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. + + + +### 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. + + From 934299a024ff9c911652497f9e84a4150977536c Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Mon, 22 Jun 2026 18:03:12 -0400 Subject: [PATCH 6/6] chore: move deprecation guides to sections on docs pages --- docs/actions/require-verified-address.mdx | 100 ++++ ...egrate-with-ory-cloud-through-webhooks.mdx | 58 +++ .../sign-in/two-step-registration.mdx | 58 +++ docs/kratos/concepts/ui-user-interface.mdx | 77 +++ docs/kratos/deprecations/index.mdx | 448 +----------------- docs/kratos/passwordless/05_passkeys.mdx | 53 +++ .../20_refresh-extend-session.mdx | 36 ++ ...ecated-features-migration-intake-design.md | 23 +- .../15_magic-link-verification-url.mdx | 53 +++ 9 files changed, 479 insertions(+), 427 deletions(-) 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 index 14a9b60cc7..e6acdc57cc 100644 --- a/docs/kratos/deprecations/index.mdx +++ b/docs/kratos/deprecations/index.mdx @@ -12,7 +12,8 @@ Users of the Ory Network, Ory Kratos (open source) and the OEL (Ory Enterprise L ## How to use this section -Each entry in this section provides information about the deprecated feature, including: +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. @@ -36,428 +37,23 @@ engaged with other users and developers, and to get support for any questions or ## Impacted functionality -### 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. - - - -### 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. - - - -### 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. - - - -### 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. - - - -### 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. - - - -### 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. - - - -### 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. - - - -### 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. - - +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 index a17e6eefcf..48393b53a8 100644 --- 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 @@ -2,7 +2,28 @@ **Date:** 2026-06-22 **Branch:** `jonas-jonas/addDeprecatedFeatures` -**Status:** Approved (design); ready for implementation plan +**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 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. + +