Skip to content

User Configuration

User Configuration allows Matillion ETL instance admins to define the user list for that instance, along with some basic permissions for those users. To open the User Configurations dialog, click Admin → User Configuration.

There are three types of security options available for user configurations. - Internal - External - None

New users can't access projects in Matillion ETL until they have logged in at least once—admins should try to make sure that this protocol is followed. The suggested steps to follow are:

  1. Ensure that any "sensitive" projects are not set to "Public Users" under the Manage Users tab in the User Configuration dialog. Doing this will prevent a user from automatically having visibility of those projects.
  2. Create a new user in Matillion ETL via AdminUser Configuration.
  3. Ask the newly created user to log in and then log out.
  4. The admin should then log in as an admin, and navigate to ProjectManage Project.
  5. Enable relevant project access to the new user.


When selecting Internal, the Matillion ETL instance will use an instance-based database of username, passwords, and privileges. Users can be added, removed, and modified in the Manage Users tab.

Adding Users

Click + in the bottom left of the dialog and complete the fields.

  • Full Name: A name to easily identify the user.
  • Username: Provide the username as per your choice.
  • Password | Repeat Password: Enter the password and confirm it.
  • Role: These are the user roles that allow users to be configured as:
    • Server Admin: Allows the user access to the Admin menu and all admin-related features therein.
    • API: Allows the user to use the Matillion v0 and v1 APIs.
    • Global Project Admin: Allows the user to read and access all projects on the instance regardless of the project's access settings.
    • Read-Only: Restricts user access. Anyone assigned to this role can't modify jobs or settings. This feature is only available on Matillion ETL instances that are initiated via Hub. For more information, refer to Read Only Users.
  • Permission Groups: Select the appropriate group for the intended user. You must select at least one Permission Group for each user. For more information about these groups and their purpose, see Groups and Permissions.

Click OK. Remember to Apply changes to confirm the new user creation.

Deleting Users

You can remove any existing user by clicking the delete button to the right of the relevant user's name. It will ask you for the confirmation to remove the user.

User passwords

Click the password icon in the relevant user entry to open the Edit Password dialog. From here, enter a new password and repeat it to confirm, then click OK.

Passwords entered in User Configuration are stored as SHA512 hashes. If manually editing a password, either via the database or the API, the desired password must be supplied as an SHA512 hash.

Passwords can:

  • Contain between 12 and 128 characters.
  • Contain any printable Unicode characters.
  • Be denied if matched against leaked or common passwords.
  • Be denied if they're too simple, such as matching simple patterns.


Via the OpenID Connect Login tab, internal users can be configured using an OpenID login and connected to an internal user profile. See OpenID Setup for more information.

Any changes made to this dialog must be confirmed by clicking Apply changes.


When selecting External, the Matillion ETL instance will link to an existing directory server. For example: OpenLDAP (Lightweight Directory Access Protocol) or Microsoft Active Directory.

Your Matillion ETL instance will require restarting for changes to apply.

If any issues occur during user configuration, please refer to Reverting from External to Internal Security for more details.

Opting to use external security will prevent existing users configured in internal security from logging in.

Adding users

Users can be configured by completing the Set Realm Parameters form, which allows users to use LDAP integration to grant and prevent access to users on a Matillion ETL instance.

The Set Realm Parameters and their descriptions are given below:

Parameter Description
Connection Name The name of a user to make the initial bind to the directory (for Active Directory, include a realm using the form "user@REALM". For example, exampleuser@EXAMPLE.COM.
Connection Password The password for the user to make the initial bind to the directory.
Encryption Key A list of KMS keys that the user has access to for encrypting connection passwords.
Connection URL The location of the directory server, using one of the forms below: For non-SSL ldap://<hostname>:389 / For SSL ldaps://<hostname>:636.
User Base The part of the directory tree to begin searching for users.
User Search The attribute to search for user names.
Role Base The part of the directory tree to begin searching for groups/roles (often the same place as users).
Role Name The name of the attribute containing the role name.
Role Search How to find all the roles for a user.
METL Access The role a user must be a member of to gain access to the Matillion ETL application
METL Server Admin The role a user must be a member of to gain access to the Matillion ETL administration page (this can be different from the METL Role Name)
METL Global Project Admin The role a user must be a member of to gain access to the Matillion ETL project administration (this can be different from the METL Role Name)
API The role a user must be a member of to gain access to the Matillion ETL API (this can be different from the METL Role Name)

Removing users

Any user that has logged into a Matillion ETL instance is stored in the Access Control List on the Manage Project window and will remain there even after logging out. To remove a user from the Access Control List, click X to the right of the user's name. If currently logged in, this user will be forced to log out and disconnect from the instance.


When selecting None, the Matillion ETL instance will essentially provide no control over who can access the Matillion ETL instance. As best practice, this option is never recommended, especially for users whose instances are publicly available.