Skip to content

Microsoft Active Directory OpenID setup


This guide will show you how to set up an OpenID login on Matillion ETL using Microsoft Active Directory Domain Services credentials. This includes acquiring credentials from Microsoft Active Directory, setting up internal security in the User Configuration dialog, and then managing users and logging in with the OpenID credentials.


  • Only credentials from a single provider can be used per instance.
  • Matillion ETL users must be created with the same login name as any expected OpenID login.
  • Valid OpenID setups may fail if the Matillion ETL instance is behind a load balancer (usually due to the incorrect detection of scheme and port). We recommend that a listener is setup on the ELB for port 443 instead of 80 to remedy the issue.
  • Microsoft Active Directory Domain Services (AD) is the legacy version of Azure Active Directory (AAD), and Azure Active Directory should be preferred for all new deployments. :::

Acquiring credentials for Microsoft Active Directory

  1. Log in to the Azure Portal. Click App registrations on the Azure services menu at the top of the dashboard.
  2. In the search bar at the top of the screen enter Active Directory and select your Active Directory service from the search results.
  3. Click App registrations in the sidebar menu.
  4. In App registrations, click + New registration in the menu at the top.
  5. In the Register an application dialog, provide details for the following fields, then click Register:
    • Name: Provide a name for the app.
    • Redirect URI: Provide an https URL for the Matillion ETL instance, appended with /j_security_check. For example:
  6. You will then see the Overview screen of the app's dashboard. Copy the Application (client) ID and Directory (tenant) ID credentials. You will need these when you set up internal security in Matillion ETL.

:::info{title='Note'} When you copy the credentials, some browsers may add a space to the end of them. Pay close attention to this because it will cause the credentials to fail. :::

  1. Click Certificates & secrets in the sidebar on the left. Then, in the Certificates & secrets dialog, click New client secret.
  2. The Add a client secret dialog will appear. Provide details for the following fields:
    • Description: Provide a description of the client secret.
    • Expires: Use the drop-down menu to select when you want the client secret to expire.
  3. Click Add. You will return to the Certificates & secrets dialog, where the new client secret will be listed, showing a Value. Copy the value, because it will be required for setting up internal security in Matillion ETL.


  • You must copy the client secret value immediately. The client secret only appears once. If you fail to copy the value, your only option is to repeat this process and create a new client secret.
  • When copying the client secret, some browsers may add a space to the end of the string. Pay close attention to this because it will cause the credentials to fail. :::

Setting up internal security

  1. In Matillion ETL, click Admin at the top-right, and then click User Configuration.
  2. In the User Configuration dialog, click the Select Security Configuration drop-down field, and select Internal.
  3. Click the Open ID Connect Login tab. Use the credentials you copied earlier from the Azure Portal, and provide details for the following fields:
    • Identity Provider: Select Microsoft AD from the dropdown menu.
    • Provider Endpoint URL: This will be a URL of the form[Active-Directory-ID]/. Replace [Active-Directory-ID] with your Directory ID.
    • Client ID: Enter the Application (client) ID.
    • Client Secret: Enter the client secret, that is the same as the "Value" you copied before.
    • User Attribute: Enter an attribute to identify users. The default is unique_name.
    • Scope: List scopes for which access will be requested. The default is email.
    • Extra Options: List any additional connection options, as [key:value] pairs. These options aren't mandatory.
  4. Click OK.

Managing users and logging in with OpenID credentials

  1. Once the OpenID has been configured, you will be prompted to restart your Matillion ETL instance. This is required to ensure all of the changes take effect. Thereafter, the Matillion ETL login screen will include Sign in with Microsoft below the standard login form. However, the OpenID users still need to be added to the user list before this can be used.
  2. To add new users to the existing user list, return to the User Configuration dialog. Click the Manage Users tab, then click the + button.
  3. This will open the Add User dialog. Provide details for the following fields:
    • Username: Enter the User attribute chosen to identify the user when you configured the Open ID Connect Login tab. If you are authenticating using OpenID, provide the associated email address in this field that matches your OpenID credentials.
    • Password: Provide an appropriate password to be linked to the user. If you're authenticating using OpenID, a password will not be required.
    • Repeat Password: Re-enter the password as above.
    • Role: Select the access level of the user. Read Project User Access for details.
    • Permission Groups: Select an appropriate permission group for the user. For more information, read Groups and Permissions.
  4. Click OK.
  5. You will be returned to the Manage Users tab. Click Apply changes to confirm the addition of the new user. The OpenID can now be used to log in to your Matillion ETL instance.


  • Using OpenID does not prevent existing or new users from logging into their Matillion ETL instance via the usual method.
  • The passwords assigned to the OpenID users within Matillion ETL are solely for use within Matillion ETL. :::