Configuring the Masking Engine for LDAP/ Active Directory Authentication (KBA1787)
KBA
KBA#1787Applicable Delphix Versions
- Click here to view the versions of the Delphix engine to which this article applies
-
Date Release Feb 13, 2023 8.0.0.0 Jan 12, 2023 7.0.0.0 Releases Prior to 2023 Major Release All Sub Releases 6.0 6.0.0.0, 6.0.1.0, 6.0.1.1, 6.0.2.0, 6.0.2.1, 6.0.3.0, 6.0.3.1, 6.0.4.0, 6.0.4.1, 6.0.4.2, 6.0.5.0, 6.0.6.0, 6.0.6.1, 6.0.7.0, 6.0.8.0, 6.0.8.1, 6.0.9.0, 6.0.10.0, 6.0.10.1, 6.0.11.0, 6.0.12.0, 6.0.12.1, 6.0.13.0, 6.0.13.1, 6.0.14.0, 6.0.15.0, 6.0.16.0, 6.0.17.0, 6.0.17.1, 6.0.17.2
5.3
5.3.0.0, 5.3.0.1, 5.3.0.2, 5.3.0.3, 5.3.1.0, 5.3.1.1, 5.3.1.2, 5.3.2.0, 5.3.3.0, 5.3.3.1, 5.3.4.0, 5.3.5.0 5.3.6.0, 5.3.7.0, 5.3.7.1, 5.3.8.0, 5.3.8.1, 5.3.9.0 5.2
5.2.2.0, 5.2.2.1, 5.2.3.0, 5.2.4.0, 5.2.5.0, 5.2.5.1, 5.2.6.0, 5.2.6.1
At a Glance
Description: | This article describes the process of configuring the Continuous Compliance (CC) Engine (aka Masking) to authenticate logins using LDAP. | |
---|---|---|
Applicable to: | This is applicable to all versions from version 5.2 (including Containerized Masking). | |
Steps: | These steps are best performed using two tabs in the browser (Masking UI + API Client). | |
Step 1 (optional): | Tab 1 UI: Setup > Tile: Authentication > LDAP. Only used to import the SSL/TLS Certificate. For Containerized Masking, import needs to be done manually. Note this step will not configure LDAP for Masking. |
|
Step 2: | Tab 1 UI: CC Login > Admin > Users. Prepare an LDAP admin user on the Masking Engine. | |
Step 3: | Tab 2 API: api-client. Configure LDAP on Masking in Application Settings (Do not close tab). | |
Step 4: | Tab 1 UI: CC Login. Try logging in to Masking Engine (if failure - go to tab 2 API). | |
Video: | How to configure LDAP video
|
|
Notes: | The best place to configure LDAP is during the initial engine Setup (startup). | |
All LDAP configurations need to be set on the Masking Engine using the Masking API. | ||
Masked vDB - See section below. | ||
Locked Out: | If the API client tab is closed and the login fails (due to invalid LDAP configurations) - you will need to log a Support Ticket to reset the login configurations. | |
Troubleshooting: | For information about investigating the logs: | |
API details: | Docs: Masking API. |
Prerequisites
Prior to proceeding familiarize yourself with the following prerequisites.
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.
Configuration Steps
Step 1 - Importing Certificate
The Delphix Engine can import an LDAP Server's public SSL certificate. This must be done through the Server Setup component of the engine, 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, the engine will request the public cert directly from the remote LDAP service and store it internally (be aware of the LDAP configurations). This is also an excellent, early test to confirm that the host and port information 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.
Possible Errors
You could encounter the following errors.
- If the hostname/port is wrong, you will receive a "Could not connect ..." error.
- If the hostname/port is correct, but the service doesn't offer SSL, you will receive "An SSL handshake error occurred ..."
- If the hostname/port refers to a service that 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".
Step 2 - UI: Add LDAP Users
This step is important and the main user to set up is a Masking LDAP Admin user. This user can then add additional users.
In some cases, you need to configure two users in advance (described above in "Required LDAP accounts").
Example
- Navigate to the Admin tab > Add User.
- Create a new user with a valid LDAP username in the User Name.
- Ensure that the Administrator checkbox is selected:
Step 3 - API: Masking LDAP Settings
Perform these tasks using a separate Browser Tab and keep this tab open in case login fails and some values need to be modified. If the settings are incorrect, you will not be able to log back in.
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 using the setting_group 'ldap'.
The response body will provide a list of settings in JSON format, including the Setting ID and current value:
{ "_pageInfo": { "numberOnPage": 7, "total": 7 }, "responseList": [ { "settingId": 30, "settingGroup": "ldap", "settingName": "Enable", "settingValue": "false" }, ...
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 match the IDs from your engine.
Setting | ID | Default Value | Description |
---|---|---|---|
Enable | 30 | false | When all settings are applied - set this to True to enable LDAP. |
LdapHost | 31 | 10.10.10.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 | What is the AD domain name / netbios name? |
LdapTlsEnable | 51 | false | Is LDAPS (SSL protected LDAP) being used? |
Apply New LDAP Settings
Expand the PUT /application-settings/{settingId} operation.
For each setting that you need to modify:
- Update the settingId value and the body.
- Modify the body to set the correct value for that setting.
- Click Execute 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!
Step 4 - Testing LDAP Login
Go to the Masking UI tab and Test logging in.
You should be able to confirm that:
- You can now log in using the LDAP account that you configured earlier, using your correct LDAP password.
- You should no longer be able to login with your former Masking Engine credentials.
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.
How to 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 verify the LDAP settings in the above section: Review Current LDAP Settings to confirm 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 Virtualization to Masking Authentication
After setting up LDAP authentication, Continuous Data Engines connected to the Continuous Compliance 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 Objects NAME SERVER PORT USERNAME CREDENTIALS SCHEME `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 Properties type: MaskingServiceConfig credentials: 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
.