Mattermost Teams Edition— Replacing Gitlab SSO with Keycloak

Many of the developers where I work have been looking for a persistent chat alternative to SfB. While there are several good options in this space, in order to satisfy internal security concerns we ultimately decided on Mattermost. Unfortunately, many of the more advanced authentication features in Mattermost are locked behind the E20 licensing. Eventually we’d like to move to a licensed instance to ease administration, but in the short term we have both a desire to switch to Mattermost quickly and a desire to integrate with LDAP.

While Keycloak is not able to reproduce all the functionality the Gitlab integration provides, it does help us avoid having to run and support a fairly heavy Gitlab instance.

Thanks to wadahiro for his original write up here, https://qiita.com/wadahiro/items/8b118c34aae904353865.

This guide assumes you already have both a mattermost instance and keycloak instance (and later, optionally, LDAP) already setup. If you do not, set these up and come back.

This guide was implemented with the following versions of software.

• Mattermost Server 5.13.2
• Keycloak 6.0.1
• OpenLDAP 2.4.47

To get started, let’s create a realm in Keycloak. You can do so by hovering over the realm on the top left and selecting add realm. For this guide, I will be creating a realm with the name mattmost.

Next, we’ll create a client configuration for Mattermost. Select Clients on the left, then click the create button on the far right. You’ll want to ensure you have the following settings (and only the following settings) configured on the client’s settings page.

1. Client ID (In my case I’ve chosen the id mattermost)
2. Enabled (ON)
3. Client Protocol (openid-connect)
4. Access Type (confidential)
5. Standard Flow Enabled (ON)
6. Valid Redirect URIs (Your mattermost base address + /signup/gitlab/complete)

After configuring the values you’ll want to hit save.

Mattermost is expecting specific information back from the OAuth server that Keycloak either doesn’t provide, or typically provides in a different format. Because of this, we’ll need to configure a few client mappers.

To do so, select the Mappers tab under your client and then click Create.

You should use the following settings,

1. Name: mattermostId (You can choose whatever you’d like)
2. Mapper Type: User Attribute
3. User Attribute: mattermostId (You can choose whatever you’d like)
4. Token Claim Name: id (Must be this)
5. Claim JSON Type: long (Must be this)
6. Add to userinfo: ON (Must be this)

Click save.

Now we’ll create a second protocol mapper, this is necessary because Keycloak does not pass a key named username by default.

1. Name: username (You can choose whatever you’d like)
2. Mapper Type: User Property
3. Property: username (Must be this)
4. Token Claim Name: username (Must be this)
5. Claim JSON Type: String (Must be this)
6. Add to userinfo: ON

All other sliders should be off. Click save.

For testing purposes we’re going to create a local user in Keycloak.

On the left, select Users and then Add user. Fill out the Username, Email, First Name and Last Name fields, then hit save.

Now, you might be wondering why we had to create a mapper for id. The reason is mattermost is expecting Gitlab to provide it with the user’s Gitlab id. The Gitlab id is a numeric value that Gitlab would typically store for its own usage. Given we’re not using Gitlab, we’ll need to provide this value ourselves. To this end, we need to go in and add an attribute with this name & value to the user we just created.

Select the Attributes tab for the user you created. Your key will be the user attribute you chose when creating the mattermost id mapper and the value should be an integer between 1 and 9999999999999999999 that has not already been assigned to another user.

In my case,

Key: mattermostId

Value: 1

Important Note: This integer must be unique per user. If it is not, users with the same id will be logged into the same mattermost account.

Next we need to configure Mattermost to use Gitlab for authentication, but before we do so, let’s get a few values we’ll need.

We’re going to need the auth, token, and userinfo endpoints for your realm from Keycloak. You can get these values by clicking Realm Settings on the left and then OpenID Endpoint Configuration.

Pull out the values for authorization_endpoint, token_endpoint, and userinfo_endpoint. You can make it easier to read by running it through a json pretty printer.

Now we need our client secret. Click Clients on the left and select your Mattermost client, then select the Credentials tab. Copy the contents of the Secret field and save them for later.

A few parts of the Mattermost Gitlab auth configuration can be done in the web system console, but ultimately we’ll need to update the config.json anyway so we’re going to just do it all there.

Open your config.json and search for the string Git. You can do this in vi with /Git, then hit ENTER, then press i to insert. You’ll want to change the following values,

Enable: true

Secret: 3e914323–818b-4eq5-a9be-85a1be70b11a (This is an example, use your own and keep it safe)

Id: mattermost (This is the name of the client you setup in keycloak)

AuthEndpoint: https://hostname/auth/realms/mattermost/protocol/openid-connect/auth (Use your own)

TokenEndpoint: https://hostname/auth/realms/mattermost/protocol/openid-connect/token (Use your own)

UserApiEndpoint: https://hostname/auth/realms/mattermost/protocol/openid-connect/userinfo (Use your own)

You can save your changes by hitting escape, then :wq, then ENTER. Mattermost should auto reload after detecting a change to its configuration.

Now go to your Mattermost sign in page. Once there you should see a purple button to sign in with Gitlab. Select that and after being redirected to Keycloak enter the username and password for the Keycloak user you created. If everything was correctly setup you should be sent back to Mattermost as a signed in user. If not, scroll to the end of this document to find the troubleshooting section.

Optional: LDAP Setup

After you get the local Keycloak user working, you may want to add an external provider like ldap to the mix. If not, you can skip this section.

We’ll start by adding the ldap provider. Under your mattermost realm, select User Federation. Then click Add provider, and select ldap.

Specific settings and what they do are outside the scope of this guide, but here’s an example of my configuration all the same. If you need help those little question marks next to settings are pretty useful.

Now, remember that mattermost id field we needed for the local user? Well, we also need it for our ldap users. Where I work the best fit for this need was the employeeNumber ldap attribute, but if you have another unique attribute with a numeric value you can use that instead.

Under the provider you created select the Mappers tab, then click Create.

Name: employeeNumber (This can be whatever you’d like)

Mapper Type: user-attribute-ldap-mapper (Must use)

User Model Attribute: employeeNumber (The name of the attribute as it will exist on Keycloak’s side)

LDAP Attribute: employeeNumber (The name of the attribute as it exists on ldap’s side)

The remaining settings can be changed to suit your needs. When you’re done hit save.

After setting up the ldap mapper we’ll want to import our users into Keycloak. Switch back to the Settings tab and at the bottom select Synchronize all users.

Now we’re going to need a client mapper for that ldap mapper. Select Clients on the left, then select your mattermost client. Next, go to the Mappers tab and click Create.

Name: ldap_mattermost_id_mapper (This can be whatever you’d like)

Mapper Type: User Attribute (Must use)

User Attribute: employeeNumber (Use whatever you selected for the User Model Attribute)

Token Claim Name: id (Must use)

Claim Json Type: long (Must use)

Add to userinfo: ON (Must use)

All other sliders should be set to off. Click save.

If everything’s setup correctly you should now be able to use gitlab authentication with Keycloak to log in as an ldap user.

Troubleshooting

This section is a work in progress. I will likely add more information as I run into issues.

Keycloak:

• Invalid parameter: redirect_uri

Double check that the Valid Redirect URIs you have configured in your client match what mattermost is providing. You can see the value for this in your browsers address bar on the error page. The value will be URL encoded, you should decode it.

Mattermost:

• Could not parse auth data out of gitlab user object

This means something is wrong with the user information in the response we’re sending from Keycloak. Verify your mappers are setup correctly and that the values being passed are the correct data type.

• Token request failed

This can happen for a number of reasons. Double check that the URLs you configured in the GitLabSettings of config.json are correct (including protocols). Verify that the the machine you’re running Mattermost on can reach the machine you have Keycloak running on. Check the logs for both Mattermost and Keycloak.