diff --git a/source/administration-guide/onboard/sso-saml-entraid.rst b/source/administration-guide/onboard/sso-saml-entraid.rst new file mode 100644 index 00000000000..87b6b36b800 --- /dev/null +++ b/source/administration-guide/onboard/sso-saml-entraid.rst @@ -0,0 +1,76 @@ +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 :ref:`encryption methods ` Mattermost supports for SAML. + +.. include:: sso-saml-before-you-begin.rst + :start-after: :nosearch: + +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. 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://`` + - **Reply URL (Assertion Consumer Service URL)**: ``https:///login/sso/saml`` + - **Sign on URL**: ``https:///login`` + +9. Select **Edit** in the **Attributes & Claims** section then set the below attributes: + + 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. + +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//federationmetadata/2007-06/federationmetadata.xml?appid=`` +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. +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. +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. Select the **Save** button. + +.. include:: sso-saml-ldapsync.rst + :start-after: :nosearch: + +.. include:: sso-saml-faq.rst + :start-after: :nosearch: \ No newline at end of file diff --git a/source/administration-guide/onboard/sso-saml-ldapsync.rst b/source/administration-guide/onboard/sso-saml-ldapsync.rst index f4efe2b692f..5d2846122b2 100644 --- a/source/administration-guide/onboard/sso-saml-ldapsync.rst +++ b/source/administration-guide/onboard/sso-saml-ldapsync.rst @@ -6,8 +6,8 @@ Configure SAML synchronization with AD/LDAP In addition to configuring SAML sign-in, you can optionally configure synchronizing SAML accounts with AD/LDAP. When configured: - - Mattermost queries AD/LDAP for relevant account information and updates SAML accounts based on changes to attributes (first name, last name, and nickname) - - Accounts disabled in AD/LDAP are deactivated in Mattermost, and their active sessions are revoked once Mattermost synchronizes attributes. +- Mattermost queries AD/LDAP for relevant account information and updates SAML accounts based on changes to attributes (first name, last name, and nickname) +- Accounts disabled in AD/LDAP are deactivated in Mattermost, and their active sessions are revoked once Mattermost synchronizes attributes. To configure SAML synchronization with AD/LDAP: @@ -16,7 +16,7 @@ To configure SAML synchronization with AD/LDAP: 3. To ignore guest users when sychronizing, go to **System Console > Authentication > SAML 2.0**, then set **Ignore Guest Users when Synchronizing with AD/LDAP** to **true**. 4. Set the rest of the AD/LDAP settings based on :ref:`configuration settings documentation ` to connect Mattermost with your AD/LDAP server. - - If you don't want to enable AD/LDAP sign-in, go to **System Console > Authentication > AD/LDAP** wizard, navigate to the **Connection Settings** section, then set **Enable sign-in with AD/LDAP** to **false**. + If you don't want to enable AD/LDAP sign-in, go to **System Console > Authentication > AD/LDAP** wizard, navigate to the **Connection Settings** section, then set **Enable sign-in with AD/LDAP** to **false**. 5. To specify how often Mattermost synchronizes SAML user accounts with AD/LDAP, go to **System Console > Authentication > AD/LDAP** wizard, navigate to the **Sync Performance** section, then set a **Synchronization Interval** in minutes. The default setting is 60 minutes. If you want to synchronize immediately after disabling an account, go to the **Sync History** section and select **AD/LDAP Synchronize Now**. 6. To confirm that Mattermost can successfully connect to your AD/LDAP server, go to **System Console > Authentication > AD/LDAP** wizard, navigate to the **Connection Settings** section, then select **Test Connection**. @@ -30,15 +30,10 @@ To re-activate the account: 3. Run AD/LDAP synchronization by going to **System Console > Authentication > AD/LDAP** wizard, navigating to the **Sync History** section, then select **AD/LDAP Synchronize Now**. 4. Purge all caches again in Mattermost by going to **System Console > Environment > Web Server**, then select **Purge All Caches** again. This re-activates the account in Mattermost. - .. note:: - If a user is deactivated from AD/LDAP, they will be deactivated in Mattermost on the next sync. They will be shown as "Deactivated" in the System Console users list, all of their sessions will expire and they won't be able to log back in to Mattermost. - - If a user is deactivated from SAML, their session won't expire until they're deactivated from AD/LDAP. However, they won't be able to log back in to Mattermost. - - .. note:: - SAML synchronization with AD/LDAP is designed to pull user attributes such as first name and last name from your AD/LDAP, not to control authentication. - - In particular, the user filter cannot be used to control who can log in to Mattermost, this should be controlled by your SAML service provider's group permissions. +.. note:: + - If a user is deactivated from AD/LDAP, they will be deactivated in Mattermost on the next sync. They will be shown as "Deactivated" in the System Console users list, all of their sessions will expire and they won't be able to log back in to Mattermost. + - If a user is deactivated from SAML, their session won't expire until they're deactivated from AD/LDAP. However, they won't be able to log back in to Mattermost. + - SAML synchronization with AD/LDAP is designed to pull user attributes such as first name and last name from your AD/LDAP, not to control authentication. In particular, the user filter cannot be used to control who can log in to Mattermost, this should be controlled by your SAML service provider's group permissions. See :ref:`technical description of SAML synchronization with AD/LDAP ` for more details. diff --git a/source/administration-guide/onboard/sso-saml.rst b/source/administration-guide/onboard/sso-saml.rst index c13bef3bc91..fae91df2529 100644 --- a/source/administration-guide/onboard/sso-saml.rst +++ b/source/administration-guide/onboard/sso-saml.rst @@ -38,6 +38,7 @@ The SAML Single sign-on integration offers the following benefits: OneLogin SAML Configuration Microsoft ADFS SAML Configuration for Windows Server 2012 Microsoft ADFS SAML Configuration for Windows Server 2016 + Microsoft Entra ID SAML Configuration Keycloak SAML Configuration Using SAML attributes to apply roles