Configuring the Masking Engine for LDAP/ Active Directory Authentication (KBA1787)

Required LDAP Information

Confirm you have access to the following information:

• Whether the LDAP server requires SSL/TLS connections
• LDAP Server Hostname (e.g. dc1.mydomain.mycompany.com)
• 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

Limitations

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.

Authenticate to the Masking API 

The Masking API Client is accessible using the following URL: http://mydelphixengine.mydomain:8282...ng/api-client/

To authenticate to the API Client:

1. Select
   • login group to open login-related operations.
   • POST /login operation to open the login API call.
   • Example Value textbox
     Clicking this will populate the nearby textbox with the example values.

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

3. 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).

4. The authorization value 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": "10.10.10.31"
    },
    ...

Preparing to Apply New Settings 

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

Note that 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.

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 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!

Note:

At this point, it's important that you do not log out of your API session. You may still need this to roll back your changes.

Testing a New Masking Engine Login 

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

• 6.x: http://mydelphixengine.mydomain.com/masking
• 5.3: http://mydelphixengine.mydomain.com:8282/masking
• 5.2: http://mydelphixengine.mydomain.com:8282/dmsuite

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 cannot authenticate using your LDAP credentials, switch back to the browser tab containing the API client, and immediately proceed to the Rollback step.

Rollback 

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 Reviewing Current LDAP Settings 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.

Authentication Using curl

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

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{"username": "myusername", "password": "mypassword"}' \
'http://mydelphixengine.mydomain:8282/masking/api/login'

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

{"Authorization":"f0d4dd35-0d2e-48bf-aca7-446d7c7a1690"}

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' \
'http://mydelphixengine.mydomain:8282/masking/api/application-settings?setting_group=ldap&page_number=1'

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

...{"settingId":31,"settingGroup":"ldap","settingName":"LdapHost","settingValue":"10.10.10.31"}...

Apply New LDAP Settings using curl

• 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": "10.10.10.31"}' \
'http://mydelphixengine.mydomain:8282/masking/api/application-settings/31'

• 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"}' \
'http://mydelphixengine.mydomain:8282/masking/api/application-settings/33'

• 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"}' \
'http://mydelphixengine.mydomain:8282/masking/api/application-settings/35'

• Enable LDAP

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: f0d4dd35-0d2e-48bf-aca7-446d7c7a1690' \
-d '{"settingValue": "true"}' \
'http://mydelphixengine.mydomain:8282/masking/api/application-settings/30'

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

Related Articles

• Masking API Client