SAML in Matillion ETL

SAML (Security Assertion Markup Language) is an open standard used for authentication. Using the SAML format, authentication information is transferred between Matillion ETL and a third-party identity provider in order to achieve a simple and secure single sign-on (SSO) to Matillion ETL.

The SAML authentication process means that users don't need to remember multiple usernames and passwords to their different applications, and increases security by avoiding the need to store passwords on the application platform.

SAML is not configured on Matillion ETL instances by default. This article describes the steps needed to set it up on your instance.

The configuration requires several steps that you must perform in order:

Create a keystore and export a certificate file.
Configure Matillion ETL to use SAML.
Configure your chosen identity provider to recognize Matillion ETL.
Configure the Matillion ETL server to recognize your identity provider.

These steps are detailed in the following sections.

Note

The SAML configuration process is complex, and should not be attempted without basic Linux command line technical skills and familiarity with manually editing configuration files. You will also require a basic understanding of private/public keys, encryption, and keystores.

Details of configuring the identity provider beyond the SAML configuration itself is outside the scope of this article. It's assumed that you already have, or are able to build, the required identity provider infrastructure.

Prerequisites

Before you begin this process, ensure that you have:

Credentials to log in (via SSH) to the server that Matillion ETL runs on.
Credentials to log in to Matillion ETL.
Credentials to log in to your identity provider, with permissions to create and configure SAML applications.

Create a keystore file

A key principle of SAML is the exchange of public keys. To enable this, Matillion ETL uses a keystore file to store the private/public keypair and RSA public key.

Several command line and GUI tools are available for managing keystores. You can use whichever method you are comfortable with.

Create using your preferred GUI keystore tool

Our examples use KeyStore Explorer, which is free and available for all platforms. However, the following instructions are given generically so that you can adapt them to your chosen tool.

Create a new JKS keystore. We use metl.jks as the default keystore filename.
Set a keystore password, and note this password for later use.
Create a new keypair, with the following suggested parameters:
- RSA key size: 2048.
- Certificate version: 3.
- Signature algorithm: SHA-256 with RSA.
- Validity period: 1 year is recommended.
Create a keypair alias, and note it for later use.
Create a keypair password, and note it for later use.
Export the keypair into a certificate file, with the following parameters:
- Export length: Head only.
- Export format: X.509.
- PEM: Yes.
- Export file name: metl.cer.

Create from the command line

Create the keystore:

keytool -genkey -v -keystore metl.jks -alias MatillionSAML -keyalg RSA -keysize 2048 -validity 365

Export the certificate:

 keytool -exportcert -keystore metl.jks -alias MatillionSAML -file metl.cer

Configure Matillion ETL

Matillion ETL is configured in two stages. First, complete the following steps before configuring your identity provider, then you will return to Matillion ETL to complete the configuration once your identity provider is configured.

Log in to the Matillion ETL EC2 instance using SSH or EC2 Connect in the AWS console.
Edit the file /usr/share/emerald/WEB-INF/classes/Emerald.properties, after first making a backup copy.
Locate the following line in the file, or add it if it does not exist:
```
FEATURE_SWITCHES=DASHBOARD_TELEMETRY,DYNAMIC_PYTHON_SELECTION
```

To this line, add SAML_AUTHENTICATION, as follows:

FEATURE_SWITCHES=DASHBOARD_TELEMETRY,DYNAMIC_PYTHON_SELECTION,SAML_AUTHENTICATION

Save the file.
Restart the Tomcat server.
Log in to the Matillion ETL instance and select User Configuration from the Admin menu.
Select Internal security configuration and click the SAML Login tab.
Select Activate SAML.

Alternatively, you can enable SAML from within the Matillion ETL client. Read Manage optional features for details.

Configure your identity provider

SAML in Matillion ETL is identity-provider agnostic, meaning that it will work with any identity provider that supports the protocol. The following instructions are given generically so that you can adapt them to your chosen identity provider.

In your identity provider app or portal, create a SAML application for Matillion ETL, with the following settings.
Select IdP-initiated workflow.
Set the ACS URL to the following: https://<your-metl-domain>/saml_response_consumer.jsp, where <your-metl-domain> is taken from the URL of your Matillion ETL instance.
Set the SP Entity ID to emerald.
Copy the Identity Provider URL for use in the final Matillion ETL configuration.
In advanced configuration settings, you can set different signing and encryption settings. These settings need to match your Matillion ETL settings and use the previously exported Matillion ETL certificate file. Set the following parameters:
- Select SP signs SAML requests, and choose the metl.cer certificate file.
- Select IdP signs assertion within response.
- Select Encrypt assertion, and choose the metl.cer certificate file.
Under User Identity, specify which user property in the identity provider is aligned with the Matillion ETL username. For example, if you select emailAddress, then the email address in the identity provider must be identical to the Matillion ETL user name. Any difference in the property value will cause login to fail.

Complete Matillion ETL configuration

Log in to the Matillion ETL EC2 instance using SSH or EC2 Connect in the AWS console.
Copy the keystore file, metl.jks, from your local environment to the /etc/tomcat/ directory.

Edit the file /usr/share/emerald/WEB-INF/classes/Emerald.properties to include the following parameters. Note that the exact settings will depend on your configuration choices in the previous sections.

Parameter	Value
SAML2.IdPEntityId	The identity provider ID.
SAML2.IdPURL	`https://<IdP-URL>` where `<Id-PURL>` is the identity provider URL.
SAML2.SPEntityId	The service provider entity ID (`emerald` in our example).
SAML2.IdPPublicCertAlias	The alias or name of the identity provider's certificate in the keystore.
SAML2.KeyStorePassword	The keystore's password.
SAML2.PrivateKeyAlias	The alias or name of Matillion ETL's certificate in the keystore.
SAML2.PrivateKeyPassword	The password of Matillion ETL's certificate in the keystore.
SAML2.CertFileName	The certificate filename. The default is `metl.jks`.
SAML2.TomcatCertPath	The certificate file's absolute path, the default is `/etc/tomcat/`.
SAML2.EnableAssertionSigning	Enable assertion signing. The recommended value is `true`.
SAML2.EnableAssertionEncryption	Enable assertion encryption. The recommended value is `true`.
SAML2.EnableResponseSigning	Set to `true`. If you get the error "SAML2 Response signing is enabled, but the signature element not found in SAML2 Response element", set to `false`.

Add the certificate referred to by SAML2.IdPPublicCertAlias to the keystore:

sudo /usr/lib/jvm/jre/bin/keytool -import -keystore /etc/tomcat/metl.jks -v -alias providercert -file [nameofcert] -trustcacerts

Restart the Tomcat server.

Log in to Matillion ETL with SAML

With the configuration completed, you can now log in to Matillion ETL using SAML via your third-party identity provider.

Currently, we only support an identity provider initiated authentication flow. This means the user must log in to the Matillion ETL instance using the identity provider's UI. We don't provide a SAML login from within the Matillion ETL UI.

The login mechanism will depend on your identity provider, but you should find a tile or icon representing Matillion ETL within your identity provider's app or portal. Click this to be taken directly into your Matillion ETL instance without the need for entering any additional login credentials.