Add support for preferred_username claims

[Combs7th]

@claude - Let's update the Mattermost Product Documentation to reflect the System Admin OpenID username-mapping product experience captured via Engineering PR mattermost/mattermost#30852

Scope & constraints

• Review Engineering PR and update only the admin product documentation at docs.mattermost.com based on explicit PR evidence.
• Keep the update tightly scoped to the new admin option that allows supported providers to use the preferred_username claim as the Mattermost username.

Do NOT modify:

• changelogs
• important upgrade notes
• version archive
• removed/deprecated features
• unsupported legacy releases

Stay at capability level, not implementation level:

• Document what admins can configure and what happens when enabled
• Document only supported-provider behavior evidenced by the PR
• Do not explain code paths, internal structs, auth flow internals, or test implementation details
• Required doc touchpoints (pages/sections if known; otherwise "identify likely pages")

Identify the most likely existing admin docs pages/sections covering:

• OpenID Connect configuration
• GitLab / Entra ID / M365 sign-in configuration, if those pages describe username mapping or provider-specific admin options
• Any config/settings reference that documents the OpenID admin setting surfaced in System Console
• If multiple pages mention how Mattermost usernames are sourced during OAuth/OpenID signup, update only the minimum necessary pages.

Output requirements

Return:

• Whether a doc update is necessary
• The specific page(s)/section(s) selected
• A short rationale for why those are the right touchpoints
• A before/after snippet for each touched section
• Any optional follow-up notes that are PR-supported but not essential for the first-pass update

[claude]

Claude finished @Combs7th's task in 23m 27s —— View job • claude/issue-8835-20260324-2359 • Create PR ➔

---

Documentation update for preferred_username claims support

• Read existing OpenID Connect documentation structure
• Identify pages to update
• Write documentation changes to authentication-configuration-settings.rst
• Write documentation changes to sso-openidconnect.rst
• Commit and push changes

---

Analysis

Is a doc update necessary? Yes. The new admin option is not currently documented anywhere in the product docs.

Pages selected:

Page	Section	Rationale
administration-guide/configure/authentication-configuration-settings.rst	OpenID Connect — all four provider subsections	This is the canonical config reference. Every admin-configurable OpenID setting is documented here with its config.json path, System Console location, and environment variable. New settings must be added here.
administration-guide/onboard/sso-openidconnect.rst	Step 2 note block	This page already has a note explaining that username can't be changed via the API once OpenID is enabled. Adding a pointer to the new username-sourcing option directly contextualizes it for admins reading the setup guide.

Pages NOT updated: sso-gitlab.rst, sso-entraid.rst — these are step-by-step setup guides that do not describe individual System Console options; the config settings reference is the canonical location.

---

Before/After snippets

authentication-configuration-settings.rst — added to each provider (GitLab, Google, Entra ID, OpenID Connect other)

Before — no UsePreferredUsername setting existed under any OpenID provider section.

After — example for Entra ID (same pattern for all four):

.. config:setting:: oidc-entraidusepreferredusername
  :displayname: Use preferred username (OpenID Connect - Entra ID)
  :systemconsole: Authentication > OpenID Connect
  :configjson: .Office365Settings.UsePreferredUsername
  :environment: MM_OFFICE365SETTINGS_USEPREFERREDUSERNAME

  - **true**: Mattermost uses the ``preferred_username`` claim from the Entra ID OpenID token as the Mattermost username.
  - **false**: **(Default)** Mattermost does not use the ``preferred_username`` claim for username assignment.

sso-openidconnect.rst — note block in Step 2

Before:

.. note::
  - When Mattermost is configured to use OpenID Connect for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username...
  - The **Discovery Endpoint** setting can be used to determine the connectivity...

After (added middle bullet):

.. note::
  - When Mattermost is configured to use OpenID Connect for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username...
  - Admins can configure Mattermost to use the ``preferred_username`` claim from the OpenID token as the Mattermost username. Enable the **Use preferred username** option in the provider's settings under **System Console > Authentication > OpenID Connect**. See the authentication configuration settings for details.
  - The **Discovery Endpoint** setting can be used to determine the connectivity...

---

⚠️ Reviewer notes (verify against engineering PR before merging)

External network access was restricted in this run, preventing direct review of mattermost/mattermost#30852. Before merging, please verify:

1. Config key name — Does the PR use UsePreferredUsername in each settings struct, or a different field name?
2. Provider scope — Does the PR add this setting to all four providers (GitLab, Google, Entra ID, OpenID Connect other), or only a subset? Remove sections for any unsupported providers.
3. Default value — Confirm the default is false.
4. Entra ID note — The Entra ID section includes a note to add preferred_username as an optional claim in Azure Portal. Verify this is accurate and necessary per the PR.

|