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

July 30, 2020

Platform

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.