Rotate Active Directory Accounts

Overview

These scripts rotate the password on an Active Directory account that already exists — a service account, or any shared identity named outright rather than derived from a requester. They run on the Linux broker over LDAPS, so no Windows host and no RSAT module is needed.

Each is a single standalone file. Upload it as the rotation script on the resource type; nothing else has to be installed.

What you’ll accomplish:

• Pick the variant that matches what consumes the credential
• Configure the AD connection as resource attributes
• Verify the account rotated and the consumer followed

Which Script

All three also unlock the account and clear the must-change-password-at-next-logon flag that an administrative reset leaves behind. Without that second step the account cannot authenticate non-interactively — which is the only way a service account ever authenticates.

How It Works

    flowchart TD
    Sched["Britive rotation<br/>(schedule or on demand)"]
    Script["rotate-ad-*.sh<br/>(runs on the Linux broker)"]
    AD["Active Directory<br/>(LDAPS 636)"]
    SM["AWS Secrets Manager"]
    Svc["Windows service<br/>(WinRM)"]

    Sched -->|"injects AD_NEW_PASSWORD (encrypted) + RESOURCE_* attributes"| Script
    Script -->|"1. preflight the consumer"| Svc
    Script -->|"2. reset unicodePwd, unlock, clear pwdLastSet"| AD
    Script -->|"3. propagate"| SM
    Script -->|"3. propagate"| Svc
  

Before You Begin

• The Access Broker is deployed and connected
• LDAPS reachable on port 636. Active Directory refuses unicodePwd writes over cleartext LDAP, so plain 389 cannot work
• ldapsearch, ldapmodify, python3, openssl, and base64 on the broker (all ship in the britive/bridge image)
• A bind account with Reset Password, and write on lockoutTime and pwdLastSet, over the target OU
• The target account already exists — a rotation rotates, it never creates
• For the Windows service variant: WinRM reachable from the broker, and pywinrm on the broker (ships in the base image)

Variables

Connection — set these as resource attributes

The broker delivers a resource’s attributes upper-cased with a RESOURCE_ prefix, so each script assigns them across at the top:

AD_SECRET holds the name of a Secrets Manager secret containing the bind credentials — not the credentials themselves. See How the Broker Passes Values to a Script.

Rotation variables — set these on the rotation

Rotation variables arrive under exactly the name you configure — no prefix, no case change.

Inside the Script

Map the resource attributes

# A value set directly wins, so the script stays runnable by hand.
AD_HOST="${AD_HOST:-${RESOURCE_HOST:-}}"
AD_BASE_DN="${AD_BASE_DN:-${RESOURCE_BASE_DN:-}}"
AD_SECRET="${AD_SECRET:-${RESOURCE_SECRET:-}}"
AWS_REGION="${AWS_REGION:-${RESOURCE_REGION:-}}"

# AD_TARGET_USER and AD_NEW_PASSWORD need no mapping — the rotation passes
# them under their own names already.
: "${AD_TARGET_USER:?set AD_TARGET_USER on the rotation}"
: "${AD_NEW_PASSWORD:?Britive supplies this; configure the attribute on the rotation}"

Reset the password

AD stores passwords in unicodePwd as the plaintext wrapped in literal double quotes, encoded UTF-16LE, then base64 for LDIF transport. Any deviation returns unwilling to perform with no further detail.

encode_unicode_pwd() {
  printf '%s' "$1" | python3 -c '
import base64, sys
quoted = f"\"{sys.stdin.read()}\"".encode("utf-16-le")
sys.stdout.write(base64.b64encode(quoted).decode("ascii"))
'
}

# The bind password is written to a 0600 file and passed with -y, never on argv.
ldapmodify -x -H "ldaps://${AD_HOST}:636" -D "$BIND_DN" -y "$BIND_PW_FILE" <<EOF
dn: ${USER_DN}
changetype: modify
replace: unicodePwd
unicodePwd:: $(encode_unicode_pwd "$NEW_PASSWORD")
EOF

replace — not add or delete — is the administrative reset form, and it does not require the previous password.

Clear what the reset leaves behind

# Unlock. Best-effort: the reset already succeeded, and failing the whole
# rotation over a lockout flag would be worse than reporting it.
replace: lockoutTime
lockoutTime: 0

# Clear must-change-at-next-logon. NOT best-effort: an account left flagged
# cannot authenticate non-interactively, so the new credential would be useless.
replace: pwdLastSet
pwdLastSet: -1

pwdLastSet accepts only two values: 0 forces a change at next logon, -1 stamps the current time and clears that requirement.

Propagating the New Password

Two systems that cannot be changed atomically means the order matters. Both variants put the cheap failures first.

# 1. Preflight — read the secret and confirm it is a JSON object.
CURRENT_SECRET="$(aws secretsmanager get-secret-value \
  --secret-id "$AWS_SECRET_ARN" --query SecretString --output text)"

printf '%s' "$CURRENT_SECRET" | jq -e 'type == "object"' >/dev/null \
|| die "secret is not a JSON object — this script patches one key, it will not overwrite a plaintext value"

# 2. Reset in AD (shown above).

# 3. Patch only AWS_SECRET_KEY; every other field survives.
printf '%s' "$CURRENT_SECRET" \
| jq --arg k "$SECRET_KEY" --arg v "$NEW_PASSWORD" '.[$k] = $v' > "$SECRET_FILE"

aws secretsmanager put-secret-value \
--secret-id "$AWS_SECRET_ARN" --secret-string "file://${SECRET_FILE}"

# 1. Preflight — resolve the host, authenticate over WinRM, confirm the service.
winrm_ps preflight \
|| die "WinRM preflight FAILED — nothing was changed in AD"

# 2. Reset in AD (shown above).

# 3. Write the new logon credential onto the service, then restart it.
winrm_ps update "$NEW_PASSWORD"

Configure in Britive

Verify

username: svc-app01
password_rotated: true
account_unlocked: true

ldapsearch -x -H "ldaps://dc01.contoso.local:636" -D "$BIND_DN" -y "$BIND_PW_FILE" \
  -b "$AD_BASE_DN" "(sAMAccountName=svc-app01)" pwdLastSet lockoutTime

Troubleshoot

Next Steps

• Rotate AWS Secrets Manager Secrets — when the secret, not a directory account, is what needs rotating
• Active Directory integration — scans, group membership, and checkout-based admin account rotation
• Source: britive/access-broker-examples — Active Directory