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 c97295b07..c0e380175 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -408,6 +408,57 @@ 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, organization members can't sign in. Break-glass account recovery lets +designated users bypass SSO enforcement and recover access through email-based recovery. + +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. + +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). + +### Set break-glass via the identity admin API + +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" \ + -H "Authorization: Bearer $ORY_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "op": "replace", + "path": "/recovery_addresses/0/break_glass_for_organization", + "value": "$ORGANIZATION_ID" + } + ]' +``` + +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" \ + -H "Authorization: Bearer $ORY_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "op": "replace", + "path": "/recovery_addresses/0/break_glass_for_organization", + "value": "00000000-0000-0000-0000-000000000000" + } + ]' +``` + +:::warning + +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. + +::: + ## Self-service organization onboarding ```mdx-code-block