Configure SAML with OneLogin

import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx'; import Inc1_sso_saml_ldapsync from './sso-saml-ldapsync.mdx'; import Inc2_sso_saml_faq from './sso-saml-faq.mdx';

<PlanAvailability slug="all-commercial" />

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

See the encryption options documentation for details on what encryption methods Mattermost supports for SAML.

<Inc0_sso_saml_before_you_begin />

Create a OneLogin connection app for Mattermost SSO

1. Add a SAML test connector app.

1. Log in to OneLogin as an administrator.
2. Go to Apps > Add Apps.
3. Search for "SAML Test Connector", then select SAML Test Connector (Advanced).

4. In the Display Name field, enter a name for the application, then optionally upload an app icon. You can use the Mattermost logo for the icon, which you can download from Branding Guidelines page.

5. Make sure that the Visible in portal option is enabled.
6. Select Save.

2. Configure the app.

1. Select the Configuration tab, then enter the following values:

• RelayState: leave blank
• Audience: leave blank
• Recipient: https://<your-mattermost-url>/login/sso/saml where https://<your-mattermost-url> should typically match the Mattermost Site URL.
• ACS (Consumer) URL Validator: https:\/\/<your-mattermost-url>\/login\/sso\/saml
• ACS (Consumer) URL: https://<your-mattermost-url>/login/sso/saml

2. In System Console, enable encryption, then select Save. You're redirected to the Info tab. From there, select the Configuration tab to access the SAML Encryption field.
3. Paste the Public Key that you generated earlier into the SAML Encryption field at the bottom of the page. This field displays in OneLogin only when encryption is enabled in Mattermost.

4. Select Save.

3. Enter the attribute parameters. The following attributes are recommended:

<table style={{width: '26%'}}> <colgroup> <col style={{width: '14%'}} /> <col style={{width: '11%'}} /> </colgroup> <thead> <tr> <th>Name</th> <th>Value</th> </tr> </thead> <tbody> <tr> <td>ID</td> <td>UUID</td> </tr> <tr> <td>Email</td> <td>Email</td> </tr> <tr> <td>FirstName</td> <td>First Name</td> </tr> <tr> <td>LastName</td> <td>Last Name</td> </tr> <tr> <td>Name ID value</td> <td>Email</td> </tr> <tr> <td>Username</td> <td>Username</td> </tr> </tbody> </table>

Attribute parameters map attributes between OneLogin and Mattermost. For more information on which attributes are configurable, see our documentation on SAML configuration settings.

Email attributes are required.

1. Select the Parameters tab.
2. Select Add Parameter.

3. In the Field name field, enter an attribute parameter such as Email.
4. Select the Include in SAML assertion checkbox.
5. Select Save.

6. Select Edit.
7. In the Value field, select the OneLogin value that corresponds to the attribute parameter.

8. Repeat the steps above to add any other attributes that you need. After you've added all the attributes you want to use, the parameter list should look similar to the following image:

4. Copy the SSO information.

1. Select the SSO tab.
2. Copy the values in the Issuer URL and SAML 2.0 Endpoint (HTTP) fields, then save them for later use.

3. Select View Details to view the X.509 certificate.
4. Make sure that the X.509 PEM option is selected in the drop-down.

5. Select DOWNLOAD, then save the file in a convenient location for later use.

5. Save all your changes.

Configure SAML Sign-On for Mattermost

1. Start the Mattermost server, then log in to Mattermost as a system admin. Go to System Console > Authentication > SAML.

1. Enter the OneLogin Issuer URL into the Identity Provider Metadata URL field.
2. Select Get SAML Metadata from IdP to download the metadata.

2. Configure Mattermost to verify the signature.

1. In the Verify Signature field, select True.
2. In the Service Provider Login URL, enter https//<your-mattermost-url>/login/sso/saml.

3. Configure Mattermost to sign SAML requests using the Service Provider Private Key.
4. Enable encryption.

1. In the Enable Encryption field, select True.
2. In the Service Provider Private Key field, upload the private key that you generated earlier.
3. In the Service Provider Public Certificate field, upload the public key that you generated earlier.

5. Set attributes for the SAML Assertions, which are used for updating user information in Mattermost.

The Email Atttribute field and the Username Attribute field are required, and should match the values that you entered earlier when you configured the SAML Test Connector on OneLogin.

6. (Optional) Customize the login button text.
7. Select Save.
8. (Optional) If you configured First Name Attribute and Last Name Attribute, go to System Console > Site Configuration > Users and Teams, then set Teammate Name Display to Show first and last name. This is recommended for a better user experience.

To confirm that SAML SSO is successfully enabled, switch your system admin account from email to SAML-based authentication from your profile picture via Profile > Security > Sign-in Method > Switch to SAML SSO, then log in with your SAML credentials to complete the switch.

We also recommend that you post an announcement to your users detailing how the migration will work.

You can also configure SAML for OneLogin by editing the config.json file to enable SAML based on SAML configuration settings. You must restart the Mattermost server for the changes to take effect.

<Inc1_sso_saml_ldapsync />

<Inc2_sso_saml_faq />