ContextQMD
Back to Mattermost

Configure SAML with Okta

docs/main/administration-guide/onboard/sso-saml-okta.mdx

11.10.08.7 KB
Original Source

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 Okta for Mattermost.

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

<Inc0_sso_saml_before_you_begin />

Set Up a connection app for Mattermost Single Sign-On

  1. Log in to Okta as an administrator.

  2. Switch to the Classic UI, using the drop-down in the upper left.

  3. Go to Admin Dashboard > Applications > Add Application.

  4. Select Create New App, then choose SAML 2.0 as the Sign on method.

  5. Enter General Settings for the application, including App name and App logo (optional). It's recommended to display the application icon to users, including in the Okta Mobile app. If you’d like to use a Mattermost logo for the application, you can download one from our page.

  6. Enter SAML Settings, including:

  • Single sign on URL: https://&lt;your-mattermost-url&gt;/login/sso/saml where https://&lt;your-mattermost-url&gt; should typically match the Mattermost Site URL.

  • Audience URI: For instance, mattermost

  • Name ID format: unspecified

  • Application username: Email

  1. To set up encryption for your SAML connection, select Show Advanced Settings.

  2. Set Assertion Encryption as Encrypted, then upload the Service Provider Public Certificate you generated earlier to the Encryption Certificate field.

  3. Enter attribute statements used to map attributes between Okta and Mattermost. For more information on which attributes are configurable, see our documentation on SAML configuration settings. Email and username attributes are required. For SAML with Okta, an ID attribute is also required, and that ID must be mapped to user.id.

  4. Select Next. Then, set Okta support parameters for the application. Recommended settings:

  • I’m an Okta customer adding an internal app

  • This is an internal app that we have created

  1. Select Finish.

  2. In the Mattermost System Console, go to Authentication > SAML 2.0, then set Override SAML bind data with AD/LDAP information to false if currently set to true. You can re-enable this configuration setting later when once setup is complete.

  3. On the next screen, select the Sign On tab, then select View Setup Instructions.

  4. Select the Identity Provider metadata link, then copy the link from the browser URL field. This will be used during the SAML configuration steps in the next section.

  5. Take note of Identity Provider Single Sign-On URL (also known as SAML SSO URL), and the Identity Provider Issuer, as both may be needed to configure SAML for Mattermost.

  6. Download the X.509 Certificate file and save it. You may need to upload it to Mattermost in a later step.

Configure SAML Sign-On for Mattermost

Start the Mattermost server and log in to Mattermost as a system admin. Go to System Console > Authentication > SAML 2.0, then paste the copied Identity Provider Metadata URL in the Identity Provider Metadata URL field and select Get SAML Metadata from IdP.

This populates the SAML SSO URL and the Identity Provider Issuer URL fields automatically. The Identity Provider Public Certificate is also downloaded from the server and set locally.

Alternatively you can enter the following fields manually:

  • SAML SSO URL: Identity Provider Single Sign-On URL from Okta, specified earlier.

  • Identity Provider Issuer URL: Identity Provider Issuer from Okta, specified earlier.

  • Identity Provider Public Certificate: X.509 Public Certificate file you downloaded from Okta earlier.

  1. Configure Mattermost to verify the signature. The Service Provider Login URL is the Single sign on URL you specified in Okta earlier.

  2. Enable encryption based on the parameters provided earlier.

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

  4. Set attributes for the SAML Assertions used to update user information in Mattermost.

    • Attributes for Email, Username, and Id are required and should match the values you entered in Okta earlier.

  5. (Optional) Customize the login button text.

  6. Select Save.

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

Once complete, and to confirm 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 for your users to explain how the migration will work.

You may also configure SAML for Okta 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 />