Skip to content

Sso Saml Keycloak

import Inc0_sso_saml_ldapsync from './sso-saml-ldapsync.mdx'; import Inc1_sso_saml_faq from './sso-saml-faq.mdx';

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

See the supported SAML encryption methods in the authentication configuration settings documentation.

Set up Keycloak for Mattermost SSO

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

  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
  1. 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
  1. Save the client.
  2. 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.

In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes.

  1. 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.

Note

Earlier versions of this documentation recommended RSA_SHA1. Use RSA_SHA256 instead. NIST SP 800-131A 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.

  1. Navigate to the Keys tab.

  • Client signature required: Off

  • Encrypt Assertions: On

  • Click Generate

  • Download the private.key file.
  • Click Confirm

In Keycloak, on the Keys tab, generate new keys for encryption.

Warning

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.

Note

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:

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:

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.

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.

  1. 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.

    1. 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.

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.

Once done your Mappers should look like this:

Example of protocol mapper configuration.

  1. 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.

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 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.

  • 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 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 documentation for details.

  1. 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.

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

    1. Generate the .crt file from the .p12 file.
    openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.crt -nodes -legacy
    1. Generate the .key file from the .p12 file.
    openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.key -nodes -nocerts -legacy
    1. 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.

  3. 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 for more details.

    • Email Attribute: email
    • Username Attribute: username
    • Id Attribute: id

    Set attributes for the SAML assertions which updates user information in Mattermost.

  4. 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. 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

  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>

  1. 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.

:start-after: :nosearch: