docs: Add breakglass local account documentation when SSO is enabled#296
Open
RomuDeuxfois wants to merge 2 commits into
Open
docs: Add breakglass local account documentation when SSO is enabled#296RomuDeuxfois wants to merge 2 commits into
RomuDeuxfois wants to merge 2 commits into
Conversation
Seb-MIGUEL
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #281
Adds a comprehensive section to the existing
authentication.mdpage documenting how to configure a breakglass local account when SSO (OpenID Connect or SAML2) is enabled.What was added
A new section "Breakglass local account with SSO enabled" appended to
docs/deployment/authentication.md, covering:1. Why you need a breakglass account
Explains the risk of being locked out when the identity provider is unavailable, and why a local admin account is critical for production deployments.
2. How it works
Documents that
openaev.auth-local-enable,openaev.auth-openid-enable, andopenaev.auth-saml2-enableare independent flags that can be enabled simultaneously, based on analysis ofOpenAEVConfig.javaandLogin.tsx.3. Step-by-step configuration
OPENAEV_AUTH-LOCAL-ENABLE=true)OPENAEV_ADMIN_EMAIL,OPENAEV_ADMIN_PASSWORD,OPENAEV_ADMIN_TOKEN)Includes complete configuration examples for both SAML2 and OpenID Connect scenarios, using environment variable syntax (Docker Compose) and
application.propertiessyntax.4. Login page behavior
Explains what users see when both local and SSO auth are enabled (local form + SSO buttons).
5. Operational recommendations
Production checklist including: regular testing, secure credential storage, credential rotation, usage monitoring, and the warning to never disable local auth without an alternative recovery mechanism.
6. FAQ
Answers common questions:
Source analysis
This documentation was written based on analysis of:
openaev-framework/.../OpenAEVConfig.java— the three independent auth flags (authLocalEnable,authOpenidEnable,authSaml2Enable)openaev-api/.../PlatformSettingsService.java— how settings are exposed to the frontendopenaev-front/.../Login.tsx— login page rendering logic (shows local form whenisLocalis true, SSO buttons whenisOpenId/isSaml2is true)application.properties— default configuration values and admin account propertiesNo breaking changes
This is a documentation-only change. No code modifications.