diff --git a/docs/identities/model/identity-schema-selection.mdx b/docs/identities/model/identity-schema-selection.mdx new file mode 100644 index 000000000..8c1ad4088 --- /dev/null +++ b/docs/identities/model/identity-schema-selection.mdx @@ -0,0 +1,97 @@ +--- +id: identity-schema-selection +title: Identity Schema Selection +--- + +```mdx-code-block +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +``` + +# Identity schema selection for self-service registration and login flows + +Ory Kratos now supports selecting an identity schema during **registration** and **login** self-service flows by specifying a +query parameter. This gives administrators more control over which schemas are used and allows multi-tenant or multi-profile +setups with distinct identity models. + +This feature is available in **Ory Kratos OEL** for now and will be available in Ory Network soon. + +## Overview + +- Users or integrators can choose which schema to use by appending the `identity_schema` query parameter when initiating + registration or login flows. +- Only schemas explicitly marked as selectable via `selfservice_selectable: true` in the configuration will be accepted. +- If no schema is selected, the default schema is used (this is the existing behavior). + +## How to Use + +### Registration Example + +**Browser flow:** + +``` +GET /self-service/registration/browser?identity_schema=schema-a +``` + +**API flow:** + +``` +GET /self-service/registration/api?identity_schema=schema-a +``` + +### Login Example + +**Browser flow:** + +``` +GET /self-service/login/browser?identity_schema=schema-a +``` + +**API flow:** + +``` +GET /self-service/login/api?identity_schema=schema-a +``` + +## Configuration + +You must define which schemas are available for self-service selection by using the `selfservice_selectable` flag in your identity +schema configuration. + +### Example Configuration + +```yaml +identity: + default_schema_id: default + schemas: + - id: default + url: file://./schemas/default.schema.json + selfservice_selectable: true + + - id: schema-a + url: file://./schemas/schema-a.schema.json + selfservice_selectable: true + + - id: schema-internal + url: file://./schemas/internal.schema.json + selfservice_selectable: false # This one cannot be selected by end users +``` + +Only schemas where `selfservice_selectable: true` will be selectable via the `identity_schema` parameter. + +## Behavior Summary + +- If a schema is listed and marked as selectable, it can be used in registration/login. +- If a schema is not listed or not marked as selectable, it cannot be used via query param. +- If no `identity_schema` is passed, the default schema (`default_schema_id`) is used. + +## Migration Notes + +- This feature is **non-breaking**. Existing flows using the default schema are unaffected. +- You only need to update configuration if you want to expose multiple schemas for selection. +- Schemas used internally (e.g., for admins or machine users) can remain non-selectable. + +## Related Docs + +- [Manage Identity Schema](./manage-identity-schema) +- [Customizing Identity Schemas](../../kratos/manage-identities/customize-identity-schema) diff --git a/src/sidebar.ts b/src/sidebar.ts index 8bd87cb74..4071e1361 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -448,6 +448,7 @@ const kratos: SidebarItemsConfig = [ "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", ], },