Add support for preferred_username claims

[Combs7th]

Adds Use preferred username setting documentation to each OpenID Connect provider section in the authentication configuration settings reference, and a note in the OpenID Connect SSO setup guide.

Closes #8835

Generated with Claude Code

[Combs7th]

@cpoile - Do the above doc updates look accurate to you?

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 3f0b790

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates added new OpenID Connect configuration settings for four OIDC providers (GitLab, Google, Entra ID, and generic OIDC) that enable administrators to assign Mattermost usernames from the preferred_username claim. Administrative guidance was added to the OpenID Connect setup documentation.

Changes

Cohort / File(s)	Summary
Configuration Settings Reference source/administration-guide/configure/authentication-configuration-settings.rst	Documented four new UsePreferredUsername boolean configuration options (defaulting to false) for GitLab, Google, Entra ID, and generic OIDC providers, including System Console paths, config.json paths, environment variables, and behaviour descriptions. Entra ID section includes additional guidance on configuring the claim in Azure portal.
OIDC Setup Guide source/administration-guide/onboard/sso-openidconnect.rst	Added note informing administrators that the Use preferred username option in System Console > Authentication > OpenID Connect enables setting Mattermost usernames from the OpenID token's preferred_username claim.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title concisely summarizes the main change: adding support for the preferred_username claims in OpenID Connect configuration.
Description check	✅ Passed	The description is clearly related to the changeset, explaining that the PR adds documentation for the new 'Use preferred username' setting across OpenID Connect provider sections and references the closed issue.
Linked Issues check	✅ Passed	The changes successfully implement the linked issue #8835 objectives by adding documentation for the preferred_username setting to the authentication configuration reference and OpenID Connect SSO setup guide.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to updating documentation for the preferred_username feature across OpenID Connect provider sections and SSO setup guide as required by issue #8835.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-8835-20260324-2359

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

source/administration-guide/configure/authentication-configuration-settings.rst (1)

2350-2352: Consider adding a claim-availability note for non-Entra providers too.

Only the Entra section explicitly tells admins how to make preferred_username available. Adding a short equivalent caveat in Google/generic sections (or one shared note) would reduce setup ambiguity.

Also applies to: 2602-2604

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@source/administration-guide/configure/authentication-configuration-settings.rst`
around lines 2350 - 2352, Add a short claim-availability caveat stating that the
preferred_username claim must be exposed by the identity provider for Mattermost
to use it (mentioning the Google OpenID token and generic OIDC providers), and
either point readers to the existing Entra instructions for how to enable that
claim or briefly describe the equivalent provider-side step (e.g., map/emit
preferred_username in the provider's token/claims configuration); reference the
`preferred_username` claim and the Google/OpenID/OIDC sections so readers know
where to apply this note.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@source/administration-guide/onboard/sso-openidconnect.rst`:
- Line 32: The provider-specific onboarding pages for GitLab, Google, and Azure
AD need to mention the new "Use preferred username" option: update each
provider's onboarding page where username sourcing is described to add a short
sentence that usernames can be taken from the OpenID Connect preferred_username
claim by enabling the Use preferred username option in System Console >
Authentication > OpenID Connect, and link to the existing authentication
configuration settings reference (the :ref:`authentication configuration
settings
<administration-guide/configure/authentication-configuration-settings:openid
connect>` reference used in sso-openidconnect.rst). Locate the username sourcing
sections in the GitLab, Google, and Azure AD onboarding docs and add this
single-line note with the same phrasing and reference as the generic OIDC page
for consistency.

---

Nitpick comments:
In
`@source/administration-guide/configure/authentication-configuration-settings.rst`:
- Around line 2350-2352: Add a short claim-availability caveat stating that the
preferred_username claim must be exposed by the identity provider for Mattermost
to use it (mentioning the Google OpenID token and generic OIDC providers), and
either point readers to the existing Entra instructions for how to enable that
claim or briefly describe the equivalent provider-side step (e.g., map/emit
preferred_username in the provider's token/claims configuration); reference the
`preferred_username` claim and the Google/OpenID/OIDC sections so readers know
where to apply this note.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bc6867f3-2d5e-448b-826c-32800ebb069b

📥 Commits

Reviewing files that changed from the base of the PR and between d3bebad and 3f0b790.

📒 Files selected for processing (2)

• source/administration-guide/configure/authentication-configuration-settings.rst
• source/administration-guide/onboard/sso-openidconnect.rst

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify whether provider-specific SSO docs mention preferred_username.
# Expected: sso-gitlab.rst, sso-google.rst, and sso-entraid.rst should mention preferred_username
# where they describe username sourcing/authority.

fd -a 'sso-(gitlab|google|entraid)\.rst$' source | while read -r f; do
  echo "=== $f ==="
  rg -n -C2 'preferred_username|username|authoritative source' "$f"
  echo
done

Repository: mattermost/docs

Length of output: 1530

---

Provider-specific onboarding docs lack reference to the new Use preferred username option.

The generic OIDC page now documents the Use preferred username option (line 32), but the provider-specific onboarding pages for GitLab, Google, and Azure AD don't mention this feature where they describe username sourcing. Since these pages explain that usernames must come from the OpenID Connect/OAuth 2.0 provider, they should reference the new preferred_username claim option for consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@source/administration-guide/onboard/sso-openidconnect.rst` at line 32, The
provider-specific onboarding pages for GitLab, Google, and Azure AD need to
mention the new "Use preferred username" option: update each provider's
onboarding page where username sourcing is described to add a short sentence
that usernames can be taken from the OpenID Connect preferred_username claim by
enabling the Use preferred username option in System Console > Authentication >
OpenID Connect, and link to the existing authentication configuration settings
reference (the :ref:`authentication configuration settings
<administration-guide/configure/authentication-configuration-settings:openid
connect>` reference used in sso-openidconnect.rst). Locate the username sourcing
sections in the GitLab, Google, and Azure AD onboarding docs and add this
single-line note with the same phrasing and reference as the generic OIDC page
for consistency.