Changing the Delphix OS (Operating System) User's Windows Authentication (Active Directory) Password for SQL Server Environments (KBA5834)

Prerequisites

In order to follow this procedure, you will need to:

• Have access to your Active Directory or System Administrators
• Have Administrative access to the Continuous Data Engine
• Know the usernames for all Active Directory accounts where the password is being changed
• Know the new password for all Active Directory accounts where the password is being changed

Step 1: Verify account lockout policies

Contact your Active Directory administrators to check whether any account lockout policies are in place for the Active Directory accounts being modified.

If an account lockout policy is in place, it should be temporarily disabled while this procedure is being followed.

If the account becomes locked, it will not be possible to validate and change the passwords.

Step 2: Identify Environments where the AD account is used

Login to the Continuous Data Engine Management interface.

From the Manage → Environments screen, select each Environment. Note which of them include affected Active Directory account(s) in the list of Environment Users.

Alternatively, the Command Line Interface can be used to list the Environments and Users connected to your engine:

/environment/user
list display=environment,name

ENVIRONMENT    NAME
WINDOWSTARGET  WINDOWSTARGET/DOMAIN\username
WINDOWSSOURCE  WINDOWSSOURCE/DOMAIN\username

Step 3: Identify dSources where the AD account is used

In some cases, dSources may be configured with an Active Directory username and password.

This can be checked using the Manage → Datasets screen. Select each dSource and review the Configuration → Source tab.

If the user type is set to Domain User with Password Credential, make a note of this. This password will also need to be updated in a later step.

From the Command Line Interface, the following command will show the way that the Continuous Data Engine is authenticating to each dSource;

/source
list display=name,syncStrategy.mssqlUser.type,syncStrategy.mssqlUser.user

NAME            SYNCSTRATEGY.MSSQLUSER.TYPE  SYNCSTRATEGY.MSSQLUSER.USER
SourceDB1       MSSqlDatabaseUser            delphix_db
SourceDB2       MSSqlEnvironmentUser         WINDOWSSOURCE/DOMAIN\username
SourceDB3       MSSqlDomainUser              DOMAIN\username
VDB1            -                            -

In the CLI output, entries which show a user type of MSSqlDomainUser will need to have their password modified.

Step 4: [Optional] Disable dSources, VDBs and Environments

In some cases, you may wish to disable objects within the Continuous Data Engine prior to password changes.

If account lockout policies cannot be changed, or you are concerned about login failures being reported on Source Databases, use the Management interface, CLI or API to disable dSources.

If account lockout policies cannot be changed, or you are concerned about login failures being reported on Target Environments, use the Management interface, CLI or API to disable VDBs and Environments.

Step 5: Change the password in Active Directory

Once you know where the passwords will need to be updated, you (or your System Administrators) can change the password within Active Directory.

Once this step is complete, the passwords recorded in the engine will no longer be valid. The engine may begin raising faults as it begins to connect to Environments using the outdated credentials.

Note:

It is possible to update a password using the Command Line Interface before it is modified in Active Directory. When performed this way, the password is not validated, and subsequent failures or faults are possible if the password is entered incorrectly.

Step 6: Update the password in Environments where the AD account is used

Login to the Management interface and navigate to the Manage → Environments screen.

For each of the Environments identified during Step 2:

1. Select the Environment from the list.
2. Click on the username of the affected account, to select it.
3. Click the Edit  icon to modify the credential.
4. Enter the new password.
5. Press Save.  The Engine will automatically attempt to verify and store the new password. If the credential is incorrect, or the AD account is locked, this action will fail.

If the user account continues to be locked out, this can cause the GUI update to fail, as the Engine will automatically attempt to test/verify the credential update. To avoid this, the password credential can be updated through CLI, which only updates the stored credential without attempting to verify it. In the example below, the existing AD credential for sl-ad\delphix on Environment win-2022-tgt will be updated.

de-mercury> /environment user
de-mercury environment user> ls
Objects
NAME
Oracle Source 19.11.0.0/oracle
delphix
Oracle Target 19.11.0.0/oracle
win-2022-tgt/sl-ad\delphix
win-2022-src/sl-ad\delphix

Operations
create
de-mercury environment user> select win-2022-tgt/sl-ad\delphix
de-mercury environment user 'win-2022-tgt/sl-ad\delphix'> ls
Properties
    type: EnvironmentUser
    name: win-2022-tgt/sl-ad\delphix
    credential:
        type: PasswordCredential
        password: ********
    environment: win-2022-tgt
    groupId: 0
    reference: HOST_USER-17
    userId: 0

Operations
delete
update
de-mercury environment user 'win-2022-tgt/sl-ad\delphix'> update
de-mercury environment user 'win-2022-tgt/sl-ad\delphix' update *> set credential.password=newpass
de-mercury environment user 'win-2022-tgt/sl-ad\delphix' update *> commit

As the CLI ultimately invokes an API request, any alterative method that issues API POST to /resources/json/delphix/environment/user/ endpoint with appropriate payload can be used to automate the update process (custom CURL script, dxToolkit, etc). The internal user reference will need to be determined.

=== POST /resources/json/delphix/environment/user/HOST_USER-17 ===
{
    "type": "EnvironmentUser",
    "credential": {
        "type": "PasswordCredential",
        "password": "newpass"
    }
}

Further guidance in API/CLI specifics are beyond the scope of this document.

Step 7: Update the password in dSources where the AD account is used, if required

In many cases, Step 3 will not identify any dSources using Domain User with Password credentials, and this step can be skipped.

If some dSources are using this configuration, for each of the affected dSources:

1. Select the dSource in the Manage → Datasets screen.
2. Switch to the Configuration → Source tab.
3. Press the Edit  icon in the Source Database panel to modify the credential.
4. Enter the new password.
5. Press Save to validate and store the new password. In contrast to the Environment user update, this action does not automatically validate the user credential, so if the password is incorrect or the AD account is locked, it will not be immediately evident after this change.

Step 8: Resolve any Faults

The engine should now be authenticating to all environments using the correct credentials.

If any authentication failures occurred while Steps 5-7 were being followed, a Fault will be raised in the Continuous Data Engine.

These authentication failures can be marked as Resolved from the System → Faults screen. If they re-occur, a new fault will be posted.

Important:

Be careful to Resolve faults, and not Ignore them. Ignored faults will not be raised if they re-occur, which will complicate troubleshooting.

Step 9: [Optional] Enable dSources, VDBs and Environments

If objects were disabled in Step 4, these can be re-enabled now.

Environment Enable operations should be allowed to run through to completion before dSources and VDBs are enabled.

Step 10: Monitor for faults or errors

VDBs and dSources should now be operating normally, with no further errors reported.

Continue to monitor the Continuous Data Engine and your Source and Target Environments for new errors.