docs: document OIDC first-user auto-admin behavior (#3292)

[Yeraze]

Summary

Fixes #3292. The docs/configuration/sso.md "Admin Privileges" section claimed OIDC login never elevates privileges, but since commit 2a06f3b8 (issue #2749) the first OIDC user to log in is auto-promoted to admin to avoid locking out a deployment when local auth is disabled.

Changes

• Document that the first OIDC user gets admin (with full permissions on all resources) and explain why (bootstrap / lockout prevention).
• Clarify that all subsequent OIDC users are created as regular non-admin accounts requiring explicit promotion.
• Add a warning that "first OIDC user" means the first user with authMethod = 'oidc', independent of any existing local accounts (e.g. the built-in admin).

Verification

Behavior confirmed against src/server/auth/oidcAuth.ts:247-289: isFirstOidcUser = !allUsersForBootstrap.some(u => u.authMethod === 'oidc') drives isAdmin and full-permission grant.

Docs-only change.

🤖 Generated with Claude Code

[github-actions]

Claude finished @Yeraze's task —— View job

---

PR Review Complete ✅

I've thoroughly reviewed this documentation update for OIDC first-user auto-admin behavior. Here's my comprehensive feedback:

Review Tasks:

• Read and analyze the modified documentation file
• Review the referenced implementation code
• Verify documentation accuracy against implementation
• Check for security considerations and clarity
• Provide comprehensive feedback

🟢 Overall Assessment: APPROVED

This is an excellent documentation fix that addresses a critical gap between implementation and documentation. The changes are accurate, well-written, and appropriately address security concerns.

✅ Strengths

1. Technical Accuracy

• Documentation perfectly matches the implementation in src/server/auth/oidcAuth.ts:247-289
• Correctly describes the isFirstOidcUser logic: !allUsersForBootstrap.some(u => u.authMethod === 'oidc')
• Accurately reflects the full permission grant behavior (lines 271-289)

2. Security Awareness

• Excellent warning callout explaining the "first OIDC user" definition
• Clear guidance for deployments that don't want this behavior
• Good recommendation to keep local auth as a break-glass option
• Proper emphasis on the security implications

3. Clarity and Completeness

• Clear distinction between first vs. subsequent OIDC users
• Proper rationale explaining why this behavior exists (lockout prevention)
• Step-by-step guidance for granting additional admin permissions

🔧 Code Quality

Documentation Standards: ✅

• Follows existing markdown formatting conventions
• Uses appropriate warning callouts and emphasis
• Maintains consistent tone with rest of documentation

Implementation Verification: ✅

• Reviewed the actual code implementation
• Bootstrap logic correctly implemented for lockout prevention
• Proper permission grant mechanism in place

🛡️ Security Considerations

Positive Security Aspects:

• Documents a legitimate security feature (prevents lockout)
• Warns users about the implications
• Provides clear guidance for alternative approaches
• Recommends keeping break-glass local admin access

No Security Concerns: The documented behavior is intentional and necessary for preventing administrative lockout scenarios.

📋 Minor Suggestions (Optional)

1. Consider adding a cross-reference to issue [BUG] OIDC first login isn't set to admin #2749 in the documentation for historical context
2. The warning box formatting is excellent and appropriately draws attention

🎯 Summary

This PR successfully addresses issue #3292 by documenting behavior that was implemented but undocumented. The change:

• ✅ Fixes misleading documentation that claimed SSO "never elevates privileges"
• ✅ Clearly explains the first-user bootstrap behavior
• ✅ Provides appropriate security warnings and guidance
• ✅ Matches implementation exactly
• ✅ Improves operational clarity for administrators

Recommendation: MERGE - This is a valuable documentation improvement with no drawbacks.

---

Files Changed: docs/configuration/sso.md (+8/-2)
Change Type: Documentation only
Risk Level: None (documentation only)