LDAP Integration
  • Dark
    Light
  • PDF

LDAP Integration

  • Dark
    Light
  • PDF

Important Notice

Overview

This guide explains how to configure Matillion ETL to use Active Directory for authentication and authorization.

Matillion supports three authentication models:

  1. NONE
  2. INTERNAL (default)
  3. EXTERNAL

By default, Matillion ETL users are authenticated against an internal user file. However, it is possible to authenticate users against an Active Directory or another LDAP directory server.

Please Note

To configure external settings for Okta LDAP integration, please follow the steps in this document until you reach Configuring Matillion, then follow Configuring Matillion ETL in Okta LDAP Configuration.



Authorization in Matillion

Matillion ETL authorization supports four roles that allow users to access specific aspects of the product:

  1. Emerald: this role allows access to the Matillion ETL interface. Typically, all users have this role.
  2. Server Admin: this role allows a user to access the Admin menu.
  3. Global Project Admin: this role allows a user to access every project.
  4. API: this role allows a user to use the Matillion ETL API.

In the context of LDAP integration, four user groups will be created that can be mapped to the above roles. For this example, four user groups have been created in Active Directory:

  1. Emerald
  2. Emerald Admin
  3. Emerald Project Admin
  4. Emerald API

Provide names or a valid naming convention for the above groups (the names above are used as an example). Also, having four separate user groups is not necessary. Depending on requirements, a single user group may be mapped to all four roles.


Backup files

Take a backup of the following five files to ensure the previous configuration can be restored, if required:

  1. /etc/tomcat8/server.xml

  2. /etc/tomcat8/tomcat-users.xml

  3. /usr/share/emerald/WEB-INF/classes/admin.properties.aws

    /usr/share/emerald/WEB-INF/classes/admin.properties.gcp

  4. /usr/share/emerald/WEB-INF/classes/Emerald.properties

  5. /usr/share/emerald/WEB-INF/security.fragment

Please Note

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


Undo changes

  • Switch back to the Instance-database via the Admin menu:

    Click Internal, then click Save Configuration and restart Tomcat/Ec2-Instance.

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

  • 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

Below, find the details required from the LDAP/Domain:

  • LDAP server:

    test.mtln.com is accessible on port 389 or 636 for SSL (Use an IP address if a domain is not accessible by name)

    Please 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)

  • Usergroups

    Emerald, Emerald Admin, Emerald Project Admin, Emerald API

  • Users

    Four users have been created and added to the usergroups as shown below

    Username Usergroup
    ec2-user Emerald, Emerald Admin, Emerald Project Admin, Emerald API
    etl-admin Emerald Project Admin
    etl-user Emerald
    api-user Emerald API

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.

Please 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

Please Note

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


1. Click Admin Menu User Configuration in the top right corner of the Matillion ETL.

2. Select EXTERNAL from Security Configuration at the top of the User Configuration pop-up window.

3. Provide details as described in the table below:

Parameter Description
Connection Name The name of a user to make the initial bind to the directory. This could be any AD user. For active directory, that will include a realm using the form "user@REALM":
ec2-user@test.mtln.com
Connection Password The password for the user to make the initial bind to the directory.
Warning: we advise against using "special characters" in passwords—any character above #128 in either of these lists may cause issues:
  1. Windows
  2. MacOS
Connection URL The location of the directory server, using one of the forms below:
For non SSL: ldap://test.mtln.com:389
For SSL: ldaps://test.mtln.com: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 Base The part of the directory tree to begin searching for groups/roles— similar to User Base above, change this appropriately if Matillion user groups are in a different container to users:
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 The role to gain access to the Matillion ETL application:
Emerald
METL Server Admin The role to gain access to the Matillion ETL administration page - this maybe different to the METL Access role name:
Emerald Admin
METL Global Project Admin This role allows a user to access every project::
Emerald Project Admin
API The role to gain access to the Matillion ETL API - this maybe different from the METL Access role name:
Emerald API

4. Click Save Configuration.

5. Restart Tomcat.

User Configuration

Log in to Matillion

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

Please Note

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

Matillion ETL login screen