team/docs/main/administration-guide/onboard/sso-saml-entraid.mdx

---
title: "Configure SAML with Microsoft Entra ID"
---
import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx';
import Inc1_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
import Inc2_sso_saml_faq from './sso-saml-faq.mdx';

<PlanAvailability slug="all-commercial" />

This page provides guidance on configuring SAML with Microsoft Entra ID for Mattermost.

<Tip>

- Need to configure Entra ID for **OpenID Connect** authentication instead? See the [Entra ID Single Sign-On](/administration-guide/onboard/sso-entraid) documentation for details.
- See the encryption options documentation for details on what [encryption methods](/deployment-guide/encryption-options#saml-encryption-support) Mattermost supports for SAML.

</Tip>

<Inc0_sso_saml_before_you_begin />

## 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.

## 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**:

> - **Identity (Entity ID)**: `https://&lt;your-mattermost-url&gt;`
> - **Reply URL (Assertion Consumer Service URL)**: `https://&lt;your-mattermost-url&gt;/login/sso/saml`
> - **Sign on URL**: `https://&lt;your-mattermost-url&gt;/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.

<Important>

Mattermost matches each attribute by its **full claim name**, including the namespace, exactly as it appears in the SAML assertion. By default, Entra ID emits its built-in claims under the namespace `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/` — so the claim that appears in the **Claim name** column as `emailaddress` is actually sent in the assertion as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`.

This means the value you enter in each Mattermost attribute field (step 15 of **Configure SAML Sign-On for Mattermost**, below) must be the **fully-qualified** claim name. Entering only the short name (for example, `email` or `name`) will **not** match, and login will fail with an error such as `SAML login was unsuccessful because one of the attributes is incorrect... <attribute> attribute is missing`.

You have two options:

- **Clear the namespace** on each claim in Entra ID under **Additional claims** so the claim name becomes the short value (for example, `email`), then enter that same short value in Mattermost; **or**
- **Leave the default namespace** in Entra ID and enter the fully-qualified claim name in Mattermost (for example, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`).

Whichever option you choose, the value in Mattermost must match the assertion **character-for-character**. If a login fails, the safest way to confirm the exact claim names being sent is to capture and decode the SAML response from the browser (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.

</Important>

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.

## 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/&lt;your-tenant-id&gt;/federationmetadata/2007-06/federationmetadata.xml?appid=&lt;your-app-id&gt;`
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/&lt;your-tenant-id&gt;/saml2`
6.  Set **Identity Provider Issuer URL** (trailing slash is required): `https://sts.windows.net/&lt;your-tenant-id&gt;/`
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://&lt;your-mattermost-url&gt;/login/sso/saml`
10. Set **Service Provider Identifier**: `https://&lt;your-mattermost-url&gt;`
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.

</Note>

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. Each value must match the **full claim name** sent in the assertion, including the namespace, exactly. See the **important** note under step 9 for details and a common failure mode.
16. Set the **Login Button Text** to suit your environment.
17. Select the **Save** button.

<Inc1_sso_saml_ldapsync />

<Inc2_sso_saml_faq />
 :start-after: :nosearch: