[FAQ] Does Mattermost integrate with JumpCloud for SAML Authentication?

[cwarnermm (Carrie Warner)]

Yes!

In order to use JumpCloud as a SAML provider for Mattermost, you will need a few things:

• A Mattermost Professional or Enterprise licence (SAML integration is not available on the free version)
• Admin access to your Mattermost System Console
• Admin access to your JumpCloud environment

You will also need to make a note of your Mattermost URL.

For a complete walkthrough of setting up this integration, see the Mattermost - JumpCloud Integration: A Step-by-Step Guide to SAML Authentication video on YouTube, or follow the steps below.

Setting Up JumpCloud
Before you start, it is helpful to already have one or more User Groups in JumpCloud, with users already assigned. This will make life easier when you come to test the integration later.

From the left-hand menu in JumpCloud, select “SSO” (under “USER AUTHENTICATION”):

If you don’t currently have any SSO applications configured, you will see a “Get Started” button at the bottom of the screen:

Otherwise, there will be a button labelled “Add New Application” in the upper left of the main screen:

Whichever option you have, click the button to create a new SSO integration. From the next page, we need to select the “Custom SAML App” from the bottom of the screen:

Give this app a name using the “Display Label” field (we recommend calling it ‘Mattermost’ so that the purpose of the integration is clear). We can now switch to the SSO tab for the main configuration:

Towards the bottom of this page, there is a field where you can define your IDP URL. This is made up of a fixed portion (which may be different to the examples on this page) and a custom portion. The custom portion defaults to ‘saml2’, but may need to be changed if this is already in use within your environment.

Whatever you choose for the custom portion of this URL, make a note of the entire URL, as we’ll need it as we progress.

Back at the top of the page, there are fields for the IdP Entity ID and the SP Entity ID. The ‘IdP Entity ID’ is simply the ‘IDP URL’ that you just noted. The ‘SP Entity ID’ (SP stands for “Service Provider”) is used to match with Mattermost. We recommend using the string: mattermost

We need to enter an ACS URL so that JumpCloud knows where to send SAML responses. This will be: http(s)://<MATTERMOST_URL>/login/sso/saml

Remember to include the port number in your Mattermost URL, if you’re not using the defaults of 80/443.

Scroll down to the bottom of the form, leaving everything set to the defaults. At the very bottom, there is a section titled ‘Attributes’. This allows us to specify what fields in Mattermost will be called when we map them across to JumpCloud, the key ones being for the email and username fields. To keep things clear, we would advise using the same attribute names in both systems.

To do this, we need two entries, mapping email to email, and username to username.

Before leaving the JumpCloud configuration, we recommend going to the “User Groups” tab at the top of the page and adding one or more user groups to this configuration. This will map users already, making testing easier.

Once complete, press the activate button at the lower right of the page.

After activating and confirming, you will be presented with a notification in the upper right of the page giving you a link to download the certificate. We will require this when we configure Mattermost.

Before moving on, it would be helpful to copy the JumpCloud Metadata URL from the SSO tab, as we’ll need this when we setup Mattermost:

Setting Up Mattermost
In the Mattermost System Console, scroll down the left-hand navigation until you find SAML 2.0 in the “AUTHENTICATION” section.

To configure Mattermost to use JumpCloud’s SAML, carry out the following steps:

• Enable the SAML section by setting Enable Login With SAML 2.0 to true

• Paste the copied JumpCloud Metadata URL into the field labelled Identity Provider Metadata URL

• Within JumpCloud, we identified the IDP URL. Copy and paste this URL into both the SAML SSO URL and Identity Provider Issuer URL fields.

• Next we need to upload the certificate that we downloaded from JumpCloud. Note that the name of the file changes to saml-idp.crt after uploading.
  

• The Service Provider Identifier field should match the entry used for the SP Entity ID field in JumpCloud. If you’re following our guidelines, then this would be mattermost.

• By default, you will see that the Enable Encryption field is set to ‘true’. This is not supported by JumpCloud, so must be set to ‘false’.

• Towards the bottom of the page, we see the fields Email Attribute and Username Attribute. These should be configured to match the attributes set in JumpCloud—in our case, we are using email and username.

• Finally, at the very bottom of the form, you can choose to set your Login Button Text to make it clear how users will be signing in. This will then show as the optional SAML option at the bottom of their login screen.