Skip to content

Enhance SAML configuration instructions for Mattermost #8914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
svelle wants to merge 17 commits into
base: master
Choose a base branch
from
+195 −27
Open

Enhance SAML configuration instructions for Mattermost #8914

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
d340aa0
Enhance SAML configuration instructions for Mattermost
svelle Apr 20, 2026
83d5fed
Update sso-saml-entraid.rst
svelle Apr 20, 2026
201af0c
Update sso-saml-entraid.rst
svelle Apr 21, 2026
a09e76c
Update sso-saml-entraid.rst
svelle Apr 21, 2026
252f318
Add image for Tenant ID location in Entra
svelle Apr 21, 2026
8010315
Add files via upload
svelle Apr 21, 2026
ee1196f
Fix formatting of image attributes in SSO SAML guide
svelle Apr 21, 2026
40d6d50
Merge branch 'master' into svelle-patch-1
svelle Apr 21, 2026
d2b8e2b
Update source/administration-guide/onboard/sso-saml-entraid.rst
svelle Apr 21, 2026
7f0d3f8
Update source/administration-guide/onboard/sso-saml-entraid.rst
svelle Apr 21, 2026
99c7757
Update source/administration-guide/onboard/sso-saml-entraid.rst
svelle Apr 21, 2026
9c215f5
Update source/administration-guide/onboard/sso-saml-entraid.rst
svelle Apr 21, 2026
93e4446
Update source/administration-guide/onboard/sso-saml-entraid.rst
svelle Apr 21, 2026
64ba8a1
Add files via upload
svelle Apr 21, 2026
26cdcb7
Add SAML configuration prerequisites and certificate script
svelle Apr 21, 2026
35dc2c3
Refactor SAML certificate generation instructions
svelle Apr 21, 2026
f772802
Update source/administration-guide/onboard/sso-saml-entraid.rst
svelle Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 92 additions & 25 deletions source/administration-guide/onboard/sso-saml-entraid.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,34 +20,101 @@ Prerequisites
* A Microsoft Entra tenant containing applicable user data.
* A verified custom domain for your tenant. See Microsoft's `Add your custom domain name to your tenant <https://learn.microsoft.com/en-us/entra/fundamentals/add-custom-domain>`__ documentation for details.
* A Microsoft Entra ID P1 or P2 license.
* An account with at least the **Application Administrator** role in your Entra tenant.

Set up an enterprise app for Mattermost SSO in Entra ID
--------------------------------------------------------

1. Log into the Microsoft Azure portal and select the **Microsoft Entra ID** service.
2. In the left menu, select **Manage > Enterprise applications**.
3. Select the **New application** button.
4. In the **Search application** field, search for **Microsoft Entra SAML Toolkit** and select **Microsoft Entra SAML Toolkit**.
5. In the **Name** field, enter **Mattermost SAML** then select the **Create** button.
6. In the **Mattermost SAML** enterprise application settings, select **Manage > Users and Groups** to assign users and/or groups to the application **or** select **Manage > Properties** then set **Assignment required?** to **No** then select **Save**.
7. In the **Mattermost SAML** enterprise application settings, select **Manage > Single sign-on** then select **SAML** under **Select a single sign-on method**.
8. Select **Edit** in the **Basic SAML Configuration section** then set the below fields then select **Save**:
1. Sign in to the `Microsoft Entra admin center <https://entra.microsoft.com>`__ with an account that has at least the **Application Administrator** role.
2. In the left navigation menu, select **Entra ID > Enterprise applications**.
3. Select **+ New application**.
4. Select **+ Create your own application**.
5. In the **What's the name of your app?** field, enter **Mattermost**.
6. Under **What are you looking to do with your application?**, select **Integrate any other application you don't find in the gallery (Non-gallery)**.
7. Select **Create**. Entra provisions the application; this may take a few seconds.
8. In the **Mattermost** enterprise application settings, select **Manage > Users and groups** to assign users and/or groups to the application, **or** select **Manage > Properties**, set **Assignment required?** to **No**, then select **Save**.
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Persona: Novice Nate | Severity: Blocker

Quoted text: “set Assignment required? to No”

Why it matters: Setting Assignment required? to No can allow any user in the Entra tenant to sign in to the application (depending on other access controls), which is a meaningful security/operational change. Readers may follow this without realizing the access scope implications.

Suggestion: Add a brief note calling out the tradeoff (recommended: keep assignment required and explicitly assign users/groups; only set it to No if you intentionally want broad access).

Suggested change
8. In the **Mattermost** enterprise application settings, select **Manage > Users and groups** to assign users and/or groups to the application, **or** select **Manage > Properties**, set **Assignment required?** to **No**, then select **Save**.
8. In the **Mattermost** enterprise application settings, select **Manage > Users and groups** to assign users and/or groups to the application. This is the recommended option because it limits access to explicitly assigned users and groups. If you intentionally want broader access, you can instead select **Manage > Properties**, set **Assignment required?** to **No**, then select **Save**. Depending on your other access controls, this can allow any user in your Entra tenant to sign in to the application.

Copilot uses AI. Check for mistakes.
9. In the **Mattermost** enterprise application settings, select **Manage > Single sign-on**, then select **SAML** under **Select a single sign-on method**.
10. Select **Edit** in the **Basic SAML Configuration** section, then set the fields below and select **Save**:

- **Identity (Entity ID)**: ``https://<your-mattermost-url>``
- **Reply URL (Assertion Consumer Service URL)**: ``https://<your-mattermost-url>/login/sso/saml``
- **Sign on URL**: ``https://<your-mattermost-url>/login``
- **Identifier (Entity ID)**: ``https://<your-mattermost-url>``
- **Reply URL (Assertion Consumer Service URL)**: ``https://<your-mattermost-url>/login/sso/saml``
- **Sign on URL**: ``https://<your-mattermost-url>/login``

9. Select **Edit** in the **Attributes & Claims** section then set the below attributes:
11. Select **Edit** in the **Attributes & Claims** section, then configure the required claim and additional claims as described below.

a. Set the the **Unique User Identifier (Name ID)** required claim **Name identifier format** and **Source attribute** values as required for your environment. Setting the **Source attribute** to an immutable value such as ``user.objectid`` is recommended.
b. Edit claim names and namespaces under **Additional claims** to match SAML attribute settings you wish to set in Mattermost. Configurable settings are Email, Username, Id, Guest, Admin, First Name, Last Name, Nickname, Position, and Preferred Language.
**How Entra claims map to Mattermost**

10. Select **Edit** in the **SAML Certificates** section. Select **Sign SAML response and assertion** for **Signing Option** and **SHA-256** for **Signing Algorithm** then select **Save**.
11. Select the **Certificate (Base64)** Download link in the **SAML Certificates** section. This is the **Identity Provider Public Certificate** to be uploaded to Mattermost.
12. In the **Mattermost SAML** enterprise application settings, select **Security > Token encryption**. Select **Import Certificate** to import the Service Provider certificate. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.crt`` file. The Import dialog says to upload a certificate with a file extension ``.cer``, but ``.crt`` files are also accepted. Upload the file then select **Add**.
13. Select the ``...`` to the right of the imported certificate details, select **Activate token encryption certificate**, then select **Yes** to activate.
14. On the **Home** page for **Microsoft Entra ID**, select the **Overview** link in the left navigation menu and copy the **Tenant ID** value. The **Tenant ID** will be used in Mattermost **SAML 2.0** URL settings.
15. In the left navigation menu, select **Manage > Enterprise applications**. Select the **Mattermost SAML** application then copy the **Application ID**. The **Application ID** will be used in the **Identity Provider Metadata URL** setting in the Mattermost **SAML 2.0** settings.
The SAML assertion Entra sends to Mattermost contains a set of *claims* — name/value pairs describing the user. Mattermost reads these claims based on the attribute names you configure in **System Console > Authentication > SAML 2.0 > Attributes** (for example, **Email Attribute**, **Username Attribute**, **First Name Attribute**).

The **Claim name** you set in Entra must match the value you enter in the corresponding Mattermost attribute field exactly, character for character. The **Value** (also called **Source attribute**) tells Entra which user property to send — for example, ``user.mail`` sends the user's email address.

a. **Required claim — Unique User Identifier (Name ID)**

Set the **Name identifier format** and **Source attribute** values as required for your environment. Setting the **Source attribute** to an immutable value such as ``user.objectid`` is recommended, because unlike email addresses or usernames, the object ID never changes even if the user is renamed. ``user.userprincipalname`` is also a common choice when a human-readable identifier is preferred, with the trade-off that renames in Entra can orphan the corresponding Mattermost account. Mattermost uses the Name ID as the user's unique identifier by default, so you do not need to add a separate ``Id`` claim under **Additional claims**.
Comment thread
svelle marked this conversation as resolved.
Outdated

b. **Additional claims**

By default, Entra populates this section with four claims using the ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/...`` namespace. These work, but we recommend replacing them with short, readable names that match the attribute fields in Mattermost. To edit a claim, select it, update the **Name** field (and clear the **Namespace** field), then save.

The following claim configuration covers a typical Mattermost setup:

.. list-table::
:header-rows: 1
:widths: 30 25 45

* - Mattermost attribute field
- Entra claim name
- Entra source attribute
* - Id Attribute
- *(leave blank)*
- ``user.objectid`` (via Name ID)
Comment thread
svelle marked this conversation as resolved.
Outdated
* - Email Attribute
- ``email``
- ``user.mail``
* - Username Attribute
- ``username``
- ``user.mailnickname``
* - First Name Attribute
- ``firstname``
- ``user.givenname``
* - Last Name Attribute
- ``lastname``
- ``user.surname``
* - Position Attribute
- ``role``
Comment thread
svelle marked this conversation as resolved.
Outdated
- ``user.jobtitle``

.. note::
Use ``user.mailnickname`` rather than ``user.userprincipalname`` as the source for the username claim. The user principal name is typically formatted as an email address (``user@domain.com``), but Mattermost usernames cannot contain the ``@`` character, so SAML logins using ``user.userprincipalname`` will fail. The mail nickname is the local part of the email address (the portion before ``@``) and maps cleanly to a valid Mattermost username.
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Persona: Editor Evie | Severity: Friction

Quoted text: “Mattermost usernames cannot contain the @ character”

Why it matters: This is an important constraint that affects whether the recommended claim mapping will work. Adding a supporting reference (or a quick pointer to where the username rules are documented) increases reader confidence and reduces ambiguity.

Suggestion: Link to the existing username requirements (for example, the profile documentation that lists allowed username characters) right after this sentence, or rephrase to explicitly align with that documented rule set (letters/numbers plus ., -, _).

Suggested change
Use ``user.mailnickname`` rather than ``user.userprincipalname`` as the source for the username claim. The user principal name is typically formatted as an email address (``user@domain.com``), but Mattermost usernames cannot contain the ``@`` character, so SAML logins using ``user.userprincipalname`` will fail. The mail nickname is the local part of the email address (the portion before ``@``) and maps cleanly to a valid Mattermost username.
Use ``user.mailnickname`` rather than ``user.userprincipalname`` as the source for the username claim. The user principal name is typically formatted as an email address (``user@domain.com``), but Mattermost usernames can contain only letters, numbers, and ``.``, ``-``, or ``_`` characters, so SAML logins using ``user.userprincipalname`` will fail. The mail nickname is the local part of the email address (the portion before ``@``) and maps cleanly to a valid Mattermost username.

Copilot uses AI. Check for mistakes.

If your organization doesn't populate ``mailnickname`` consistently, another option is a custom Entra attribute or a transformation that strips the domain from the UPN.
Comment on lines +188 to +191
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use a warning admonition for the username-claim failure case.

This block describes a likely misconfiguration that causes SAML login failure. It should be .. warning:: rather than .. note::.

Suggested minimal diff 
-       .. note::
+       .. warning::

As per coding guidelines: “Use warning admonition for meaningful risk such as broken behavior … or likely user/admin mistakes with negative consequences.”

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@source/administration-guide/onboard/sso-saml-entraid.rst` around lines 188 -
191, Replace the current note admonition with a warning admonition so the SAML
username-claim guidance is shown as a risk (change the RST block that starts
with ".. note::" and contains the lines referencing "user.mailnickname",
"user.userprincipalname" and "mailnickname" to use ".. warning::" instead);
ensure the block content remains identical besides the admonition type so the
explanation about using mailnickname (and the fallback option for custom Entra
attribute or UPN transformation) is preserved under the warning.

Comment on lines +188 to +191
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Novice Nate (Friction): The note explains that Mattermost usernames can’t contain “@”, but Mattermost usernames also have other constraints (must start with a letter, 3–22 lowercase chars, only . - _ as symbols). user.mailnickname can be empty/inconsistent, contain uppercase, or be too short/long, which can still cause SAML sign-in failures even without “@”. Suggest expanding this note to include the full username constraints and recommending a claim transformation to lowercase/validate length (or using a dedicated custom attribute) when mailnickname doesn’t conform.

Copilot uses AI. Check for mistakes.

After editing, your **Attributes & Claims** page should look similar to the screenshot below:

.. image:: ../../images/entra-attributes-and-claims.png
:alt: Entra Attributes & Claims page showing simplified claim names
:width: 100%

The **Guest**, **Admin**, **Nickname**, and **Preferred Language** attributes are also configurable in Mattermost if you want to drive them from Entra. Use the same pattern: pick a short claim name in Entra, set its source attribute, and enter the matching claim name in the corresponding Mattermost attribute field.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for SAML attribute configuration documentation
rg -n -C5 'Guest.*Attribute|Admin.*Attribute|Nickname.*Attribute|Preferred.*Language.*Attribute' source/ --type rst -g '!onboard/sso-saml-entraid.rst'

Repository: mattermost/docs

Length of output: 35455

🏁 Script executed:

# Search for Locale attribute in SAML configuration
rg -n 'locale.*attribute|Locale.*Attribute' source/administration-guide/configure/authentication-configuration-settings.rst -i -A 5 -B 2

Repository: mattermost/docs

Length of output: 1808

🏁 Script executed:

# Check the exact context in the file being reviewed
cat -n source/administration-guide/onboard/sso-saml-entraid.rst | sed -n '190,210p'

Repository: mattermost/docs

Length of output: 2613

Update terminology to match official Mattermost SAML documentation.

Line 199 mentions "Preferred Language attributes" but the official System Console setting is labeled "Preferred language attribute" in the SAML 2.0 authentication configuration. All four attributes (Guest, Admin, Nickname, and Preferred language) are valid and configurable in Mattermost, so the guidance is sound—update the capitalization to "Preferred language attribute" for consistency with the official UI label.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@source/administration-guide/onboard/sso-saml-entraid.rst` at line 199, Update
the UI wording in the sentence that lists configurable SAML attributes: replace
the phrase "Preferred Language" with the exact System Console label "Preferred
language attribute" so the sentence reads "... Guest, Admin, Nickname, and
Preferred language attribute ..." to match Mattermost's official SAML 2.0
authentication configuration terminology.


12. Select **Edit** in the **SAML Certificates** section. Select **Sign SAML response and assertion** for **Signing Option** and **SHA-256** for **Signing Algorithm**, then select **Save**.
13. Select the **Certificate (Base64)** Download link in the **SAML Certificates** section. This is the **Identity Provider Public Certificate** to be uploaded to Mattermost.
14. In the **Mattermost** enterprise application settings, select **Security > Token encryption**. Select **Import Certificate** to import the Service Provider certificate. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.crt`` file. The Import dialog says to upload a certificate with a file extension ``.cer``, but ``.crt`` files are also accepted. Upload the file then select **Add**.
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Veteran Vince (Friction): “The Import dialog says to upload a certificate with a file extension .cer, but .crt files are also accepted.” is a behavioral claim that may not hold in all Entra tenants/UX variants. To avoid a dead-end for admins, suggest wording this more defensively (e.g., “If Entra rejects .crt, rename/convert the file to .cer and try again”).

Suggested change
14. In the **Mattermost** enterprise application settings, select **Security > Token encryption**. Select **Import Certificate** to import the Service Provider certificate. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.crt`` file. The Import dialog says to upload a certificate with a file extension ``.cer``, but ``.crt`` files are also accepted. Upload the file then select **Add**.
14. In the **Mattermost** enterprise application settings, select **Security > Token encryption**. Select **Import Certificate** to import the Service Provider certificate. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.crt`` file. If Entra accepts the ``.crt`` file, upload it and select **Add**. If Entra rejects it because it expects a ``.cer`` file, rename or convert the certificate to ``.cer`` and try again.

Copilot uses AI. Check for mistakes.
15. Select the ``...`` to the right of the imported certificate details, select **Activate token encryption certificate**, then select **Yes** to activate.
16. Copy the **Tenant ID** for use in the Mattermost **SAML 2.0** URL settings.

.. note::
Entra exposes three different GUIDs during this setup, and it's easy to confuse them. The **Tenant ID** identifies your entire Entra directory, while the **Application ID** and **Object ID** (visible on the enterprise application's **Properties** page) identify the Mattermost SAML application within that directory. Mattermost uses the Tenant ID and Application ID; the Object ID is not used.

To find the Tenant ID, select **Entra ID** from the admin center home, then locate the **Tenant ID** value in the **Basic information** panel on the **Overview** page.

.. image:: ../../images/entra-tenant-id.png
:alt: Where to find the Tenant ID
Comment thread
svelle marked this conversation as resolved.
Outdated
:width: 100%

17. Copy the **Application ID** for use in the **Identity Provider Metadata URL** setting in the Mattermost **SAML 2.0** settings.

To find the Application ID, select **Entra ID > Enterprise applications** from the left navigation menu, select the **Mattermost** application, then copy the **Application ID** from the **Properties** page (shown alongside the Object ID, which is not needed).

Configure SAML Sign-On for Mattermost
--------------------------------------
Expand All @@ -58,25 +125,25 @@ Configure SAML Sign-On for Mattermost
4. Select **Get SAML Metadata From IdP** to verify that the SAML metadata can be retrieved successfully.
5. Set **SAML SSO URL**: ``https://login.microsoftonline.com/<your-tenant-id>/saml2``
6. Set **Identity Provider Issuer URL** (trailing slash is required): ``https://sts.windows.net/<your-tenant-id>/``
7. Choose the **Identity Provider Public Certificate** file from step 11 of **Set up an enterprise app for Mattermost SSO in Entra ID** then upload.
7. Choose the **Identity Provider Public Certificate** file from step 13 of **Set up an enterprise app for Mattermost SSO in Entra ID** then upload.
8. Set **Verify Signature** to **True**.
9. Set **Service Provider Login URL**: ``https://<your-mattermost-url>/login/sso/saml``
10. Set **Service Provider Identifier**: ``https://<your-mattermost-url>``
11. Set **Enable Encryption** to **True**
12. Choose your **Service Provider Private Key** file then upload. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.key`` file.
11. Set **Enable Encryption** to **True**.
12. Choose your **Service Provider Private Key** file then upload. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.key`` file.
13. Choose your **Service Provider Public Certificate** then upload. If you used the Bash script referenced in the **Before you begin** section, this is the ``mattermost-x509.crt`` file.
14. Set **Sign Request** to suit your environment. The **Signature Algorithm** must match the algorithm set in Entra ID (**RSAwithSHA256** is recommended).

.. note::

The **Test single sign-on with Mattermost SAML** tool in Microsoft Entra ID does not sign the request even if **Sign Request** is set to **True** in Mattermost. Depending on your security settings and key length, the Entra ID testing tool may successfully sign in while an actual sign in request from your Mattermost login page results in the error **AADSTS90015: Requested query string is too long.** since Entra ID handles the initial request with an HTTP GET redirect rather than HTTP POST.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

What causes Microsoft Entra ID SAML error AADSTS90015 "Requested query string is too long" and how does request signing affect this?

💡 Result:

The Microsoft Entra ID SAML error AADSTS90015, "Requested query string is too long" (also described officially as "QueryStringTooLong - The query string is too long"), occurs when the incoming authentication request's query string exceeds the 4096-byte limit enforced by Entra ID's HTTP listener input validation. Primary causes in SAML contexts: - Use of HTTP-Redirect binding (GET) for AuthnRequest, where the base64-encoded, deflated SAMLRequest parameter (plus RelayState) becomes oversized. Common when the SAML assertion includes many groups/claims or long parameters. - Signed SAML requests over HTTP-Redirect: Signing adds extra query parameters (Signature and SigAlg), substantially increasing length since the signature is appended to the URL rather than embedded in the body. - Long RelayState values (SAML standard limits to 80 bytes, but apps often exceed this). - Accumulated browser cookies or other query parameters pushing over the limit. Request signing exacerbates this specifically in HTTP-Redirect binding. When the service provider (SP) signs the AuthnRequest: - The signature is not embedded in the SAML XML (as in POST); instead, separate Signature={base64 sig} and SigAlg={algorithm} parameters are added to the query string. - This can add hundreds of bytes, easily exceeding limits on already large requests. Solutions: - Switch to HTTP-POST binding for the AuthnRequest (preferred for signed requests), which sends the SAMLRequest in the POST body (no query string limit issue). Configure in the SP application settings (e.g., vendor UI, web.config). - Disable SAML request signing if not required (Entra ID does not enforce or validate signed incoming AuthnRequests by default). - Shorten RelayState (ask app vendor). - Clear excessive browser cookies for microsoftonline.com domains as a temporary workaround. - Use tools like Fiddler to capture and measure the SAMLRequest query string size. Official Entra ID error reference confirms the description with no additional SAML-specific details. Microsoft Q&A threads from Entra staff provide the most direct SAML guidance.

Citations:

Clarify the AADSTS90015 error mechanism and the role of request signing.

The explanation that Entra ID uses HTTP-Redirect (GET) is correct, but it omits critical context: the error occurs because GET binding places the SAML request and the signature parameters in the query string, which must not exceed 4096 bytes. When you enable signed requests, the Signature and SigAlg parameters are appended to the URL rather than embedded in the body, substantially increasing the query string size. Rewrite to explain that signing amplifies the risk of exceeding Entra ID's query string size limit, and note that switching to HTTP-POST binding avoids this constraint entirely.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@source/administration-guide/onboard/sso-saml-entraid.rst` at line 240, Update
the paragraph that begins "The **Test single sign-on with Mattermost SAML**
tool..." to explicitly state that Entra ID's HTTP-Redirect (GET) binding places
the encoded SAMLRequest and any signature parameters (Signature and SigAlg) into
the URL query string, which can exceed Entra ID's ~4096-byte limit; explain that
enabling "Sign Request" appends Signature and SigAlg to the query string and
therefore increases the risk of hitting AADSTS90015, and add that using
HTTP-POST binding (which embeds the SAML payload and signature in the request
body) avoids this query-string size constraint.


15. Set attribute settings to match attributes configured in step 9 of the **Set up an enterprise app for Mattermost SSO in Entra ID** section.
15. Set attribute settings to match the attributes configured in step 11 of the **Set up an enterprise app for Mattermost SSO in Entra ID** section.
16. Set the **Login Button Text** to suit your environment.
17. Select the **Save** button.

.. include:: sso-saml-ldapsync.rst
:start-after: :nosearch:

.. include:: sso-saml-faq.rst
:start-after: :nosearch:
:start-after: :nosearch:
Comment thread
svelle marked this conversation as resolved.
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Persona: Editor Evie | Severity: Friction

Quoted text/behavior: The :start-after: :nosearch: option under the final .. include:: sso-saml-faq.rst directive is indented with a tab.

Why it matters: Tabs in reStructuredText indentation can lead to inconsistent rendering or Sphinx warnings depending on configuration; spaces are the safer, standard indentation.

Suggestion: Replace the tab indentation with spaces (matching the include option indentation style used elsewhere in the docs).

Suggested change
:start-after: :nosearch:
:start-after: :nosearch:

Copilot uses AI. Check for mistakes.
Comment on lines 246 to +250
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Editor Evie (Polish): The .. include:: option lines at the end of the file are indented with a tab (\t:start-after: ...), while earlier directives in this file use spaces for indentation (e.g., the badges include). Tabs work but tend to cause inconsistent rendering/linting across editors. Suggestion: replace the tabs with consistent two-space indentation for the :start-after: options.

Copilot uses AI. Check for mistakes.
Comment on lines 246 to +250
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Editor Evie (Blocker): The .. include:: option lines at the end of the file are indented with a literal tab (e.g., \t:start-after: :nosearch:). Tabs can render inconsistently and can break Sphinx/reStructuredText directive option parsing in some toolchains. Suggest replacing the tabs with spaces (matching the indentation used earlier in the file for include options).

Copilot uses AI. Check for mistakes.
Binary file added source/images/entra-attributes-and-claims.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/images/entra-tenant-id.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading