|
| 1 | +Configure SAML with Microsoft Entra ID |
| 2 | +======================================== |
| 3 | + |
| 4 | +.. note:: |
| 5 | + |
| 6 | + This documentation covers configuring Entra ID for **SAML** authentication. If you need to configure Entra ID for **OpenID Connect** authentication instead, see the :doc:`Entra ID Single Sign-On </administration-guide/onboard/sso-entraid>` documentation. |
| 7 | + |
| 8 | +The following process provides steps to configure SAML with Microsoft Entra ID for Mattermost. |
| 9 | + |
| 10 | +See the encryption options documentation for details on what :ref:`encryption methods <deployment-guide/encryption-options:saml encryption support>` Mattermost supports for SAML. |
| 11 | + |
| 12 | +.. include:: sso-saml-before-you-begin.rst |
| 13 | + :start-after: :nosearch: |
| 14 | + |
| 15 | +Prerequisites |
| 16 | +------------- |
| 17 | + |
| 18 | +* A Microsoft Entra tenant containing applicable user data. |
| 19 | +* 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. |
| 20 | +* A Microsoft Entra ID P1 or P2 license. |
| 21 | + |
| 22 | +Set up an enterprise app for Mattermost SSO in Entra ID |
| 23 | +-------------------------------------------------------- |
| 24 | + |
| 25 | +1. Log into the Microsoft Azure portal and select the **Microsoft Entra ID** service. |
| 26 | +2. In the left menu, select **Manage > Enterprise applications**. |
| 27 | +3. Select the **New application** button. |
| 28 | +4. In the **Search application** field, search for **Microsoft Entra SAML Toolkit** and select **Microsoft Entra SAML Toolkit**. |
| 29 | +5. In the **Name** field, enter **Mattermost SAML** then select the **Create** button. |
| 30 | +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**. |
| 31 | +7. In the **Mattermost SAML** enterprise application settings, select **Manage > Single sign-on** then select **SAML** under **Select a single sign-on method**. |
| 32 | +8. Select **Edit** in the **Basic SAML Configuration section** then set the below fields then select **Save**: |
| 33 | + |
| 34 | + - **Identity (Entity ID)**: ``https://<your-mattermost-url>`` |
| 35 | + - **Reply URL (Assertion Consumer Service URL)**: ``https://<your-mattermost-url>/login/sso/saml`` |
| 36 | + - **Sign on URL**: ``https://<your-mattermost-url>/login`` |
| 37 | + |
| 38 | +9. Select **Edit** in the **Attributes & Claims** section then set the below attributes: |
| 39 | + |
| 40 | + 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. |
| 41 | + 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. |
| 42 | + |
| 43 | +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**. |
| 44 | +11. Select the **Certificate (Base64)** Download link in the **SAML Certificates** section. This is the **Identity Provider Public Certificate** to be uploaded to Mattermost. |
| 45 | +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**. |
| 46 | +13. Select the ``...`` to the right of the imported certificate details, select **Activate token encryption certificate**, then select **Yes** to activate. |
| 47 | +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. |
| 48 | +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. |
| 49 | + |
| 50 | +Configure SAML Sign-On for Mattermost |
| 51 | +-------------------------------------- |
| 52 | + |
| 53 | +1. In the Mattermost **System Console**, select **Authentication > SAML 2.0**. |
| 54 | +2. Set **Enable Login With SAML 2.0** to **True**. |
| 55 | +3. Set **Identity Provider Metadata URL**: ``https://login.microsoftonline.com/<your-tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<your-app-id>`` |
| 56 | +4. Select **Get SAML Metadata From IdP** to verify that the SAML metadata can be retrieved successfully. |
| 57 | +5. Set **SAML SSO URL**: ``https://login.microsoftonline.com/<your-tenant-id>/saml2`` |
| 58 | +6. Set **Identity Provider Issuer URL** (trailing slash is required): ``https://sts.windows.net/<your-tenant-id>/`` |
| 59 | +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. |
| 60 | +8. Set **Verify Signature** to **True**. |
| 61 | +9. Set **Service Provider Login URL**: ``https://<your-mattermost-url>/login/sso/saml`` |
| 62 | +10. Set **Service Provider Identifier**: ``https://<your-mattermost-url>`` |
| 63 | +11. Set **Enable Encryption** to **True** |
| 64 | +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. |
| 65 | +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. |
| 66 | +14. Set **Sign Request** to suit your environment. The **Signature Algorithm** must match the algorithm set in Entra ID (**RSAwithSHA256** is recommended). |
| 67 | + |
| 68 | +.. note:: |
| 69 | + |
| 70 | + 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. |
| 71 | + |
| 72 | +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. |
| 73 | +16. Set the **Login Button Text** to suit your environment. |
| 74 | +17. Select the **Save** button. |
| 75 | + |
| 76 | +.. include:: sso-saml-ldapsync.rst |
| 77 | + :start-after: :nosearch: |
| 78 | + |
| 79 | +.. include:: sso-saml-faq.rst |
| 80 | + :start-after: :nosearch: |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments