Configure SAML with Okta

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

Before you begin

Before you configure SAML:

  1. Make sure you have the XML Security Library installed on your Mattermost instance. The XML Security Library is usually included as part of Debian GNU/Linux.
  2. Install the xmlsec1-openssl library
  • On Ubuntu: sudo apt-get install libxmlsec1-openssl
  • On RHEL: sudo yum install xmlsec1-openssl
  1. Generate encryption certificates for encrypting the SAML connection.
  1. You can use the Bash script from the mattermost/docs repository on GitHub, or any other suitable method.
  2. Save the two files that are generated. They are the private key and the public key. In the System Console, they are referred to as the Service Provider Private Key and the Service Provider Public Certificate respectively.

Set up a connection app for Mattermost SSO

  1. Sign into Okta as an administrator.

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

  3. Click Create New App and choose SAML 2.0 as the Sign on method.

    ../_images/okta_1_new_app.PNG

  4. Enter General Settings for the application, including App name and App logo (optional). It is 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 are free to download one from our page.

../_images/okta_2_general_settings.PNG
  1. Enter SAML Settings, including:

  • Single sign on URL: https://<your-mattermost-url>/login/sso/saml

  • Audience URL: For instance, mattermost

  • Name ID format: unspecified

  • Application username: Email

    ../_images/okta_3_initial_saml_settings.PNG

  1. Set up encryption for your SAML connection. First, click Show Advanced Settings.

    ../_images/okta_4_initial_saml_settings.PNG

Then, set Assertion Encryption as Encrypted and upload the Service Provider Public Certificate you generated in step 2 to the Encryption Certificate field.

../_images/okta_5_advanced_saml_settings.PNG

  1. Enter attribute statements, which will be 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 Mattermost servers running 3.3 and earlier, first name and last name attributes are also required.

    ../_images/okta_6_attribute_statements.PNG

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

    ../_images/okta_7_support_configuration.PNG

  1. Click Finish. On the next screen, click the Sign On tab and click View Setup Instructions.

    ../_images/okta_8_view_instructions.PNG

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

Furthermore, you must download the X.509 Public Certificate file and save it. You will need to upload it to Mattermost at a later step.

../_images/okta_9_view_instructions.PNG

Configure SAML for Mattermost

  1. Start Mattermost server and sign into Mattermost as a System Administrator. Go to System Console > Authentication > SAML, and enter the following fields:

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

    ../_images/okta_10_mattermost_basics.PNG

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

    ../_images/okta_11_mattermost_verification.PNG

  2. Enable encryption based on the parameters provided earlier.

    ../_images/okta_12_mattermost_encryption.PNG

  3. Set attributes for the SAML Assertions, which will be used to update user information in Mattermost. Attributes for email and username are required and should match the values you entered in Okta earlier. See documentation on SAML configuration settings for more detail.

For Mattermost servers running 3.3 and earlier, the first name and last name attributes are also required fields.

../_images/okta_13_mattermost_attributes.PNG

  1. (Optional) Customize the login button text.

    ../_images/okta_14_mattermost_login_button.PNG

  2. Click Save.

  3. (Optional) If you configured First Name Attribute and Last Name Attribute, go to System Console > General > Users and Teams and set Teammate Name Display to Show first and last name. This is recommended for a better user experience.

You’re done! If you’d like to confirm SAML SSO is successfully enabled, switch your System Administrator account from email to SAML-based authentication via Account Settings > General > Sign-in Method > Switch to SAML SSO and sign in with your SAML credentials to complete the switch.

It is also recommended to post an announcement about how the migration will work to users.

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

Troubleshooting

The following are troubleshooting suggestions on common error messages and issues.

  1. System Administrator locks themselves out of the system
If the System Administrator is locked out of the system during SAML configuration process, they can set an existing account to System Administrator using a command line tool.
  1. Received error message: An account with that username already exists. Please contact your Administrator.

This usually means an existing account has another authentication method enabled. If so, the user should sign in using that method (such as email and password), then change their sign-in method to SAML via Account Settings > Security > Sign-in method.

This error message can also be received if the Username Attribute of their SAML credentials doesn’t match the username of their Mattermost account. If so, the user can update the attribute at their identity provider (for instance, back to the old value if it had been previously updated).

  1. Received error message: An account with that email already exists. Please contact your Administrator.

This usually means an existing account has another authentication method enabled. If so, the user should sign in using that method (such as email and password), then change their sign-in method to SAML via Account Settings > Security > Sign-in method.

This error message can also be received if the Email Attribute of their SAML credentials doesn’t match the email address of their Mattermost account. If so, the user can update the attribute at their identity provider (for instance, back to the old value if it had been previously updated).

  1. Received error message: SAML login was unsuccessful because one of the attributes is incorrect. Please contact your System Administrator.
Confirm all attributes, including Email Attribute and Username Attribute, are correct in both the Identity Provider configuration and in System Console > SAML.
  1. Unable to switch to SAML authentication successfully

First, ensure you have installed the XML Security Library on your Mattermost instance and that it is available in your PATH.

Second, ensure you have completed each step of the SAML configuration.

If you are still having trouble with configuration, feel free to post in our Troubleshooting forum and we’ll be happy to help with issues during setup.