docs: clarify Entra ID SAML attribute namespace matching

[ewwollesen]

Summary

Mattermost matches SAML assertion attributes by their full Name (or FriendlyName), including any namespace, character-for-character. Microsoft Entra ID emits its built-in claims under the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ namespace by default, so an admin who enters the short name shown in the Entra UI (e.g. email, name) into the Mattermost attribute fields gets a silent mismatch and login fails with:

SAML login was unsuccessful because one of the attributes is incorrect. Please contact your System Administrator., <attribute> attribute is missing

The current Entra ID guide mentions editing "claim names and namespaces" but doesn't explain that the value entered in Mattermost must be the fully-qualified claim name (or that the namespace must be cleared in Entra). The SAML FAQ has no entry for this error at all. This is a recurring support issue.

Changes

• sso-saml-entraid.rst: add an .. important:: note under the Attributes & Claims step explaining exact full-name matching, the two ways to reconcile it (clear the namespace in Entra, or use the fully-qualified name in Mattermost), and how to confirm the real claim names with SAML-tracer. Cross-referenced from the Mattermost-side attribute step.
• sso-saml-faq.rst: add a provider-agnostic troubleshooting entry for the "one of the attributes is incorrect" / "<attribute> attribute is missing" failure. This FAQ is include-ed on all SAML provider pages, so it surfaces for Okta/OneLogin/ADFS/Keycloak/Entra alike.

Source

Derived from a support investigation (ticket 51591) where a captured Entra assertion confirmed the IdP sent http://schemas.xmlsoap.org/ws/2005/05/identity/claims/{email,name,emailaddress} while the config used short names.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds documentation guidance for a recurring SAML support issue: Mattermost matches SAML attribute names character-for-character against the IdP assertion, including any namespace prefix. The Entra ID guide and the shared SAML FAQ are updated so admins understand and can troubleshoot the "<attribute> attribute is missing" login failure caused by namespaced claim names.

Changes:

• Add an .. important:: block under step 9 of the Entra ID guide explaining full-name (namespace-aware) matching and the two reconciliation paths (clear the namespace in Entra, or use the fully-qualified name in Mattermost), plus a cross-reference from step 15.
• Add a provider-agnostic FAQ entry covering the "one of the attributes is incorrect" error, with guidance to inspect the assertion via SAML-tracer.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
source/administration-guide/onboard/sso-saml-entraid.rst	Adds emphasis on namespaces in step 9.b, an .. important:: block detailing the namespace pitfall and two fixes, and a pointer from step 15 to that note.
source/administration-guide/onboard/sso-saml-faq.rst	Adds a new FAQ entry explaining the "<attribute> attribute is missing" failure and how to resolve it, included on all SAML provider pages.

I did not find any blocking issues. Verified:

• The .. important:: directive at column 0 follows the same pattern as the existing .. note:: block between steps 14 and 15 in the same file, and the surrounding numbered list uses explicit numbering (10–15), so the directive does not disrupt list continuity.
• The FAQ heading underline (~) length is sufficient for the new question heading.
• Cross-reference text ("step 15 of Configure SAML Sign-On for Mattermost" and "step 9 of the Set up an enterprise app for Mattermost SSO in Entra ID section") matches the actual headings and step numbering in the file.
• The SAML-tracer external link target is identical in both files.

Verification gap: I did not independently confirm the exact server log string "<attribute> attribute is missing" against the Mattermost server source; the PR description attributes it to a specific support ticket, which is reasonable.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR enhances Mattermost's SAML authentication documentation by adding detailed guidance on claim name matching. The Entra ID configuration guide now explains namespace handling and provides troubleshooting steps, while the Mattermost setup instructions emphasize exact claim name alignment. A new FAQ section addresses common SAML login failures caused by attribute mismatches.

Changes

SAML Claim Name Matching Guidance

Layer / File(s)	Summary
Entra ID configuration and Mattermost setup guidance source/administration-guide/onboard/sso-saml-entraid.rst	Entra ID guide now includes a detailed explanation of Mattermost's exact full claim-name matching requirement (including namespaces), Entra's default namespace behaviour, two supported approaches to align namespaces, and guidance to decode the SAML response for confirmation. Mattermost SAML 2.0 configuration instructions are updated to explicitly require exact claim name matches and cross-reference the expanded guidance.
SAML login failure troubleshooting FAQ source/administration-guide/onboard/sso-saml-faq.rst	New FAQ subsection explains why SAML login fails with attribute errors, clarifies Mattermost's exact Name/FriendlyName matching behaviour, provides a namespace mismatch example with Entra ID, and outlines resolution steps: capture and decode the SAML response, then align Mattermost configuration or reconfigure the IdP to emit short claim names.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main objective of the changes: clarifying how Entra ID SAML attribute namespace matching works in Mattermost configuration.
Description check	✅ Passed	The description provides comprehensive context about the SAML attribute namespace matching issue, explains the specific problem users face, and details the changes made to both documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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 docs/saml-entraid-attribute-namespace

---

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]

🧹 Nitpick comments (1)

source/administration-guide/onboard/sso-saml-faq.rst (1)

42-46: ⚡ Quick win

Use numbered steps for the resolution procedure.

This is an actionable procedure; numbering improves run order and novice readability.

Suggested minimal diff

 To resolve this:
 
-- Capture and decode the SAML response (for example, with the `SAML-tracer <https://addons.mozilla.org/firefox/addon/saml-tracer/>`__ browser extension) and read the ``Name`` attribute of each ``<Attribute>`` element in the ``<AttributeStatement>``.
-- Set each Mattermost attribute field to the **exact** ``Name`` value from the assertion — including any namespace prefix — or reconfigure the IdP to emit the claim under the short name you want to use in Mattermost.
+1. Capture and decode the SAML response (for example, with the `SAML-tracer <https://addons.mozilla.org/firefox/addon/saml-tracer/>`__ browser extension) and read the ``Name`` attribute of each ``<Attribute>`` element in the ``<AttributeStatement>``.
+2. Set each Mattermost attribute field to the **exact** ``Name`` value from the assertion — including any namespace prefix — or reconfigure the IdP to emit the claim under the short name you want to use in Mattermost.

As per coding guidelines: "Use numbered, atomic steps (one action per step) when providing procedural instructions".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@source/administration-guide/onboard/sso-saml-faq.rst` around lines 42 - 46,
The procedure is currently an unnumbered bullet list; convert it into numbered,
atomic steps so each action is a separate step and order is clear: 1) Capture
and decode the SAML response (e.g., using the SAML-tracer browser extension) 2)
Inspect each <Attribute> element inside the <AttributeStatement> and read the
Name attribute value 3) For each Mattermost attribute field, set it to the exact
Name value (including any namespace prefix) from the assertion 4) Alternatively,
reconfigure the IdP to emit the claim under the short name you want to use in
Mattermost; ensure each step references the exact symbols (<Attribute>,
<AttributeStatement>, Name, Mattermost attribute field, IdP, SAML-tracer) so
reviewers can locate and verify the changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@source/administration-guide/onboard/sso-saml-faq.rst`:
- Around line 42-46: The procedure is currently an unnumbered bullet list;
convert it into numbered, atomic steps so each action is a separate step and
order is clear: 1) Capture and decode the SAML response (e.g., using the
SAML-tracer browser extension) 2) Inspect each <Attribute> element inside the
<AttributeStatement> and read the Name attribute value 3) For each Mattermost
attribute field, set it to the exact Name value (including any namespace prefix)
from the assertion 4) Alternatively, reconfigure the IdP to emit the claim under
the short name you want to use in Mattermost; ensure each step references the
exact symbols (<Attribute>, <AttributeStatement>, Name, Mattermost attribute
field, IdP, SAML-tracer) so reviewers can locate and verify the changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d44e9a0d-106a-4d9c-a5a7-87d7513f2baf

📥 Commits

Reviewing files that changed from the base of the PR and between eead1da and 0d3ece8.

📒 Files selected for processing (2)

• source/administration-guide/onboard/sso-saml-entraid.rst
• source/administration-guide/onboard/sso-saml-faq.rst

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 0d3ece8