This guide will show how to configure Matillion to use Active Directory for authentication and authorisation.
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.
Authorisation in Matillion
Matillion authorisation supports four roles which allow users to access specific aspects of the product.
- Emerald: This role allows access to the ETL interface. Typically all users have this role.
- Server Admin: This role allows a user to access the Admin menu.
- Global Project Admin:This role allows a user to access to every project.
- API: this role allows a user to use Matillion ETL API.
In the context of LDAP integration, four usergroups will be created that can be mapped to the above roles. For this example, I have created four usergroups in our AD—Emerald, Emerald Admin, Emerald Project Admin, Emerald API.
Provide names or a valid naming convention for the above groups (the names above are merely used as an example). Also, having four separate usergroups is not necessary. Depending on requirements, a single usergroup may be mapped to all four roles.
Take a backup of the following files to ensure previous configuration can be restored, if required:
Alternatively, a snapshot of the instance can also be taken prior to making any 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.
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)
When issuing queries to the Global Catalogue for larger Active Directories (or when experiencing timeouts waiting for Active Directory to response), it can be beneficial to use Port 3268 (LDAP) or 3269 (LDAPS)
Emerald, Emerald Admin, Emerald Project Admin, Emerald API
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 usergroups in Active Directory are held in containers or organisational units (OU) managed by the domain administrator. The above setup ensures the users and usergroups are in the users' containers, however any number of different configurations may be applied. Ideally, try to keep the users and usergroups in the same containers/OU.
The distinguished name of the container/OU in which users and usergroups are categorised will need to be provided. For example, the distinguished name for the Users container in this setup is
- Click Admin in thr top right corner of Matillion ETL, then click User Configuration.
- Select EXTERNAL from Security Configuration at the top of the User Configuration pop-up window.
- Provide details as described in 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":
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:
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:
User Search The attribute to search for user names (leave this unchanged):
Role Base The part of the directory tree to begin searching for groups/roles—similar to User Base above, change this appropriately if Matillion usergroups are in a different container to users:
Role Name The name of the attribute containing the role name (leave this unchanged):
Role Search How to find all the roles for a user (leave this unchanged):
METL Role Name The role a user must be a member of to gain access to the Matillion ETL application:
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, but is not required to be, different to the METL Role Name:
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:
- Click Save Configuration.
- Restart Tomcat.
Login to Matillion
Once Tomcat is restarted, users may now use the assigned Active Directory username and password to login.
The domain does not need to be specified as part of the username—for example, "domain\\username" or "email@example.com".