mirror of
https://github.com/hanzoai/team.git
synced 2026-10-30 14:49:35 +00:00
b07a9836ba
* docs(P13e): reconcile drift for Administration Guide onboard/upgrade/comply pages Ports content changes made in the legacy Sphinx docs repo since the P13 migration fork point (2026-05-14) into the corresponding MDX pages: SAML/SSO Entra ID namespace-matching guidance, granular permissions updates, upgrade notes for v11.7/v11.8, OSS component list, and minor typo/link fixes across onboard, upgrade, and comply sections. * docs(P13e): fix MDX compile failure from blank lines inside <pre><code> blocks Blank lines inside JSX <pre><code> blocks are parsed as paragraph boundaries by MDX, breaking the enclosing tag matching. Remove the blank lines used for SQL readability while keeping each statement on its own line. * docs(P13e): fix insecure curl example and legacy absolute doc link - electronic-discovery.mdx: use https for the authenticated curl example, matching the other curl examples in the same page. - important-upgrade-notes.mdx: point the Deprecated Features reference at the local route instead of the legacy docs.mattermost.com URL. --------- Co-authored-by: Hanzo Dev <[email protected]>
108 lines
6.9 KiB
Plaintext
108 lines
6.9 KiB
Plaintext
---
|
||
title: "Entra ID Single Sign-On"
|
||
---
|
||
<PlanAvailability slug="all-commercial" />
|
||
|
||
## Configuring EntraID as a Single Sign-On (SSO) service
|
||
|
||
<Note>
|
||
|
||
- This documentation covers configuring Entra ID for **OpenID Connect** authentication. If you need to configure Entra ID for **SAML** authentication instead, see the [Configure SAML with Microsoft Entra ID](/administration-guide/onboard/sso-saml-entraid) documentation.
|
||
- The system must be using SSL as Microsoft only allows OAuth redirect URIs that are SSL-enabled.
|
||
|
||
</Note>
|
||
|
||
Follow these steps to configure Mattermost to use your Entra ID logon credentials and Azure Active Directory account as a Single Sign-on (SSO) service for team creation, account creation, and sign-in.
|
||
|
||
### Step 1: Register an application in Azure Portal
|
||
|
||
1. Log in to the [Azure Portal](https://portal.azure.com/) with the account that relates to the Azure Active Directory tenant where you want to register the application. You can confirm the tenant in the top right corner of the portal.
|
||
2. In the left-hand navigation pane, select the **Microsoft EntraID**, then toward the bottom select **Add application registrations**.
|
||
3. Give your new registration a **Name**.
|
||
4. Define which **Supported account types** can access the application. For example, if this is to be only accessed from your enterprise's Azure AD accounts, then select **Accounts in this organizational directory only**.
|
||
5. Define the **Redirect URI** as Web client, then input the URL with the host name that will be specific to your Mattermost service followed by `/signup/office365/complete`. An example below is: `https://your.mattermost.com/signup/office365/complete`
|
||
|
||
|
||
|
||
|
||
|
||
Once the App Registration has been created, you can configure it further. See the standard [Azure AD documentation](https://learn.microsoft.com/en-gb/azure/active-directory/develop/quickstart-register-app) for reference.
|
||
|
||
### Step 2: Generate a new client secret in Azure Portal
|
||
|
||
1. From the overview page of the newly created **Registered App**, select **Certificates and Secrets** from the menu, then select the button to generate a **New Client secret**.
|
||
|
||
|
||
|
||
2. Provide a description, define the expiry for the token, then select **Add**.
|
||
|
||
|
||
|
||
3. Store the **value** of the new secret somewhere secure.
|
||
4. In Azure Portal, select **Overview** from the menu, then copy and paste both the Application (client) ID and the Directory (tenant) ID to a temporary location. You will enter these values as an **Application ID** and as part of an **Auth Endpoint** and **Token Endpoint** URL in the Mattermost System Console.
|
||
|
||
|
||
|
||
5. Grant admin concent for the configured permissions under **App Registrations \> \<Your App\> \> Manage \> API Permissions**
|
||
|
||
|
||
|
||
### Step 3: Configure Mattermost for Entra ID SSO
|
||
|
||
1. Log in to Mattermost, then go to **System Console \> Authentication \> OpenID Connect**.
|
||
2. Select **Entra ID** as the service provider.
|
||
3. Paste the **Directory (tenant) ID** from the Azure Portal as the **Directory (tenant) ID** in Mattermost.
|
||
4. The **Discovery Endpoint** for OpenID Connect with Entra ID is prepopulated with `https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration`.
|
||
5. Paste the **Application (client) ID** from the Azure Portal as the **Client ID** in Mattermost.
|
||
6. Paste the **client secret** value from the Azure Portal as the **Client Secret** in Mattermost.
|
||
7. Select **Save**.
|
||
|
||
<Note>
|
||
|
||
When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes.
|
||
|
||
</Note>
|
||
|
||
### Note about Microsoft Active Directory Tenants
|
||
|
||
A Microsoft Active Directory (AD) tenant is a dedicated instance of Azure Active Directory (Azure AD) that you own and would have received when signing up for a Microsoft cloud service, such as Azure or Entra ID. Tenants are commonly used by organizations who want to store information about their users, such as passwords, user profile data, and permissions. See the [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant) documentation to learn more about getting an Azure AD tenant.
|
||
|
||
To allow your Azure AD users to log in to Mattermost using Entra ID SSO, you must register Mattermost in the Microsoft Azure AD tenant that contains the users' information. The registration can be done from the [Microsoft Azure portal](https://portal.azure.com). The steps to register the Mattermost account in the tenant should be similar to those provided above, and you can find more information about [integrating apps with Azure AD here](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant).
|
||
|
||
If you don't register Mattermost in the Microsoft Azure AD tenant your organization uses, Entra ID SSO will likely fail for your users.
|
||
|
||
<Note>
|
||
|
||
If you do not use Azure Active Directory, you may register Mattermost with your Entra ID or Azure account (a personal, work, or school account), then set up Entra ID SSO with Mattermost using the steps provided above.
|
||
|
||
</Note>
|
||
|
||
### Configure Mattermost `config.json` for Entra ID SSO
|
||
|
||
Instead of using the System Console, you can add the Entra ID settings directly to the `config.json` file on your Mattermost server.
|
||
|
||
1. Open `config.json` as *root* in a text editor. It’s usually in `/opt/mattermost/config` but it might be elsewhere on your system.
|
||
2. Locate the `Office365Settings` section, then add or update the following information:
|
||
|
||
``` text
|
||
"Office365Settings": {
|
||
"Enable": false,
|
||
"Secret": "i.hddd6Pu3--5dg~cRddddqOrBdd1a",
|
||
"Id": "28ddd714-1f2f-4f9c-9486-90b8dddd27",
|
||
"Scope": "profile openid email",
|
||
"AuthEndpoint": "",
|
||
"TokenEndpoint": "",
|
||
"UserApiEndpoint": "",
|
||
"DiscoveryEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
|
||
"DirectoryId": "common"
|
||
}
|
||
```
|
||
|
||
3. Save your changes, then restart your Mattermost server. After the server restarts, users must change their login method before they can log in with Entra ID.
|
||
|
||
## Frequently Asked Questions
|
||
|
||
### How can I use LDAP attributes or Groups with OpenID?
|
||
|
||
At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak.
|