Skip to content

LDAP integration

Matillion ETL supports LDAP integration through the External User Configuration option. Users can link to an existing LDAP (Lightweight Directory Access Protocol) directory server such as OpenLDAP or Microsoft Active Directory.

Matillion ETL uses LDAP role names to map LDAP roles to its own roles as defined in Groups and Permissions. Some pre-defined roles used by Matillion ETL to give high-level access—such as instance administration—must be created in the LDAP directory.

This guide explains how to configure Matillion ETL to use Active Directory for authentication when 'External' authentication has been selected.

Note

  • If you are using Azure Active Directory as your authentication provider, you must configure Azure Active Directory Domain Services. To learn how, read LDAP authentication with Azure Active Directory.
  • To configure external settings for Okta LDAP integration, follow the steps in this document until you reach configure, then follow Configuring Matillion ETL in Okta LDAP Configuration.

Authorization in Matillion ETL

Matillion ETL authorization requires five roles that allow users to access specific aspects of the product:

  • Emerald: Allows access to the Matillion ETL interface. Typically, all users have this role.
  • Server Admin: Allows a user to access the Admin menu.
  • Global Project Admin: Allows a user to access every project.
  • API: Allows a user to use the Matillion ETL API.
  • Read Only: This user has read only access and can't change any jobs or settings. This feature is only available on Matillion ETL instances initiated via the Hub. To learn more, read Read Only Users.

For LDAP integration, you must create LDAP user groups that can be mapped to these Matillion ETL access roles. For example purposes, we will create five user groups in Active Directory as follows:

  • Emerald
  • Emerald Admin
  • Emerald Project Admin
  • Emerald API
  • Emerald Read Only

You should determine what user groups you will require. You may not need five separate groups as illustrated in this example. Depending on your requirements, a single user group may be mapped to all five roles. You should provide suitable names or a valid naming convention for your groups.

Note

The user groups above are for illustrative purposes only.

Any LDAP group that can be found from the Role Base provided during LDAP configuration can be used to map to existing or custom Matillion Groups and Permissions, as described in the article Groups and Permissions, and this mapping is completely independent of LDAP role mapping. As best practice we recommend that these two functions use different LDAP groups: an LDAP group used to map to Matillion ETL groups and permissions shouldn't also be used to map to a Matillion ETL access role as described here.

Backup files

Before making any changes to LDAP configuration, take a backup of the following files to ensure the previous configuration can be restored if required:

  • /etc/tomcat/server.xml
  • /etc/tomcat/tomcat-users.xml
  • /usr/share/emerald/WEB-INF/classes/Emerald.properties
  • /usr/share/emerald/WEB-INF/security.fragment
  • Snowflake and Redshift users: /usr/share/emerald/WEB-INF/classes/admin.properties.aws
  • BigQuery users: /usr/share/emerald/WEB-INF/classes/admin.properties.gcp

Alternatively, a snapshot of the instance can be taken before making any changes.

Undo changes

If necessary, you can use the following methods to undo any changes and revert to the previous state.

  1. Switch back to the instance database via the Admin menu: Click Internal, then click Save Configuration and restart Tomcat/Ec2-Instance.
  2. If access to the Admin menu is unavailable: Restore the server.xml and tomcat-users.xml files from the backups made earlier, and restart Tomcat.
  3. Restore from a snapshot: When choosing to restore from a snapshot, keep in mind that if the snapshot is too old, any changes to jobs or configurations made before the snapshot will be lost.

LDAP setup

The following details are required from the LDAP/Domain to enable the integration we're setting up in this example:

LDAP server

You will need an LDAP server accessible on port 389 or 636 for SSL.

Note

When issuing queries to the Global Catalogue for larger Active Directories (or when experiencing timeouts waiting for Active Directory to respond), it can be beneficial to use Port 3268 (LDAP) or 3269 (LDAPS).

User groups

  • Emerald
  • Emerald Admin
  • Emerald Project Admin
  • Emerald API
  • Emerald Read Only

Users

Five users have been created and added to the user groups as shown below.

Username User group
ec2-user Emerald, Emerald Admin, Emerald Project Admin, Emerald API
etl-admin Emerald Project Admin
etl-user Emerald, Emerald Read Only
api-user Emerald API
readonly-user Emerald Read Only

Users and user groups in Active Directory are held in containers or organizational units (OU) managed by the domain administrator. The above setup ensures the users and user groups are in the users' containers, however, any number of different configurations may be applied. Ideally, try to keep the users and user groups in the same containers/OU.

Note

The distinguished name of the container/OU in which users and user groups are categorized will need to be provided. For example, the distinguished name for the Users container in this setup is CN=Users,DC=test,DC=mtln,DC=com

Configuring Matillion ETL

Note

To configure Okta LDAP integration, refer to Configuring Matillion ETL in Okta LDAP Configuration.

  1. Click Admin → User Configuration in the top-right of the Matillion ETL interface.
  2. Select External from the Security Configuration drop-down menu at the top.

  3. Complete the following details:

    Parameter Description
    Connection 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.
    Connection Password The password for the user to make the initial bind to the directory. We advise against using "special characters" in passwords—any character above #128 in either of these lists may cause issues: Windows; MacOS.
    Encryption Key A list of KMS keys that are used to encrypt connection passwords.
    Connection URL The location of the directory server, using one of the following forms: For non-SSL: ldap://<LDAP-server>:389 and For SSL: ldaps://<LDAP-server>:636.
    User Base The part of the directory tree to begin searching for users. Typically users are created in the Users Container/OU. Change this as appropriate if Matillion ETL users are held in a different container: CN=users,DC=test,DC=mtln,DC=com
    User Search The attribute to search for user names (leave this unchanged): sAMAccountName={0}
    Role Bases 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: CN=Users,DC=test,DC=mtln,DC=com
    Role Name The name of the attribute containing the role name (leave this unchanged): cn
    Role Search How to find all the roles for a user (leave this unchanged): member={0}
    METL Access This role allows access to the Matillion ETL application: Emerald
    METL Server Admin This role allows access to the Matillion ETL administration page. This may be different from the METL Access role name: Emerald Admin
    METL Global Project Admin This role allows a user to access every project: Emerald Project Admin
    API This role allows access to the Matillion ETL API. This maybe different from the METL Access role name: Emerald API
    Options Use the radio buttons to select from Allow Nested Roles, Role Subtree, or User Subtree. For more information about these options, see below.
    Read Only This role allows read-only access to Matillion ETL: Emerald Read Only.

    There are three optional parameters to choose from:

    • Allow Nested Roles: If your users are defined in a nested group, checking this box will allow those users to inherit the relevant permissions.
    • Role Subtree: Sets the scope of the search. Tick the checkbox if you want to search the entire subtree rooted at the roleBase level. If you choose to leave this box un-ticked, the search scope requests a lone top-level search.
    • User Subtree: Sets the scope of the search. Tick the checkbox is you want to search the entire subtree, rooted at the userBase level. If you choose to leave this box un-ticked, the search scope requests a lone top-level search.

  4. To test the configuration, click Test at the bottom of the dialog, then click OK. You can't click OK until a successful test is completed.

  5. Restart Tomcat.

Log in to Matillion ETL

Once Tomcat is restarted, users may now use the assigned Active Directory username and password to log in to Matillion ETL.

Note

The domain doesn't need to be specified as part of the username—for example, "domain\username" or "username@domain.com".