Configuring stateless authentication
This article outlines how authentication can be configured using environment variables for Matillion ETL. This allows Matillion ETL usernames and password to be stored in the Matillion database instead of in the tomcat-users.xml
, which is the default for an installation. This is especially useful if a customer is running a high availability setup and wishes to keep the usernames and password details in sync between servers (nodes in a cluster), as they will be using the shared database, where this configuration is stored.
Users must first follow the advice in Enabling stateless authentication, then choose either the Internal Security, OpenID, or LDAP integration section, depending on their desired setup. These are mutually exclusive options.
Note
We advise always taking a backup of the below files before beginning this process as they will be required to revert the configuration if required.
/usr/share/emerald/WEB-INF/classes/Emerald.properties
/etc/tomcat/server.xml
Enabling stateless authentication
Before configuring OpenID or LDAP, your Matillion ETL instance must have stateless authentication enabled using environment variables. For IaC deployments, it may be preferable to set these using a post-deployment script.
- SSH into your Matillion ETL instance.
- Open the following file for editing:
/usr/share/emerald/WEB-INF/classes/Emerald.properties
-
Ensure the following variables are set:
VARIABLE_AUTHENTICATION=true STATELESS_CONFIGURATION=true
-
Save and close the file.
- Open the following file for editing:
/etc/sysconfig/tomcat
-
Ensure the following variables are set:
MTLN_PERSISTENCE_URL_POSTGRES="jdbc:postgresql://<DatabaseAddress>:<Port>/DatabaseName" MTLN_PERSISTENCE_USERNAME_POSTGRES=<username> MTLN_PERSISTENCE_PASSWORD_POSTGRES=<password>
Where the
MTLN_PERSISTENCE_URL_POSTGRES
address points to the FQDN of your persistence database and a port may or may not be required, depending on your setup. HA/clustered deployments will be required to provide details for their external Postgres database. For single-node deployments, this database is typically on the instance itself and should have the following values:MTLN_PERSISTENCE_URL_POSTGRES="jdbc:postgresql://127.0.0.1/postgres" MTLN_PERSISTENCE_USERNAME_POSTGRES=postgres MTLN_PERSISTENCE_PASSWORD_POSTGRES=postgres
-
Save and close the file.
Internal Security
Before following the advice in this section, please ensure the steps in Enabling stateless authentication have been completed.
Internal Security is the built-in user configuration option for Matillion ETL that requires no outside systems for managing user logins.
- SSH into your Matillion ETL instance.
- Open the following file for editing:
/usr/share/emerald/WEB-INF/classes/Emerald.properties
-
Ensure the following variables are set:
VARIABLE_AUTHENTICATION=true STATELESS_CONFIGURATION=true STATELESS_PROTOCOL_TYPE=BOTH STATELESS_OPENID_ENABLE=true DEFAULT_TOMCAT_USER_USERNAME=${whatever you like} DEFAULT_TOMCAT_USER_PASSWORD=${whatever you like}
-
Save and close the file.
- Open the following file for editing:
/usr/share/tomcat/bin/setenv.sh
-
Ensure the following variables are set:
export MTLN_PERSISTENCE_STORE_NAME=postgres export MTLN_PERSISTENCE_USERNAME_POSTGRES=postgres export MTLN_PERSISTENCE_PASSWORD_POSTGRES=postgres export MTLN_PERSISTENCE_URL_POSTGRES="jdbc:postgresql://127.0.0.1/postgres"
-
Save and close the file.
- The server must now be restarted for your changes to take effect.
- Users can now be added in the Admin → User Configuration menu.
OpenID integration
Before following the advice in this section, please ensure the steps in Enabling stateless authentication have been completed.
OpenID is the choice for those who want to manage their Matillion ETL users via the in-instance User Configuration dialog and require no external services. Using OpenID removes the ability to use LDAP and so those following the advice in this section should ignore the advice in LDAP integration.
- SSH into your Matillion ETL instance.
- Open the following file for editing:
/usr/share/emerald/WEB-INF/classes/Emerald.properties
-
Ensure the following variables are set:
Property Example Value Notes DEFAULT_TOMCAT_USER_USERNAME <username>
If deleted manually, this user will be recreated upon restarting the instance(s). DEFAULT_TOMCAT_USER_PASSWORD <password>
Desired default user's password. STATELESS_OPENID_ENABLE true This property must be set to true STATELESS_OPENID_PROVIDER GENERIC Valid values are: GENERIC, AZURE, GOOGLE, MICROSOFT and OKTA. STATELESS_PROTOCOL_TYPE HTTPS Valid values are: HTTP, HTTPS and BOTH. STATELESS_OPENID_ENDPOINT https://<idp-fqdn>/...
The chosen OpenID Identity Provider's base URL. STATELESS_OPENID_ID <client-id>
Usually referred to as the "client ID". SEC_STATELESS_OPENID_SECRET <client-secret>
Usually referred to as the "client secret" or "secret value". STATELESS_OPENID_SCOPE <open-id-scope>
See the documentation for each provider's suggested/default scope. STATELESS_OPENID_ATTRIBUTE <open-id-attributes>
See the documentation for each provider's suggested/default attribute. -
Save and close the file.
- The server must now be restarted for your changes to take effect.
- Users can now be added in the Admin → User Configuration menu.
LDAP integration
Before following the advice in this section, please ensure the steps in Enabling stateless authentication have been completed.
LDAP is the choice for those who want to manage their Matillion ETL users via an external directory. Using LDAP removes the ability to use openID and so those following the advice in this section should ignore the advice in OpenID integration.
It may be instructive to read the documentation on LDAP Integration for users who are familiar with setting up LDAP within the External security dialog in Matillion ETL before attempting these changes.
- SSH into your Matillion ETL instance.
- Open the following file for editing:
/usr/share/emerald/WEB-INF/classes/Emerald.properties
- Ensure the following variables are set:
LDAP variables:
|Variable|Description|
|---|---|
|STATELESS_LDAP_ENABLE|Must be set to **true**|
|STATELESS_LDAP_NAME|The name of a user to make the initial bind to the directory. This could be any LDAP user. For Active Directory, the name must include a realm using the form ```user@REALM```.|
|SEC_STATELESS_LDAP_PASSWORD|The password for the user to make the initial bind to the directory. We advise against using "special characters" in passwords.|
|STATELESS_LDAP_KEY||
|STATELESS_LDAP_URL|The location of the directory server. ```ldap://<LDAP-server>:<port>```. Use port **389** for non-SSL and port **636** for SSL.|
|STATELESS_LDAP_BASES|The part of the directory tree to begin searching for users. Typically users are created in the Users Container/OU.|
|STATELESS_LDAP_SEARCH|The attribute to search for user names.|
|STATELESS_LDAP_ROLEBASE|The part of the directory tree to begin searching for groups/roles�similar to User Base above, change this appropriately if Matillion ETL user groups are in a different container.|
|STATELESS_LDAP_ROLENAME|The name of the attribute containing the role name.|
|STATELESS_LDAP_ROLESEARCH|The attribute to search for roles.|
|STATELESS_LDAP_ACCESS|The role that allows access to the Matillion ETL application. e.g. **Emerald**|
|STATELESS_LDAP_ADMIN|The role that allows administrator access to the Matillion ETL application. e.g. **Emerald_Admin**|
|STATELESS_LDAP_PROJECTADMIN|The role that allows Project administrator access to the Matillion ETL application. e.g. **Emerald_Project_Admin**|
|STATELESS_LDAP_API|The role that allows Matillion ETL API access. e.g. **Emerald_API**|
|STATELESS_LDAP_READONLY|The role that allows read-only access to the Matillion ETL application. e.g. **Emerald_Read_Only**|
|STATELESS_LDAP_NESTED|false|
|STATELESS_LDAP_ROLESUBTREE|Sets the scope of the role search. Select true if you wish to search the entire subtree, rooted at the "User Base" entry. Selecting false (default) requests a lone top-level search.|
|STATELESS_LDAP_USERSUBTREE|Sets the scope of the user search. Select true if you wish to search the entire subtree, rooted at the "User Base" entry. Selecting false (default) requests a lone top-level search.|
- Save and close the file.
- If this is done before launching the instance then there is no need for a restart. Otherwise, restart your server for the changes to take effect.