Add documentation for configuring SAML with Microsoft Entra ID

[roberson-io]

@claude The documentation does not contain instructions for configuring SAML with Microsoft Entra ID. There should be a new documentation page similar to the pages for other SAML identity providers such as the Okta SAML configuration page, OneLogin SAML configuration page, Keycloak SAML configuration page, etc. The link to this documentation page should appear in the left navigation menu under Administration Guide > Server maintenance > Secure Mattermost > SAML-based SSO like other SAML documentation pages

Below is the content for the new documentation page in Markdown that will need to be converted to reStructuredText:

Configure SAML with Microsoft Entra ID

The following process provides steps to configure SAML with Microsoft Entra ID for Mattermost.

See the encryption options documentation for details on what encryption methods Mattermost supports for SAML.

Before you begin

Before you begin, you need to generate encryption certificates for encrypting the SAML connection.

1. You can use the Bash script from the mattermost/docs repository on GitHub, or any other suitable method. See the generate self-signed certificates documentation for details on generating a self-signed x509v3 certificate for use with multiple URLs / IPs.

2. Save the two files that are generated. They are the private key and the public key. In the System Console, they are referred to as the Service Provider Private Key and the Service Provider Public Certificate respectively.

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 documentation for details.
• A Microsoft Entra ID P1 or P2 license.

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. Click 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 click 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 click Save.
7. In the Mattermost SAML enterprise application settings, select Manage > Single sign-on then click SAML under Select a single sign-on method.
8. Select Edit in the Basic SAML Configuration section then set the below fields then click Save:
   1. Identity (Entity ID): https://<your-mattermost-url>
   2. Reply URL (Assertion Consumer Service URL): https://<your-mattermost-url>/login/sso/saml
   3. Sign on URL: https://<your-mattermost-url>/login
9. Select Edit in the Attributes & Claims section then set the below attributes:
   1. 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.
   2. 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.
10. Select Edit in the SAML Certificates section. Select Sign SAML response and assertion for Signing Option and SHA-256 for Signing Algorithm then click 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 click Add.
13. Click the ... to the right of the imported certificate details, select Activate token encryption certificate, then click 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.

Configure SAML Sign-On for Mattermost

1. In the Mattermost System Console, select Authentication > SAML 2.0.
2. Set Enable Login With SAML 2.0 to True.
3. Set Identity Provider Metadata URL: https://login.microsoftonline.com/<your-tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<your-app-id>
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.
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.
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.
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.
16. Set the Login Button Text to suit your environment.
17. Click the Save button.

[claude]

Claude finished @roberson-io's task —— View job • claude/issue-8449-20251002-1513 • Create PR ➔

---

Adding Microsoft Entra ID SAML Documentation ✅

I've successfully added documentation for configuring SAML with Microsoft Entra ID to the Mattermost documentation.

Completed Tasks:

• Read repository guidelines (CLAUDE.md)
• Explore documentation structure and locate existing SAML documentation
• Examine existing SAML provider documentation for formatting patterns
• Convert Markdown content to reStructuredText format
• Create new Microsoft Entra ID SAML documentation file
• Update navigation/index files to include the new page
• Commit and push changes
• Provide PR creation link

Summary of Changes:

1. Created new documentation file: source/administration-guide/onboard/sso-saml-entraid.rst

   • Converted the provided Markdown content to reStructuredText
   • Followed established patterns from other SAML provider documentation
   • Included all sections: Prerequisites, Entra ID setup, and Mattermost configuration
   • Added proper cross-references and formatting

2. Updated navigation: Modified source/administration-guide/onboard/sso-saml.rst

   • Added "Microsoft Entra ID SAML Configuration" to the toctree
   • Positioned it logically among other Microsoft-related providers

The new documentation page will appear in the left navigation menu under Administration Guide > Server maintenance > Secure Mattermost > SAML-based SSO as requested.

---