Document OAuth2 username claim resolution and configuration

[3keyroman]

Changes

• Document how the platform resolves the user identity from OAuth2 token claims: the configured usernameClaim (default username) is the single source, with no fallback to any other claim
• Add configuration guidance for identity providers that issue preferred_username instead, such as Microsoft Entra ID
• Warn that changing the username claim of an existing provider changes the username resolved from tokens, so existing users may no longer match on login
• State the issuer URL uniqueness requirement across OAuth2 providers

[Copilot]

Pull request overview

This PR updates the ILM documentation to clearly describe how OAuth 2.0 user identity is derived from token claims, emphasizing that a single configured claim (usernameClaim, defaulting to username) is authoritative with no fallback behavior. It also adds operational guidance for common IdP configurations (e.g., Microsoft Entra ID) and warns about impacts when changing the configured claim or issuer matching.

Changes:

• Documents deterministic username resolution using usernameClaim (or username by default) with no fallback when missing.
• Adds configuration guidance for IdPs that emit preferred_username instead of username.
• Adds warnings about changing usernameClaim on existing providers and clarifies issuer URL uniqueness requirements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.