From 8aec18ff384ef3797ff3074523163e78775ba633 Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Thu, 26 Mar 2026 18:20:20 +0100 Subject: [PATCH 1/3] docs: add break-glass SSO account recovery documentation Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/kratos/organizations/organizations.mdx | 74 +++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index c97295b07..81523f38c 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -408,6 +408,80 @@ Jun 10 09:16:40 2038 GMT You can use this information to externally monitor certificate expirations or integrate it into your internal workflows and alerting systems as needed. +## Break-glass account recovery for SSO + +When an organization's SSO provider is unavailable due to an outage or misconfiguration, organization members can't sign in because +they must authenticate through SSO. Break-glass account recovery lets designated users bypass SSO and recover access to their +accounts through email-based recovery. + +Only identities with the `break_glass` flag set on their recovery address can use this feature. Normal organization members without +this flag remain blocked from email-based recovery. + +### How it works + +1. An admin enables the `break_glass` flag on a recovery address for the designated user. +2. The user navigates to the account recovery page and enters their email address. +3. Ory sends a recovery code to the email address. +4. The user enters the recovery code and gets a session. + +### Enable break-glass recovery + +```mdx-code-block + + +``` + +Go to the workspace member settings in the Ory Console and enable the break-glass flag for the user. + +```mdx-code-block + + + +``` + +Use the Admin API to set the `break_glass` flag on a recovery address. You need the identity ID and the index of the recovery +address you want to update. + +```shell +curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID" \ + -H "Authorization: Bearer $ORY_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "op": "replace", + "path": "/recovery_addresses/0/break_glass", + "value": true + } + ]' +``` + +To disable break-glass recovery for a user, set the value to `false`: + +```shell +curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID" \ + -H "Authorization: Bearer $ORY_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "op": "replace", + "path": "/recovery_addresses/0/break_glass", + "value": false + } + ]' +``` + +```mdx-code-block + + +``` + +:::warning + +Grant break-glass recovery only to a small number of trusted users, such as organization administrators. Any user with this flag can +bypass SSO and recover their account through email, which sidesteps your organization's SSO policies. + +::: + ## Self-service organization onboarding ```mdx-code-block From 2b893fa02bc087dda4705d48dae575886df6d310 Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Sat, 28 Mar 2026 21:16:27 +0100 Subject: [PATCH 2/3] docs: update break-glass API to final design - Field renamed from break_glass to break_glass_for_organization (UUID) - Add workspace members API tab (PATCH /workspaces/{ws}/members/{member}) - Add identity admin API tab with org UUID value - Console UI uses "Allow account recovery" toggle - Document org-scoping behavior: flag doesn't carry over if user changes org Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/kratos/organizations/organizations.mdx | 62 +++++++++++++++------ 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index 81523f38c..fb90825fd 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -410,17 +410,18 @@ alerting systems as needed. ## Break-glass account recovery for SSO -When an organization's SSO provider is unavailable due to an outage or misconfiguration, organization members can't sign in because -they must authenticate through SSO. Break-glass account recovery lets designated users bypass SSO and recover access to their -accounts through email-based recovery. +When an organization's SSO provider is unavailable due to an outage or misconfiguration, organization members can't sign in +because they must authenticate through SSO. Break-glass account recovery lets designated users bypass SSO enforcement and recover +access to their accounts through email-based recovery. -Only identities with the `break_glass` flag set on their recovery address can use this feature. Normal organization members without -this flag remain blocked from email-based recovery. +The recovery address stores the organization ID it applies to in the `break_glass_for_organization` field. Recovery is only +allowed when this field matches the identity's current organization. If the user moves to a different organization, the +break-glass flag doesn't carry over. ### How it works -1. An admin enables the `break_glass` flag on a recovery address for the designated user. -2. The user navigates to the account recovery page and enters their email address. +1. An admin enables account recovery for a workspace member through the Ory Console or the workspace members API. +2. The designated user navigates to the account recovery page and enters their email address. 3. Ory sends a recovery code to the email address. 4. The user enters the recovery code and gets a session. @@ -431,16 +432,41 @@ this flag remain blocked from email-based recovery. ``` -Go to the workspace member settings in the Ory Console and enable the break-glass flag for the user. +Go to **Workspace Settings** > **Members**. For workspaces with SSO enabled, an **Allow account recovery** toggle appears for each +organization member. Enable this toggle for the designated user. ```mdx-code-block - + ``` -Use the Admin API to set the `break_glass` flag on a recovery address. You need the identity ID and the index of the recovery -address you want to update. +Use the workspace members API to enable break-glass recovery for a member: + +```shell +curl -X PATCH "https://api.console.ory.sh/workspaces/$WORKSPACE_ID/members/$MEMBER_ID" \ + -H "Authorization: Bearer $ORY_SESSION_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"break_glass": true}' +``` + +To disable break-glass recovery: + +```shell +curl -X PATCH "https://api.console.ory.sh/workspaces/$WORKSPACE_ID/members/$MEMBER_ID" \ + -H "Authorization: Bearer $ORY_SESSION_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"break_glass": false}' +``` + +```mdx-code-block + + + +``` + +You can also set the `break_glass_for_organization` field directly on a recovery address using the identity admin API. Set the +value to the organization's UUID: ```shell curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID" \ @@ -449,13 +475,13 @@ curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDEN -d '[ { "op": "replace", - "path": "/recovery_addresses/0/break_glass", - "value": true + "path": "/recovery_addresses/0/break_glass_for_organization", + "value": "$ORGANIZATION_ID" } ]' ``` -To disable break-glass recovery for a user, set the value to `false`: +To disable break-glass recovery, set the value to the nil UUID: ```shell curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID" \ @@ -464,8 +490,8 @@ curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDEN -d '[ { "op": "replace", - "path": "/recovery_addresses/0/break_glass", - "value": false + "path": "/recovery_addresses/0/break_glass_for_organization", + "value": "00000000-0000-0000-0000-000000000000" } ]' ``` @@ -477,8 +503,8 @@ curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDEN :::warning -Grant break-glass recovery only to a small number of trusted users, such as organization administrators. Any user with this flag can -bypass SSO and recover their account through email, which sidesteps your organization's SSO policies. +Grant break-glass recovery only to a small number of trusted users, such as organization administrators. Any user with this flag +can bypass SSO and recover their account through email, which sidesteps your organization's SSO policies. ::: From b570649ef4ac1dc168528cfe0e2d03dc666d7b28 Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Sat, 28 Mar 2026 21:27:31 +0100 Subject: [PATCH 3/3] docs: split break-glass docs between console and kratos - Console SSO guide (docs/console/single-sign-on.mdx): Console UI toggle and workspace members API - Kratos organizations (docs/kratos/organizations/organizations.mdx): identity admin API with break_glass_for_organization UUID field Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/console/single-sign-on.mdx | 34 ++++++++++ docs/kratos/organizations/organizations.mdx | 71 ++++----------------- 2 files changed, 45 insertions(+), 60 deletions(-) diff --git a/docs/console/single-sign-on.mdx b/docs/console/single-sign-on.mdx index 1b545a788..22e14c652 100644 --- a/docs/console/single-sign-on.mdx +++ b/docs/console/single-sign-on.mdx @@ -57,6 +57,40 @@ this setting, as it may lock out users who have not completed the SSO setup. ::: +## Break-glass account recovery + +When your SSO provider is unavailable due to an outage or misconfiguration, organization members can't sign in. Break-glass +account recovery lets designated users bypass SSO enforcement and recover access to their accounts through email. + +### Enable account recovery for a member + +Go to **Workspace Settings** > **Members**. For workspaces with SSO enabled, an **Allow account recovery** toggle appears for each +organization member. Enable this toggle for the designated user. + +You can also use the workspace members API: + +```shell +curl -X PATCH "https://api.console.ory.sh/workspaces/$WORKSPACE_ID/members/$MEMBER_ID" \ + -H "Authorization: Bearer $ORY_SESSION_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"break_glass": true}' +``` + +To disable account recovery, set `break_glass` to `false` or use the toggle in the Console. + +### How recovery works + +1. The designated user navigates to the account recovery page and enters their email address. +2. Ory sends a recovery code to the email address. +3. The user enters the recovery code and gets a session. + +:::warning + +Grant account recovery access only to a small number of trusted users, such as organization administrators. Any user with this +access can bypass SSO and recover their account through email. + +::: + ## Known limitiations - Only one domain is supported. If you need to support multiple domains, choose one primary domain for SSO and ensure that all diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index fb90825fd..c0e380175 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -410,63 +410,19 @@ alerting systems as needed. ## Break-glass account recovery for SSO -When an organization's SSO provider is unavailable due to an outage or misconfiguration, organization members can't sign in -because they must authenticate through SSO. Break-glass account recovery lets designated users bypass SSO enforcement and recover -access to their accounts through email-based recovery. +When an organization's SSO provider is unavailable, organization members can't sign in. Break-glass account recovery lets +designated users bypass SSO enforcement and recover access through email-based recovery. -The recovery address stores the organization ID it applies to in the `break_glass_for_organization` field. Recovery is only -allowed when this field matches the identity's current organization. If the user moves to a different organization, the -break-glass flag doesn't carry over. +Each recovery address has a `break_glass_for_organization` field that stores the organization UUID it applies to. Recovery is only +allowed when this field matches the identity's current organization. If the user moves to a different organization, the flag +doesn't carry over. -### How it works +For Ory Network users, the easiest way to manage this is through the +[Ory Console SSO settings](/docs/console/single-sign-on#break-glass-account-recovery). -1. An admin enables account recovery for a workspace member through the Ory Console or the workspace members API. -2. The designated user navigates to the account recovery page and enters their email address. -3. Ory sends a recovery code to the email address. -4. The user enters the recovery code and gets a session. +### Set break-glass via the identity admin API -### Enable break-glass recovery - -```mdx-code-block - - -``` - -Go to **Workspace Settings** > **Members**. For workspaces with SSO enabled, an **Allow account recovery** toggle appears for each -organization member. Enable this toggle for the designated user. - -```mdx-code-block - - - -``` - -Use the workspace members API to enable break-glass recovery for a member: - -```shell -curl -X PATCH "https://api.console.ory.sh/workspaces/$WORKSPACE_ID/members/$MEMBER_ID" \ - -H "Authorization: Bearer $ORY_SESSION_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"break_glass": true}' -``` - -To disable break-glass recovery: - -```shell -curl -X PATCH "https://api.console.ory.sh/workspaces/$WORKSPACE_ID/members/$MEMBER_ID" \ - -H "Authorization: Bearer $ORY_SESSION_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"break_glass": false}' -``` - -```mdx-code-block - - - -``` - -You can also set the `break_glass_for_organization` field directly on a recovery address using the identity admin API. Set the -value to the organization's UUID: +Set the `break_glass_for_organization` field on a recovery address to the organization's UUID: ```shell curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDENTITY_ID" \ @@ -496,15 +452,10 @@ curl -X PATCH "https://$PROJECT_SLUG.projects.oryapis.com/admin/identities/$IDEN ]' ``` -```mdx-code-block - - -``` - :::warning -Grant break-glass recovery only to a small number of trusted users, such as organization administrators. Any user with this flag -can bypass SSO and recover their account through email, which sidesteps your organization's SSO policies. +Grant break-glass recovery only to a small number of trusted users. Any user with this flag can bypass SSO and recover their +account through email. :::