Skip to content

docs: Add breakglass local account documentation when SSO is enabled#296

Merged
RomuDeuxfois merged 1 commit into
mainfrom
docs/breakglass-local-account-sso
May 21, 2026
Merged

docs: Add breakglass local account documentation when SSO is enabled#296
RomuDeuxfois merged 1 commit into
mainfrom
docs/breakglass-local-account-sso

Conversation

@RomuDeuxfois
Copy link
Copy Markdown
Member

Summary

Closes #281

Adds a comprehensive section to the existing authentication.md page 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, and openaev.auth-saml2-enable are independent flags that can be enabled simultaneously, based on analysis of OpenAEVConfig.java and Login.tsx.

3. Step-by-step configuration

  • Step 1: Keep local auth enabled (OPENAEV_AUTH-LOCAL-ENABLE=true)
  • Step 2: Configure a strong admin account (OPENAEV_ADMIN_EMAIL, OPENAEV_ADMIN_PASSWORD, OPENAEV_ADMIN_TOKEN)
  • Step 3: Enable and configure the SSO provider

Includes complete configuration examples for both SAML2 and OpenID Connect scenarios, using environment variable syntax (Docker Compose) and application.properties syntax.

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:

  • Can I hide the local login form?
  • Can I create additional breakglass accounts?
  • Does local auth weaken SSO security?
  • Will SSO users see the local form?

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 frontend
  • openaev-front/.../Login.tsx — login page rendering logic (shows local form when isLocal is true, SSO buttons when isOpenId/isSaml2 is true)
  • application.properties — default configuration values and admin account properties

No breaking changes

This is a documentation-only change. No code modifications.

@Seb-MIGUEL Seb-MIGUEL self-requested a review May 20, 2026 17:15
@RomuDeuxfois RomuDeuxfois force-pushed the docs/breakglass-local-account-sso branch from efa3de5 to 976e269 Compare May 21, 2026 06:49
@RomuDeuxfois RomuDeuxfois merged commit d749464 into main May 21, 2026
1 check passed
@RomuDeuxfois RomuDeuxfois deleted the docs/breakglass-local-account-sso branch May 21, 2026 06:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] Add a local account breakglass when SSO enabled

2 participants