Mattermost Platform

Update to SAML (ADFS): Instructions for versions prior to 5.25

The SAML/ADFS documentation for Mattermost prior to v5.25 included incorrect directions for setting the Relying Party Trust Identifier for SAML setup with Active Directory ADFS. Although the settings will continue to work, we encourage you to modify the settings in line with the fix to ensure your configuration will not be negatively affected with future upgrades.

Note: This issue does not appear to affect OneLogin or Okta implementations. 

The Relying Party Trust Identifier (RPTI) is a string that uniquely identifies the application. The value is passed by the Service Provider (SP) (Mattermost) in the <AuthNRequest><Issuer> object. ADFS then uses this Identifier to understand who is making this request.

The SAML login flow works today because Mattermost places the Identity Provider Issuer URL into this object, which then matches the RPTI.

The string sent is the Identity Provider Issuer URL. This string is returned from ADFS to Mattermost in the response, which allows the SP (Mattermost) to verify the <Issuer> providing the response.

The problem with using the Identity Provider Issuer URL as the RPTI is that it must be unique and as such can only be used once. Following these directions means that a second Mattermost instance cannot be created and configured to point to the same ADFS server as both instances will attempt to use the same RPTI.

Although it can be any unique string, usually, the Service Provider URL is used for this setting, for example https://<your-mattermost-url>/login/sso/saml. Or you could use another URN identifier (i.e., urn:federation:mattermost).In Mattermost v5.25 the implementation has been updated to correct this issue. If you’re setting up SAML for the first time with v5.25 onwards, you can ignore this article and use the appropriate instructions below:

If you have an existing implementation, please follow the steps below to ensure your configuration is correct going forward.

Step 1: Add the unique SP identifier to ADFS

This Relying Party Trust now has two identifiers.

Step 2: Update your Relying Party Trust Identifier in Mattermost.

Go to System Console -> Authentication -> SAML 2.0.

There is a new field called ServiceProviderIdentifier. This field will now be used to set the <ISSUER> property in the SAML request. It will default to the Identity Provider Issuer URL. Although this is wrong, it will maintain backward compatibility.

Update the Service Provider Identifier to the Service Provider Login URL or the new Relying Party Trust Identifier set in Step 1.

Step 3: Test to see if your login still works

Test logging in via SAML and make sure SAML users are able to login.

Step 4: Remove the old Relying Party Identifier

The final step is to remove the “old” Relying Party Identifier in ADFS:

Don’t feel like following these steps? Upgrade to the latest version of Mattermost today.


Scott Bishel is a lead software engineer at Mattermost, Inc. He brings more than three decades worth of developer experience to Mattermost. Previously, Scott worked as a lead software engineer at SalesforceIQ, a principal software engineer at Tempo AI, and a senior software development lead at Microsoft, among other positions. He lives in Colorado.