diff --git a/source/administration-guide/onboard/sso-saml-entraid.rst b/source/administration-guide/onboard/sso-saml-entraid.rst index 2344db4dd41..79939e44477 100644 --- a/source/administration-guide/onboard/sso-saml-entraid.rst +++ b/source/administration-guide/onboard/sso-saml-entraid.rst @@ -11,8 +11,112 @@ This page provides guidance on configuring SAML with Microsoft Entra ID for Matt - Need to configure Entra ID for **OpenID Connect** authentication instead? See the :doc:`Entra ID Single Sign-On ` documentation for details. - See the encryption options documentation for details on what :ref:`encryption methods ` Mattermost supports for SAML. -.. include:: sso-saml-before-you-begin.rst - :start-after: :nosearch: +Before you begin +---------------- + +Before configuring SAML, you need to generate a private key and self-signed X.509 certificate. These are uploaded to Mattermost as the **Service Provider Private Key** and **Service Provider Public Certificate**, and the certificate is also uploaded to Entra ID for token encryption. + +You can generate these files with any tool that produces a 4096-bit RSA private key and a matching self-signed certificate. The Bash script below is provided as a reference; adapt the variables to your environment before running it. + +The script generates a 4096-bit RSA private key (``mattermost-x509.key``) and a self-signed X.509 certificate (``mattermost-x509.crt``) valid for 10 years. Set the environment variables below before running it — the defaults are placeholders and should not be used in production. + +.. list-table:: + :header-rows: 1 + :widths: 20 50 30 + + * - Variable + - Purpose + - Default + * - ``CRT_FILENAME`` + - Base name for the generated files (``.key``, ``.crt``). + - ``mattermost-x509`` + * - ``CRT_C`` + - Country value (ISO 3166-1 alpha-2 country code). + - ``US`` + * - ``CRT_L`` + - Locality value (city). + - ``Palo Alto`` + * - ``CRT_O`` + - Organization value. + - ``Mattermost`` + * - ``CRT_OU`` + - Organizational Unit value. + - ``DevOps`` + * - ``CRT_CN`` + - Common Name value. You can use any descriptive value for this SAML encryption certificate; it doesn't need to match your Mattermost hostname, though you can use the hostname if you prefer. + - ``base.example.com`` + * - ``CRT_SAN`` + - Subject Alternative Name value. Comma-separated list of DNS names and/or IPs to include in the certificate. For SAML encryption, Mattermost and Entra ID don't require these values to match the Mattermost hostname, though using the hostname is a valid convention. + - ``DNS.1:logs.example.com,DNS.2:metrics.example.com,IP.1:192.168.0.1,IP.2:127.0.0.1`` + +**Example invocation** for a Mattermost server at ``mattermost.example.com``: + +.. code-block:: bash + + CRT_CN="mattermost.example.com" \ + CRT_SAN="DNS.1:mattermost.example.com" \ + CRT_O="Acme Corp" \ + CRT_OU="IT" \ + CRT_C="DE" \ + CRT_L="Berlin" \ + ./gencert.sh + +**The script:** + +.. code-block:: bash + + #!/bin/bash + + umask 007 + + FILE_NAME="${CRT_FILENAME:-"mattermost-x509"}" + CERT="${FILE_NAME}.crt" + KEY="${FILE_NAME}.key" + CSR="${FILE_NAME}.csr" + + # generate key + openssl genrsa -out $KEY 4096 + + if [ $? -ne 0 ]; then + echo "Error generating key" + exit + fi + + # generate certificate signing request + openssl req \ + -new \ + -key $KEY \ + -out $CSR \ + -subj "/C=${CRT_C:-"US"}/L=${CRT_L:-"Palo Alto"}/O=${CRT_O:-"Mattermost"}/OU=${CRT_OU:-"DevOps"}/CN=${CRT_CN:-"base.example.com"}" + + if [ $? -ne 0 ]; then + echo "Error generating certificate signing request (csr)" + exit + fi + + # generate self-signed certificate + openssl x509 \ + -req \ + -days 3650 \ + -in $CSR \ + -signkey $KEY \ + -sha256 \ + -out $CERT \ + -extfile <(echo -e "basicConstraints=critical,CA:true,pathlen:0\nsubjectAltName=${CRT_SAN:-"DNS.1:logs.example.com,DNS.2:metrics.example.com,IP.1:192.168.0.1,IP.2:127.0.0.1"}") + + if [ $? -ne 0 ]; then + echo "Error generating self-signed certificate" + exit + fi + + rm $CSR + chmod 600 $CERT + + echo -e "\nSuccess! $KEY and $CERT generated." + +After the script completes, you'll have ``mattermost-x509.key`` and ``mattermost-x509.crt`` in the current directory. Keep the ``.key`` file secure — it's the private key for your SAML Service Provider identity. For details on verifying the generated certificate or password-protecting the private key, see the :doc:`gencert.sh reference `. + +The ``.key`` is the **Service Provider Private Key** and the ``.crt`` is the **Service Provider Public Certificate** referenced throughout the rest of this guide. Prerequisites ------------- @@ -20,34 +124,98 @@ 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. +* 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 `__ 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**. +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**: + + - **Identifier (Entity ID)**: ``https://`` + - **Reply URL (Assertion Consumer Service URL)**: ``https:///login/sso/saml`` + - **Sign on URL**: ``https:///login`` + +11. Select **Edit** in the **Attributes & Claims** section, then configure the required claim and additional claims as described below. + + **How Entra claims map to Mattermost** + + 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. The Name ID is part of the SAML assertion, but Mattermost account binding is controlled by the **Id Attribute (SAML)** setting if you configure it, or by email otherwise. If you want immutable user binding in Mattermost, add a separate ``Id`` claim under **Additional claims** and set its **Value** (source attribute) to an immutable Entra attribute such as ``user.objectid``. ``user.userprincipalname`` is also a common choice for Name ID when a human-readable identifier is preferred, with the trade-off that renames in Entra can orphan the corresponding Mattermost account if you rely on it for identity matching. + + 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: - - **Identity (Entity ID)**: ``https://`` - - **Reply URL (Assertion Consumer Service URL)**: ``https:///login/sso/saml`` - - **Sign on URL**: ``https:///login`` + .. list-table:: + :header-rows: 1 + :widths: 30 25 45 -9. Select **Edit** in the **Attributes & Claims** section then set the below attributes: + * - Mattermost attribute field + - Entra claim name + - Entra source attribute + * - Email Attribute + - ``email`` + - ``user.mail`` + * - Username Attribute + - ``username`` + - ``user.mailnickname`` + * - First Name Attribute + - ``firstname`` + - ``user.givenname`` + * - Last Name Attribute + - ``lastname`` + - ``user.surname`` + * - Position Attribute + - ``position`` + - ``user.jobtitle`` - 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. + .. 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. -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. + 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. + + 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. + +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**. +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 + :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 -------------------------------------- @@ -58,12 +226,12 @@ 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//saml2`` 6. Set **Identity Provider Issuer URL** (trailing slash is required): ``https://sts.windows.net//`` -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:///login/sso/saml`` 10. Set **Service Provider Identifier**: ``https://`` -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). @@ -71,7 +239,7 @@ Configure SAML Sign-On for Mattermost 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. +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. @@ -79,4 +247,4 @@ Configure SAML Sign-On for Mattermost :start-after: :nosearch: .. include:: sso-saml-faq.rst - :start-after: :nosearch: \ No newline at end of file + :start-after: :nosearch: diff --git a/source/images/entra-attributes-and-claims.png b/source/images/entra-attributes-and-claims.png new file mode 100644 index 00000000000..6bad055debd Binary files /dev/null and b/source/images/entra-attributes-and-claims.png differ diff --git a/source/images/entra-tenant-id.png b/source/images/entra-tenant-id.png new file mode 100644 index 00000000000..8e815e9eec6 Binary files /dev/null and b/source/images/entra-tenant-id.png differ