upstream-mattermost/docs/main/administration-guide/onboard/sso-saml-keycloak.mdx

---
title: "Configure SAML with Keycloak"
---
import Inc0_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
import Inc1_sso_saml_faq from './sso-saml-faq.mdx';

<PlanAvailability slug="all-commercial" />

The following process provides steps to configure SAML with Keycloak for Mattermost.

See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.

## Set up Keycloak for Mattermost SSO

<Note>

This was tested with Keycloak v26.4.0. We recommend adding Mattermost as a client to your primary realm.

</Note>

1.  Log in to Keycloak as an administrator.
2.  Select **Clients**, then **Create client**. You'll use this client ID in a later step.

> - **Client type**: `SAML`
> - **Client ID**: `mattermost`

3.  Click **Next** and update the following values:

> - **Root URL**: `http://your-mattermost-url.com`
> - **Home URL**: `/login/sso/saml`
> - **Valid redirect URIs**: `/login/sso/saml`

4.  **Save** the client.
5.  Under the **Settings** tab, update the following values:

> - **Enabled**: **On**
> - **Name ID format**: `email`
> - **Force Name ID format**: **On**
>
> ![In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes.](/images/keycloak_1_client_settings.png)
>
> ![In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes.](/images/keycloak_1_client_settings_2.png)

6.  Under the **Signature and Encryption** section, update the following values:

> - **Sign Documents**: **Off**
> - **Sign Assertions**: **On**
> - **Signature Algorithm**: `RSA_SHA256`
> - **SAML signature key name**: `NONE`
> - **Canonicalization Method**: `EXCLUSIVE`
> - **Encryption Algorithm**: `AES_256_GCM`
> - **Key Transport Algorithm**: `RSA_OAEP_MGF1P`
> - **Digest method for RSA-OAEP**: `SHA1`
>
> ![In Keycloak, configure the Signature and Encryption settings for the Mattermost client.](/images/keycloak_1_client_signature_encryption.png)
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> Earlier versions of this documentation recommended `RSA_SHA1`. Use `RSA_SHA256` instead. [NIST SP 800-131A](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) set December 31, 2013 as the deadline after which SHA-1 is disallowed for digital signature generation. Revision 2 of that publication, published in March 2019, allows SHA-1 signature generation only where NIST protocol-specific guidance specifically permits it. A Keycloak server running in FIPS mode returns a `500` error when it tries to sign the assertion with `RSA_SHA1`. Mattermost validates `RSA_SHA256`-signed assertions, and Keycloak derives the signature digest method from the signature algorithm you select here.
>
> </div>

7.  Navigate to the **Keys** tab.

> - **Client signature required**: **Off**
>
> - **Encrypt Assertions**: **On**
>
>   1.  Click **Generate**
>   2.  Download the **private.key** file.
>   3.  Click **Confirm**
>
>   ![In Keycloak, on the Keys tab, generate new keys for encryption.](/images/keycloak_2_saml_keys.png)
>
>   <div class="warning">
>
>   <div class="title">
>
>   Warning
>
>   </div>
>
>   Leave **Client signature required** off, as shown above. Mattermost does sign its authentication requests when you enable **Sign Request** in step 4 of the Mattermost section below, but Keycloak validates those signatures only if you also import the Mattermost service provider certificate as a signing key on this tab. Turning **Client signature required** on without importing that certificate causes Keycloak to reject Mattermost's authentication requests.
>
>   </div>
>
>   <div class="note">
>
>   <div class="title">
>
>   Note
>
>   </div>
>
>   **If your Keycloak server runs in FIPS mode**, the **Archive Format** list offers only `BCFKS`, because `PKCS12` and `JKS` are unavailable. Export the `BCFKS` keystore, then convert it to `PKCS12` before you continue:
>
>   ```console
>   keytool -importkeystore -srckeystore keystore.bcfks -srcstoretype BCFKS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath /path/to/bc-fips-<version>.jar -destkeystore keystore.p12 -deststoretype PKCS12
>   ```
>
>   Point `-providerpath` at your Bouncy Castle FIPS JAR. `keytool` prompts for the source and destination store passwords. The converted `keystore.p12` then works with the extraction commands in step 4 of Configure SAML in Mattermost below.
>
>   Convert the whole keystore as shown above rather than looking for a way to export the key on its own, because `keytool` has no command that exports a private key by itself.
>
>   As an alternative, generating the keypair locally and importing only the certificate into Keycloak avoids the keystore conversion entirely, and works on FIPS and non-FIPS servers alike:
>
>   ```console
>   openssl req -x509 -newkey rsa:2048 -nodes -days 1095 -subj "/CN=mattermost" -keyout mattermost.key -out mattermost.crt
>   ```
>
>   Keep `-nodes`, because Mattermost can't read a passphrase-protected private key. Set `-days` explicitly, because it defaults to 30. Keep `-keyout` and `-out`, because without them the certificate goes to standard output and the private key goes to a configuration-dependent default filename.
>
>   Import only `mattermost.crt` into the encryption keys section of this tab, then upload both files in step 4 below and skip the `openssl pkcs12` extraction commands, since you already have the files those commands would have produced.
>
>   </div>
>
>   Next, click **Export** and update the following values and download the keystore.p12 file.
>
>   - **Archive Format**: `PKCS12`
>   - **Key Alias**: `mattermost`
>   - **Key Password**: `mattermost`
>   - **Store Password**: `mattermost`
>
>   ![In Keycloak, on the Keys tab, generate new keys, export using the values documented, then select Download.](/images/keycloak_2_saml_keys_2.png)

8.  Navigate to the **Client scopes** tab.

    First we add the predefined mappers for email, first name, and last name.

    1.  Select **mattermost-dedicated**
    2.  Click **Add predefined mapper**
    3.  Select the **X500 email**, **X500 givenName**, and **X500 surname** attributes.
    4.  Click **Add**.

    Next, we add the mappers for username and id.

    1.  Select **Add Mapper** -\> **By Configuration** -\> User Property.
    2.  Set **Name** to `Username`.
    3.  Set **Property** to `username` (This is case sensitive and must be lowercase).
    4.  Set **SAML Attribute Name** to `username`.
    5.  Select **Save**.

    ![In Keycloak, on the Mappers tab, create a protocol mapper, then save your changes.](/images/keycloak_4_create_username_attribute.png)

    6.  Repeat the above steps and use the custom property of `id` to create the ID Attribute.

    ![In Keycloak, on the Mappers tab, create a protocol mapper for the ID attribute, then save your changes.](/images/keycloak_4_create_id_attribute.png)

<Note>

If you're planning to sync your SAML users with LDAP within Mattermost, the ID value used here must match with your Mattermost LDAP `ID Attribute`.

</Note>

Once done your Mappers should look like this:

![Example of protocol mapper configuration.](/images/keycloak_4_create_username_attribute_finished.png)

9.  Get the metadata URL from Keycloak:

    1.  Within your Realm, select **Realm Settings**.
    2.  At the bottom of the **General** tab you should see a **SAML 2.0 Identity Provider Metadata** endpoint. Right-click and copy this URL. Store for the next step.

    ![Within your Realm, select Realm Settings. At the bottom of the General tab, you should see a SAML 2.0 Identify Provider Metadata endpoint. Copy this URL for the next step.](/images/keycloak_5_export_metadata.png)

## Configure SAML in Mattermost

1.  In the Mattermost **System Console** go to **Authentication \> SAML**.

2.  Set the **Identity Provider Metadata URL** to the value you copied from the step above and select **Get SAML Metadata from IdP**. The metadata import will populate fields related to your Keycloak configuration.

    If you have any issues with this import, you can check the `mattermost.log` file for more information. [Enable debug logging](/administration-guide/manage/logging#how-do-i-enable-debug-logging) and try again.

    > ![In Mattermost, configure SAML in the System Console by going to Authentication \> SAML. Set the Identity Provider Metadata URL to the value you copied in the previous step. When you select Get SAML Metadata from IdP, fields related to your Keycloak configuration are populated.](/images/keycloak_6_get_metadata.png)

<Note>

- If Mattermost does not correctly pull the **Identity Provider Public Certificate** you can manually add it by opening the metadata URL in a browser, copying the certificate value, and use a tool like [OneLogin's X.509 formatter](https://www.samltool.com/format_x509cert.php) that can format the certificate for you. Then save the correctly formatted certificate to a file and upload it to the **Identity Provider Public Certificate** field in the Mattermost System Console.
- If Mattermost can not pull the metadata and is throwing a connection issue enable debug logging and see if you need to add your Keycloak url to the **Allowed Untrusted Internal Connections** list in the System Console under **Environment \> Developer** and restart the server. See the [Allowed Untrusted Internal Connections](/administration-guide/configure/environment-configuration-settings#allow-untrusted-internal-connections) documentation for details.

</Note>

3.  Set the below fields:

    - **Verify Signature**: **false**
    - **Service Provider Login URL**: `http://your-mattermost-url.com/login/sso/saml`
    - **Service Provider Identifier**: `mattermost`

    The Service Provider Identifier will match the **Client ID** that you configured in the second Keycloak step.

    ![In the System Console, configure SAML as documented, where the Service Provider Identifier matches the Client ID you configured in Keycloak.](/images/keycloak_7_mattermost_config.png)

4.  Configure the Encryption using the key you downloaded in step 6 of the Keycloak config.

    1.  Generate the `.crt` file from the `.p12` file.

    ``` console
    openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.crt -nodes -legacy
    ```

    2.  Generate the `.key` file from the `.p12` file.

    ``` console
    openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.key -nodes -nocerts -legacy
    ```

    3.  Upload both of these files within the Mattermost System Console. Make sure to select **Upload**.

    > - **Service Provider Private Key**: `mattermost.key`
    > - **Service Provider Private Certificate**: `mattermost.crt`
    > - **Sign Request**: **true**
    > - **Signature Algorithm**: `RSAwithSHA256`
    > - **Canonicalization Algorithm**: `Exclusive XML Canonicalization 1.0 (omits comments)`
    >
    > ![In the System Console, upload both the Service Provider Private Key and the Service Provider Private Certificate.](/images/keycloak_8_mattermost_encryption.png)

5.  Set attributes for the SAML Assertions, which will update user information in Mattermost.

    The attributes below are from steps 7 and 8 above. These values must be the **SAML Attribute Name** within Keycloak. See [documentation on SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20) for more details.

    - **Email Attribute**: `email`
    - **Username Attribute**: `username`
    - **Id Attribute**: `id`

    ![Set attributes for the SAML assertions which updates user information in Mattermost.](/images/keycloak_9_mattermost_attributes.png)

6.  Select **Save**.

To confirm SAML is working correctly, log out of Mattermost or open Mattermost in a new Incognito Browser Window and select **Sign in with SAML** on the login page and login with an existing Keycloak account.

If you have existing users in Mattermost that are going to be migrated to SAML login, make sure to plan for user migration and update your users accordingly.

You may also configure SAML for Keycloak by editing `config.json`. Before starting the Mattermost server, edit `config.json` to enable SAML based on [SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). You must restart the Mattermost server for the changes to take effect.

## Configuing a SAML user as a Guest in Keycloak

1.  In Mattermost, go to **System Console \> Authentication \> SAML**.

2.  Set the **Guest Attribute** to designate which SAML users are guests.

    ![In Mattermost, configure the SAML guest attribute](/images/mm-guset-config.png)

3.  In the Keycloak administration interface, add a user attribute mapper for guests.

> 1.  Select **Clients** from the LHS menu.
> 2.  Select **mattermost** from the list.
>
> > - Select the *Client Scopes* tab
> > - Select *mattermost dedicated* from the list of scopes
> > - Click the *Add mapper* drop down and select *By configuration*
> > - Select *User Attribute* on the model that opens
> > - Add values for *Name*, *User Attribute* and *SAML Attribute Name* as shown
> >
> > ![\<Add attribute mapper\>](/images/keycloak-mapper-details.png)

4.  In Keycloak specify which users are guest by adding the attribute under **User details**

> 1.  Select **Users** from the LHS menu.
> 2.  Select the username of the desired user.
> 3.  Select the **Attribute** tab and select **+ add an attribute**.
> 4.  Add the key and value.
>
> > ![An example of adding an attribute to a user.](/images/guest-user-attribute.png)

<Inc0_sso_saml_ldapsync />

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