Custom SSO integration with Matillion Data Productivity Cloud – SAML

Editions

This feature is for customers on our Enterprise edition only. Visit Matillion pricing to learn more about each edition.

Single Sign-On (SSO) is an authentication service that enables users to access multiple applications with a single set of login credentials. This feature enhances security and efficiency by minimizing the need for multiple passwords and simplifying access management.

This guide details the process required to set up SSO integration with the Matillion Data Productivity Cloud using SAML.

Here's a summary of the detailed steps covered in this guide:

1. Create a new SAML application in your identity provider using the information provided below, and share the details of that application with Matillion.
2. Create a TXT DNS entry to all domains that you want to link through SSO.
3. Matillion will set up a matching application and email you the Relay ID along with a link to test the configuration of both applications.
4. Add the Relay ID to your application, and test it using the test link provided.
5. Matillion will address any necessary changes for the configuration and, once everything is complete, we'll fully transition. Normal logins to the Matillion Data Productivity Cloud will remain unaffected during the setup to ensure continued access until the switch is finalized.

---

Identity provider setup

Follow these steps in your selected identity provider portal:

1. Type: SAML.
2. Reply URL (Assertion Consumer Service URL): Enter "https://id.matillion.com/login/callback".
3. Ensure that the Unique User Identifier (Name ID) claim is mapped to an immutable and unique value, such as user.employeeid, instead of the user's email address, which is often the default setting. If it's set to the email, any users who later change their email address will lose access to their account, as they will be recognized as a completely new user to Matillion.

4. Most identity providers automatically generate the standard SAML claims when setting up a new application. However, some may not. Ensure the following claims are present—if any are missing, create and map them accordingly:

   • name - User's full display name
   • email - User's email address
   • given_name - User's first name
   • family_name - User's surname

   Additionally, create a custom claim called email_verified that returns a static value of true. This ensures that users aren't prompted to verify their email address with Matillion, as the identity provider will treat the address as already verified.

5. Set the Identifier to urn:auth0:matillion:[domain]-saml, replacing "[domain]" with your primary email domain and converting any special characters to dashes. For example, "example-company.com" should be formatted as urn:auth0:matillion:example-company-com-saml.

6. Create a TXT DNS entry for each domain you want to bind, containing the text from the end of the Identifier mentioned above, such as matillion:example-company-com-saml.

Raise a support ticket

After completing the identity provider setup, submit a support ticket through the Matillion Support Portal including the following information:

• Enter the name of your identity provider.
• Enter the login URL provided by the application set up with your identity provider.
• Provide a list of domains you wish to bind.
• Provide the certificate from the application configured in your identity provider, in Base64 format.
• Enter confirmation of the identifier used in the application.
• Enter confirmation of the name of the DNS entries created.

Finalize the identity provider setup

Once your support ticket has been received, Matillion will create a matching application, and provide you with its Relay State. Follow the steps to complete the identity provider setup:

1. Set the Relay State in your application to the value previously provided by Matillion.
2. Sign out of any active sessions in Matillion.
3. Visit https://sso-check.matillion.com, enter your email address, and click Log In.
4. After logging in, a list of checkboxes will appear. If any are not green, review the message associated with each one, and adjust your application configuration as needed to resolve the issues.
5. Once all checkboxes are green, the integration can be activated. Before proceeding, ensure all users have committed their work to Git, as any uncommitted work may be lost during the migration.
6. When all work has been committed and you're ready for us to enable the integration fully, please notify us via your support ticket, and we'll complete the transition.
7. We will let you know when the integration has been fully switched on. Once this is complete, all users with an email domain in the list provided will be required to log in via the SSO connection. Users should log in as normal at https://app.matillion.com—upon entering their email address, the password field will be removed and the user can click Log In to be directed to your identity provider.

Note

Users must log in with the same email address they used previously on their first log in via SSO for their profile to be migrated. Any email address accepted by your identity provider can be used for subsequent logins.