Rotate Local Accounts

Overview

This guide configures secret rotation for a standalone VMware ESXi local account. The script updates the stored secret on the host via the vSphere SOAP API — the account itself is not created or removed. Use this for shared admin accounts (e.g. root) that you want to rotate on a schedule or post-incident.

Reference script: britive/access-broker-examples/VMware/ESXi/rotate/rotate-esxi-account.py.

Before You Begin

ESXi service account already configured (see Getting Started → Configure the ESXi Host).
The target account to rotate (e.g. root) must already exist on the host.
vSphere Standard or higher license — rotation calls UpdateUser, which is a write operation.
Broker pool with outbound TCP 443 to the host.

How It Works

    sequenceDiagram
    participant Britive
    participant Broker
    participant ESXi as ESXi Host

    Britive->>Broker: Trigger rotation (schedule or on-demand)
    Broker->>Broker: Run rotate-esxi-account.py
    Broker->>ESXi: Login on ha-sessionmgr (service account)
    Broker->>ESXi: UpdateUser on ha-localacctmgr with target account id + new secret
    Broker->>ESXi: Logout
    Broker-->>Britive: Return new secret
    Britive->>Britive: Store new secret in the Britive Secrets Store

Secrets are sent inside the encrypted HTTPS session and never written to stdout or logs.

Environment Variables

Variable	Required	Description
`ESXI_HOST`	Yes	IP or hostname of the target ESXi host
`ESXI_SVC_USER`	Yes	Service account on the host (Administrator role)
`ESXI_SVC_PASSWORD`	Yes	Service account secret (sensitive)
`ESXI_TARGET_USER`	Yes	Local account on the host to rotate
`ESXI_NEW_PASSWORD`	Yes	New secret to set (sensitive)
`ESXI_VERIFY_TLS`	No	`true` to verify TLS (default `false`)

Register the Rotation Script

In the Britive console: Resource Manager → Resource Types → ESXi → Rotation.

Upload the script

Upload or reference rotate-esxi-account.py on the broker host.

Map variables

Map script variables to resource parameters — same mapping as the JIT permission, plus ESXI_TARGET_USER and ESXI_NEW_PASSWORD from the rotation context.

Mark sensitive variables

Mark ESXI_SVC_PASSWORD and ESXI_NEW_PASSWORD as sensitive.

Verify

Trigger a rotation

In the console: Resource Manager → Resources → <esxi-host> → Rotate Account → select target account → Rotate Now.

Expected log output from the broker:

[rotate] Rotating secret for root
[rotate] Secret rotated successfully for root

Confirm the new secret works

Sign in to the host UI (https://<esxi-host>/ui) or SSH using the rotated account with the new secret pulled from Britive’s secret store.

Confirm the old secret no longer works

Retry the same sign-in with the previous secret — it should be rejected.

Troubleshoot

Symptom	Cause	Fix
Rotation fails with `InvalidArgument`	ESXi password complexity rule rejected the generated secret	Generate a stronger secret (length, character classes) or relax PAM rules on the host
Rotation fails with a SOAP fault about licensing	Free / unlicensed ESXi blocks write API calls	Apply a vSphere Standard license on the host
Rotation fails with `UserNotFound`	`ESXI_TARGET_USER` doesn’t exist on the host	Check the account name — case-sensitive on ESXi
Account is locked out after rotation	PAM lockout from a stale process still using the old secret	Stop the consuming process, unlock the account on the host, retry

Next Steps

Scan Local Accounts — confirm rotated accounts are still in Britive’s identity inventory
Getting Started — JIT temp local admin pattern

Last updated on July 8, 2026

Getting Started — JIT Local Admin Scan Local Accounts