Skip to content

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.

  1. SSH into your Matillion ETL instance.
  2. Open the following file for editing: /usr/share/emerald/WEB-INF/classes/Emerald.properties

  3. Ensure the following variables are set:

    VARIABLE_AUTHENTICATION=true
STATELESS_CONFIGURATION=true

  4. Save and close the file.

  5. Open the following file for editing: /etc/sysconfig/tomcat

  6. 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

  7. 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.

  1. SSH into your Matillion ETL instance.
  2. Open the following file for editing: /usr/share/emerald/WEB-INF/classes/Emerald.properties

  3. 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}

  4. Save and close the file.

  5. Open the following file for editing: /usr/share/tomcat/bin/setenv.sh

  6. 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"

  7. Save and close the file.

  8. The server must now be restarted for your changes to take effect.
  9. 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.

  1. SSH into your Matillion ETL instance.
  2. Open the following file for editing: /usr/share/emerald/WEB-INF/classes/Emerald.properties

  3. 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.

  4. Save and close the file.

  5. The server must now be restarted for your changes to take effect.
  6. 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.

  1. SSH into your Matillion ETL instance.
  2. Open the following file for editing: /usr/share/emerald/WEB-INF/classes/Emerald.properties
  3. 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.|
  1. Save and close the file.
  2. 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.