LDAP Integration

Overview

Matillion supports 3 authentication models – NONE, INTERNAL (default) and EXTERNAL

By default (from v1.25.1) users in Matillion are authenticated against an INTERNAL user file however it is possible to authenticate users against an Active Directory or other LDAP directory server.

This document will guide you through the process of configuring Matillion to use your Active Directory for Authentication and Authorization.
 

Authorization in Matillion

Matillion supports three roles which allow a user to access specific aspects of the product.

  1. Emerald: This role allows access to the ETL interface. Typically all users have this role.
  2. Admin: This role allows a user to access the admin page.
  3. API: this role allows a user to use Matillion ETL API.

In the context of LDAP integration, we will create three usergroups that can be mapped to the above roles. For this example, I have created 3-usergroups in our AD – Emerald, Emerald Admin, Emerald API.

You are free to choose any names or (valid) naming convention for these groups and are not required to use the ones stated above. Also, having 3 separate usergroups is not necessary. Depending on your requirement, you may map a single usergroup to all three roles.
 

Take Backups

Take a backup of the following files so we can restore previous configuration 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

Another option is to take a snapshot of your instance prior to making changes and restore it if required.
 

Undo changes

If you are able to access Admin page and would like to switch back to Internal-database, then do so from the Admin page. Click on Internal, Click Save Configuration and restart Tomcat/Ec2-Instance.

If you are unable to restore from Admin Page, replace the files server.xml and tomcat-users.xml and restart tomcat.

You may also choose to restore to a snapshot assuming its not too old. Any changes to jobs or configuration made since the snapshot was taken would be lost.
 

LDAP Setup

This section talks about the details you need from your LDAP/Domain.

Ldap server          test.mtln.com, accessible on port 389 or 636 for SSL.
                              Use IP address if your domain is not accessible by name.

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

Usergroups          Emerald, Emerald Admin, Emerald API.

Users                    I have created 3-users and added them to the usergroups as shown below

 
Username UserGroup
ec2-user Emerald, Emerald Admin, Emerald API
etl-user Emerald
api-user Emerald API
 

Users and Usergroups in AD are held in Containers or Organisational Units(OU) managed by your domain administrator. My setup has the users and usergroups in the Users container. You are free to choose a different container/OU to hold your users/usergroups. Ideally, keep the Users and Usergroups in the same container/OU.

You will be required to provide the distinguished name of the container/OU that has your users and usergroups. For example, the distinguished name for the USERS container in my setup is - CN=Users,DC=test,DC=mtln,DC=com
 

Configuring Matillion

  1. Login to Matillion admin page.
  2. Under Security Configuration, click EXTERNAL
  3. Provide details as described in table below.
  4. Click Save Configuration
  5. Restart Tomcat (top-right)
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.
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 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 as-is.
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 as-is.

cn
Role Search How to find all the roles for a user. Leave this as-is.
member={0}
METL Role Name The role a user must be a member of to gain access to the Matillion ETL application.
Emerald
METL Admin Role Name The role a user must be a member of to gain access to the Matillion ETL administration page – this can be different to the METL Role Name but is not required to be.
Emerald Admin
API Group Name The role a user must be a member of to gain access to the Matillion ETL API – this can be different to the METL Role Name but is not required to be.
Emerald API

 

Login to Matillion

Once tomcat is restarted, the users may now use their AD username and password to login. Please note, there is no need to specify the domain name (e.g. domain\username or username@domain.com).