Skip to content

Sso Saml 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';

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

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

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

In OneLogin, go to Apps > Add Apps, search for SAML Test Connector, then select the matching result in the list

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

Enter a display name for the application in the Display Name field. You can optionally upload an app icon. Ensure the Visible in portal option is enabled, and save your OneLogin changes.

  1. Make sure that the Visible in portal option is enabled.
  2. Select Save.
  1. 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

In OneLogin, select the Configuration tab to configure the SSO integration with required values.

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

In the Mattermost System Console, enable encryption and save your changes. When you return to OneLogin, return to the Configuration tab, access the SAML Encryption field, and paste the generated Public Key into the SAML Encryption field. This field isn't visible in OneLogin until encryption is enabled in Mattermost. Save your OneLogin changes.

  1. Select Save.
  1. Enter the attribute parameters. The following attributes are recommended:
Name Value
ID UUID
Email Email
FirstName First Name
LastName Last Name
Name ID value Email
Username Username

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.

In OneLogin, select the Parameters tab, then select Add parameter. Map attribute parameters between OneLogin and Mattermost. Email attributes are required.

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

For each field you map in OneLogin, ensure the Include in SAML assertion flag is enabled.

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

For each field you map in OneLogin, select the OneLogin value that corresponds to the attribute parameter.

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

Example of attribute parameters mapped between OneLogin and Mattermost.

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

In OneLogin, select the SSO tab, copy the Issuer URL and SAML 2.0 Endpoint (HTTP) values to a convenient location.

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

On the SSO tab in OneLogin, select View Details to access the X.509 certificate. Ensure that the X.509 PEM option is selected. Select Download and save the file in a convenient location.

  1. Select DOWNLOAD, then save the file in a convenient location for later use.
  1. 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.
  1. 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.

On the System Console SAML page, enable the Verify Signature option by setting it to true, then enter your specific Service Provider Login URL based on your Mattermost URL

  1. Configure Mattermost to sign SAML requests using the Service Provider Private Key.
  2. 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.

On the System Console SAML page, enable encryption, then upload both the private and public generated keys.

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

On the System Console SAML page, set attributes for the SAML Assertions used to update user information in Mattermost. Both Email Attribute and Username Attribute are required, and should match the values entered when configuring the SAML Test Connector in OneLogin.

  1. (Optional) Customize the login button text.
  2. Select Save.
  3. (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.