Skip to main content

KBA1787 Configuring the Masking Engine for LDAP / Active Directory Authentication


Applicable Delphix Versions

Major Release

All Sub Releases



This guide describes the process of configuring the Masking Engine to authenticate logins using LDAP.

This guide is valid for Masking Engine release 5.2 and later. Configuring LDAP for Masking Engine release 5.1 and lower requires the assistance of Delphix Support.


Required LDAP information

Before proceeding, confirm that you have access to the following information:

  • Whether the LDAP server requires SSL/TLS connections
  • LDAP Server Hostname (e.g.
  • LDAP Server Port (usually the default of 389, or 636 for SSL/TLS)
  • LDAP Base DN (e.g. DC=mydomain,DC=mycompany,DC=com)
  • NETBIOS name of the Active Directory domain (e.g. mydomain), if your LDAP Server uses Microsoft Active Directory
  • LDAP Filter - for Active Directory, this is typically left at the default: (&(objectClass=person)(sAMAccountName=?))

Required LDAP accounts

You will need credentials for two LDAP accounts:

  • A valid LDAP account to configure as an administrator, for testing login and creating future accounts (this may be your own)
  • A service account, for the Virtualisation Engine to authenticate with the Masking Engine and launch masking jobs
    • This account may not be required if you do not use the Virtualization components of the Delphix Engine
    • You may need to request the creation of this account by your system administrators


Please be aware of the following restrictions and limitations:

  • LDAP authentication is incompatible with local authentication. Once LDAP is enabled, existing users will only be able to log in if there is an LDAP account matching their username.
  • Manual configuration by Delphix Support is required if you are authenticating against an LDAP Cluster.

Import an SSL Certificate (if using SSL/TLS)

This step is only necessary if your LDAP authentication service is secured with SSL/TLS.

NOTE: LDAP authentication with SSL/TLS is only possible from Masking Engine version and onwards.

The Delphix Engine can import an LDAP Server's public SSL certificate.  This must be done through the Virtualization Engine's Server Setup component, using the Authentication settings.

The Use LDAP and Protect LDAP traffic with SSL/TLS options must be checked, and an LDAP server (hostname or IP) provided, before the Import Server Certificate button will be activated.  Currently, these settings in the Server Setup page only affect whether the Virtualization Service is configured for LDAP.  The configuration settings for the Masking Service (except for the certificate itself) are managed through the Masking API as detailed in the section Configure LDAP Settings below.

When you provide the proper server info and then click on the Import Server Certificate button, the Engine will request the public cert directly from the remote LDAP service and store it internally.  This is also an excellent, early test to confirm that the host and port info is accurate.

Once the certificate is downloaded, you want to make sure that you add "LdapTlsEnable" to the list of application settings that you will configure in the section Configure LDAP Settings below.


This will provide details of the LDAP server's certificate, which can be accepted using the Accept button:


You could encounter the following errors.

If the hostname / port are simply wrong, (i.e. nothing there) you will receive a "Could not connect ..." error.

If the hostname / port are correct, but the service doesn't offer SSL, you will receive "An SSL handshake error occurred ..."

If the hostname / port refer to a service which doesn't understand your attempts to communicate, (i.e. connect to some other random service) there will be a delay followed by a "Communication Error".

Prepare new LDAP Masking Engine users

Configuring LDAP users in advance is important. In most cases you will need to configure two users in advance - these are described above in "Required LDAP accounts".

To configure these accounts as users on the Masking Engine, log in as an administrative user:

From the Admin tab, select the Add User button.


Create a new user with a valid LDAP username in the User Name field, with the Administrator checkbox checked:


IMPORTANT: The configured password will ONLY be used while the LDAP setting is disabled for the Masking Engine.

You should set the password to a secure value that is NOT the same as your LDAP password, and do not need to record it.

Repeat this step for the Virtualization Engine service account, if applicable.

Configure LDAP Settings (API Client)

The following guide provides instructions using the web-based API Client. Instructions for performing this work using curl via the command line are included later in this document.

Authenticate to the Masking API

The Masking API Client is accessible using the following URL:

To authenticate to the API Client, select:

  • The login group, to open login-related operations
  • The POST /login operation, to open the login API call
  • The Example Value textbox - clicking this will populate the nearby textbox with the example values


Adjust the example values in the Value text box, setting the correct login details, specifying your existing, non-LDAP Masking Engine login:


Click Try it out!.

If the login is successful, the Response Body will include an Authorization value which you can copy to your clipboard (not including the quotes).


This authorization key should be input using the Authorize button in the header at the very top of the page:



This step will unlock all of the other API operations for use.

Review current LDAP settings

A list of the available LDAP settings is available in the Masking API Client documentation. Alternatively, you can retrieve a list of all settings and their current values using the GET /application-settings call.

The setting_group setting can be left blank to retrieve all settings, or you can enter ldap to show all LDAP-specific configuration:


The response body will provide a list of settings in JSON format, including the Setting ID and current value:

      "settingId": 31,
      "settingGroup": "ldap",
      "settingName": "LdapHost",
      "settingValue": ""

Preparing to apply new settings

You can use the settingId values above in conjunction with the LDAP information to prepare new values.

The following list was correct at the time of writing. Changes to IDs or available settings do occasionally occur and we strongly suggest that you double-check the settings and matching IDs from your engine.

Setting ID Default Value Description
Enable 30 false Is LDAP authentication enabled?
LdapHost 31 What is the host/IP for LDAP authentication?
LdapPort 32 389 What is the port for LDAP authentication?
LdapBasedn 33 DC=tbspune,DC=com What is the baseDN for LDAP user entries?
LdapFilter 34 (&(objectClass=person)(sAMAccountName=?)) What is the LDAP filter to locate unique LDAP user entries?
MsadDomain 35 AD If LDAP server is Microsoft AD, what is the AD domain name / netbios name?
LdapTlsEnable 51 false Is LDAPS (SSL protected LDAP) being used?

In many cases, it may only be necessary to update the LDAP Host, Base DN, AD Domain Name, and Enabled settings.

If your LDAP service is protected by SSL (LDAPS) and you uploaded the appropriate certificate as described in the section Import an SSL Certificate above, then you need to make sure to add "LdapTlsEnable" to the list of application settings that you will configure.  You may also need to set your "LdapPort" to 636 as that is the default and most common port for LDAPS.

Prepare a list of the values that need to be changed  Make sure to note the Setting ID (from the Review step) for each setting that you intend to change.

Apply new LDAP settings

Expand the PUT /application-settings/{settingId} operation.

For each setting that you need to modify:

  • Update the settingId value
  • Modify the body textbox, to set the correct value for that setting
  • Click Try it out! to send the API request to the Masking Engine
  • Confirm that the Response Body includes the correct setting, and that the Response Code is 200 (OK)

IMPORTANT: Apply the LDAP Enabled setting last!


IMPORTANT: At this point, do not log out of your API session. You may still need this to roll back your changes.

Test a new Masking Engine login

Open your Masking Engine's login page in a new tab or window:

You should be able to confirm that:

  • You can no longer login with your former Masking Engine credentials
  • You can now log in using the LDAP account that you configured earlier, using your correct LDAP password

If you can not authenticate using your LDAP credentials, switch back to the browser tab containing the API client, and immediately proceed to the Rollback step.


If the LDAP configuration is not successful, roll back the configuration immediately, by setting the LDAP Enabled setting to false.


You may wish to review the current LDAP settings using the steps in "Reviewing current LDAP settings" above, to verify that the values are set as expected.

The Logs option from the Admin section of the main Masking Engine UI may be useful in diagnosing the exact nature of any failure.

Configure LDAP Settings (curl)

As an alternative to the API client, it is possible to use curl from a Unix/Linux command line to configure LDAP settings.


To authenticate to the Masking Engine using curl, you can use the login API call:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{"username": "myusername", "password": "mypassword"}' \

If successful, this will return a message similar to the following:


This Authorization UUID should be used in the headers of all subsequent commands.

Review current LDAP Settings

To retrieve current LDAP settings, call the application-settings GET API:

curl -X GET --header 'Accept: application/json' --header 'Authorization: f0d4dd35-0d2e-48bf-aca7-446d7c7a1690' \

This will return a lengthy JSON string containing all current LDAP parameters:


Apply new LDAP settings

  • Set the LDAP hostname
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: f0d4dd35-0d2e-48bf-aca7-446d7c7a1690' \
-d '{"settingValue": ""}' \
  • Set the LDAP base DN
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: f0d4dd35-0d2e-48bf-aca7-446d7c7a1690' \
-d '{"settingValue": "DC=tbspune,DC=com"}' \
  • Set the AD Domain Name
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: f0d4dd35-0d2e-48bf-aca7-446d7c7a1690' \
-d '{"settingValue": "AD"}' \
  • Enable LDAP
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: f0d4dd35-0d2e-48bf-aca7-446d7c7a1690' \
-d '{"settingValue": "true"}' \

To set other values, review the table from "Preparing to apply these settings", earlier in this document.

Configure Virtualization to Masking authentication

After setting up LDAP authentication, Delphix Virtualization Engines connected to the Masking Engine may no longer be able to retrieve or start masking jobs.

This is most easily confirmed by logging into the Management interface and looking at the status of recent MASKINGJOB_FETCH jobs, which occur on each user login.


Now that the Masking engine will only allow LDAP logins, credentials for a valid LDAP account must be provided. This will likely be a service account such as svc_delphixmasking.

Once an account has been prepared, the Delphix Command Line Interface (CLI) can be accessed by SSH, updating credentials as described in  Configuring Virtualization Service for Masked Provisioning:

mydelphixengine> maskingjob
mydelphixengine maskingjob> serviceconfig
mydelphixengine maskingjob serviceconfig> ls
`MASKING_SERVICE_CONFIG-1  localhost  8282  admin     { ... }      HTTP
mydelphixengine maskingjob serviceconfig> select `MASKING_SERVICE_CONFIG-1
mydelphixengine maskingjob serviceconfig '`MASKING_SERVICE_CONFIG-1'> update
mydelphixengine maskingjob serviceconfig '`MASKING_SERVICE_CONFIG-1' update *> ls
    type: MaskingServiceConfig
        type: PasswordCredential
        password: ********
    port: 8282
    scheme: HTTP
    server: localhost
    username: admin
mydelphixengine maskingjob serviceconfig '`MASKING_SERVICE_CONFIG-1' update *> set username=svc_masking
mydelphixengine maskingjob serviceconfig '`MASKING_SERVICE_CONFIG-1' update *> set credentials.password
Enter credentials.password: ************
mydelphixengine maskingjob serviceconfig '`MASKING_SERVICE_CONFIG-1' update *> commit

To test whether the change was successful, log out and log back in to the Management interface, and confirm that the most recent MASKINJOBG_FETCH job has a Status of COMPLETED.