AD Secret Engine

This feature is part of the Enterprise plan. If it is not enabled for your organization, please contact StrongDM at the StrongDM Help Center.

StrongDM Vault has a secret engine for on-premises Active Directory. This secret engine can be used to manage and rotate credentials within AD itself as well as in a backing secret store. The copies kept on the secret store can then be used to facilitate user connection through StrongDM to resources using those credentials, which are rotated in tandem with the ones on AD, ensuring the two copies are kept in sync.

The AD connection is set up with either the StrongDM Admin UI or the StrongDM CLI, and the process generally involves providing AD configuration information to allow StrongDM nodes to connect to your on-premises AD environment and perform secrets updates within AD. Once the connection is established, the secrets are rotated on AD at the same time as they are rotated and stored in a backing secret store.

If you do not already have a secret store (StrongDM Vault or a supported cloud secret store provider) configured with StrongDM, do that first by following one of the guides in the Secret Stores section.

Prerequisites

For StrongDM, the following requirements must be met:

• You must be a StrongDM account administrator.

• At least one StrongDM gateway must have authorization for the necessary operations to succeed in both API operations and network traffic to the secret engine and/or vault.

• At least one secret store (either StrongDM Vault or one of the supported cloud providers) must be configured.

For AD, the following requirements must be met:

• The user must have the privilege to change passwords for users in scope detailed in the Set up AD account privileges section.

• Authorization details must be provided during configuration.

• Open port 636 for TLS encrypted connections.

• Open port 389 for unencrypted connections.

Set up AD account privileges

StrongDM will authenticate using a user account in Active Directory that must be an granted adequate permissions to reset passwords for other accounts. In order to do that:

1. Go to Active Directory Users and Computers, right click on the organizational unit that contains the accounts (generally "Users"), and select Delegate Control.

2. Click Next, and when prompted for a User or Group, select the account that StrongDM will be using to rotate passwords.

3. In the next page of the wizard, choose Create a Custom Task to Delegate.

4. Select Only the following objects in the folder, then select User objects from the list.

5. Click on General > Property-Specific > Creation/Deletion of specific child objects and pick the following from the Permissions list:

   • Change Password

   • Reset Password

   • Read lockoutTime

   • Write lockoutTime

   • Read pwdLastSet

   • Write pwdLastSet

   • Read userAcccountControl

   • Write userAccountControl

6. Click Next, then Finish.

For HashiCorp Vault, the nodes (gateways or relays) that are going to access the secret store for storing managed secrets must have permissions to read/write/create/delete secrets with a path starting with the secret store root path.

Create a Secret Engine

To add a new secret engine in the Admin UI, follow these steps.

1. In the Admin UI and go to Settings > Secrets Management.

2. Select the Secret Engines tab and click Add secret engine.

3. On the dialog that displays, select Active Directory and then set the following properties, then click save.

Configuring password rotation or complexity settings here provide a default for secrets created by and managed by this secret engine. If you create an individual secret with this engine but change these settings on that individual secret, the settings on the secret will be followed. For example, if you do not provide any default rotation settings for the engine, secrets created will, by default, not have any of these settings configured. If you configure a rotation time of one hour for one particular secret, it will be rotated hourly, disregarding the secret engine configuration.

Secret engine properties

These properties are required, other than Tags.

Property	Requirement	Description
Name	Required	Descriptive name that clearly indicates what the engine is for
Secret Store	Required	The secret store where the secrets you wish to manage are located
Secret Store Root Path	Required	The path to the secret store where the secrets are located, for example, /secret/data/ad
Select node(s)	Required	The node(s) (gateways, relays, proxy clusters) to be used to contact your secret store; does not have to be filled out to create the engine, but is required to function
Select or add tags	Optional	Tags for organizing and interacting with secret engines

Active Directory properties

The URL and Bind DN are required, with the rest being optional. Note that if the Bind password is provided, the existing password for this user will be updated to match the provided value. If a password is not provided, the secret store's password value will not be in sync with Active Directory until after the first rotation.

Property	Requirement	Description
URL	Required	Active Directory URL
Bind DN	Required	Bind Distinguished Name, or direct path to or reference to the user account used to access AD; should exactly match the distingushedName value found in the account attribute editor in Active Directory
Bind password	Optional	Password for the Bind DN
Credential rotation interval	Optional	Interval for automatic secret rotation, in days, hours, and minutes
Timeout after credential read	Optional	Timeout after credential read in days, hours, and minutes

Password generation properties

These properties are optional criteria and constraints on password generation for the rotation of passwords.

Property	Requirement	Description
Length	Optional	Length of passwords that are generated; defaults to 32
Number of Digits	Optional	Number of digits contained in passwords that are generated; defaults to 6
Number of symbols	Optional	Number of symbols contained in passwords that are generated; defaults to 0
Excluded characters	Optional	Characters that are excluded from passwords that are generated; defaults to \
Exclude uppercase	Optional	Exclude uppercase letters from passwords that are generated
Allow repeated passwords	Optional	Allow repeated passwords when generating new passwords

Advanced settings

These properties are advanced settings regarding the encryption of the connection to AD and other advanced details.

Property	Requirement
CA certificate	Optional
Start TLS	Optional
Insecure TLS	Optional
Disable timestamp validation	Optional
Request timeout	Optional
Connection timeout	Optional
Maximum backoff duration	Optional
Base DN	Optional
User Principal Domain	Optional

The Secret Engines tab now displays the secret engine that you just added.

CLI Configuration of the Secret Engine

The following example provides a general idea of how to use some of the sdm admin secretengines and sdm admin managedsecrets CLI commands to set up an AD secret engine to store secrets, entitle them to a user, have the user retrieve the secrets, and rotate the secrets in AD.

1. Create the secret engine:

   sdm admin secretengines create active_directory
   --binddn "CN=Alice Glick,OU=Engineering,DC=example,DC=com"
   --bindpass="Example"
   --secret-store-id se-1234a12345bcd123
   --name AD
   --secret-store-root-path="/secret/data/ad"

2. Configure the node (gateway or relay) to be used to contact Active Directory. Run the sdm admin nodes update command to update the relevant node with a tag in the form of eng__<SECRET_ENGINE_NAME>=true:

   sdm admin nodes update n-1b23000c4567a890 --tags eng__AD=true

3. Define a managed secret that will manage the passwords for the user. After running the following command, information about the new secret is returned.

   $ sdm admin managedsecrets create AD Bob user_dn='CN=Alice Glick,OU=Engineering,DC=example,DC=com'
   ID                   ms-1a234b5c67de8912
   Secret Engine ID     eng-12a3456b78cd9e1f
   Name                 Bob
   Last Rotated At      NEVER
   Next Rotation At     NEVER
   Policy               password.excludeuppercase=false,password.length=0,password.numsymbols=0,password.numdigits=0.password.allowrepeat=false
   Tags

4. Retrieve the password for the created user, which is shown in the Secret Value that is returned. To retrieve, rotate, or validate secrets, use the sdm managedsecrets command. The show subcommand shows the secret without sensitive values; the retrieve subcommand shows the sensitive data.

   sdm managedsecrets retrieve AD Bob

5. Now that you've created secrets and verified that they can be retrieved, you have the option to rotate the user's password:

    sdm managedsecrets rotate AD Bob

6. Optionally log in to the Admin UI and go to Access > Secrets to view, rotate, and/or validate the managed secret.

See the sdm admin managedsecrets and sdm managedsecrets command reference pages for details on these commands.

How to Schedule Automatic Password Rotation

For AD managed secrets, you may schedule automatic password rotation by setting a time-to-live (TTL) value for either the secret engine or the managed secret. The TTL is an amount of time in seconds, minutes, or hours (for example, 12h, 30m, 5s, or 6h30m) that determines the lifetime of the password.

A password is valid for the given amount of time set in the TTL, after which it is automatically rotated. If the TTL value is not set, the secret engine's TTL value is used for rotation. If neither are set or they are set to 0s (zero seconds), then there is no automatic password rotation, and rotation will need to be done manually using sdm managedsecrets rotate or on the Admin UI's Access > Secrets page.

In the following example, an AD secret engine is created with the TTL set to 12 hours:

sdm admin secretengines create active_directory
--binddn "CN=Alice Glick,OU=Engineering,DC=example,DC=com"
--bindpass="Example"
--secret-store-id se-1234a12345bcd123
--name exampleAD
--secret-store-root-path="/secret/data/ad"
--ttl="12h"

In the following example, an AD managed secret is created and the TTL is set to 12 hours:

sdm admin managedsecrets create exampleAD Bob
--user_dn="CN=Alice Glick,OU=Engineering,DC=example,DC=com"
--ttl="12h"

Maximum Backoff Duration

To ensure successful automatic secret rotations for AD managed secrets, you can set a specific maximum backoff duration value for automatic rotations. Maximum backoff duration is the maximum amount of time that the system will wait before attempting rotation before stopping. The default value is 24 hours.

If an automatic rotation attempt fails, the system will retry in increasing intervals until the maximum backoff duration is reached. After it is reached, the system will retry every maximum backoff duration. For example, if the maximum backoff duration is set to 12 hours and automatic rotation fails, the system might retry 1 minute later, retry 1 hour later after that, and then retry 12 hours later, which is the maximum backoff duration value. Every subsequent attempt will be made every 12 hours after the previous attempt until the rotation is successful.

Once a rotation succeeds, whether manual or automatic, the schedule resets, and the next rotation will follow the standard secret expiration timing.

You can adjust the maximum backoff duration by using the --max-backoff-duration option when creating or updating an AD secret engine.

In the following example, an AD secret engine is created with rotation set to occur every 12 hours (see the --ttl value) and the maximum backoff duration set to 10 minutes. If the scheduled rotation fails, the system will try again in increasing intervals until 10 minutes has been reached. After that, the system will attempt to rotate it every 10 minutes until it is successful.

sdm admin secretengines create active_directory
--binddn "CN=Alice Glick,OU=Engineering,DC=example,DC=com"
--bindpass="Example"
--secret-store-id se-1234a12345bcd123
--name exampleAD
--secret-store-root-path="/secret/data/ad" 
--ttl="12h"
--max-backoff-duration="10m"

Manage Secrets

Create a managed secret

Next, create a secret using the secret engine. This will allow the secret engine to begin rotating the password for the selected username, and also begin storing it in your secret store, so that we can use it for proxying connections to the resource.

1. Go to the Admin UI under Settings > Secrets Management, then select the Secrets tab, and select Add Secret.

2. Fill in a Name and Description for the secret.

It may be reasonable to correlate this name with the username or with the resource name that you intend to use this credential to access, if it is going to be used for leased credential access to the database. If it is being used for a specific identity using Identity Aliases, it could be named after the specific identity it is mapped to.

1. For Select secret engine, select the engine you just created.

2. Fill in the rest of the form, including resource specific fields and rotation or password complexity information for this secret if you desire it to be different than the defaults for this secret engine, and select Save.

Configure a Resource to use this Secret

Lastly, configure a resource to use this secret to authenticate to a resource.

Fill in the resource configuration as you normally would, but for Secret Store, select the secret store, and for the user credential fields, fill them in with /<SECRET_ENGINE_PATH>/SECRET_PATH?key=<SECRET_KEY>, filling in the values for <SECRET_ENGINE_PATH> from your secret engine configuration, <SECRET_PATH> from your managed secret configuration, and <SECRET_KEY> from the name of the revelant key within this managed secret.

Now you should be able to grant access to this resource to a user through a role, if you have not done so already, or through just in time access with workflows, and attempt accessing it.

Further Reading

• For more about managing secrets, see the main StrongDM Vault section.

• For instructions on entitling users to access particular secrets, see the Entitle Secrets via Policy section.

• For details on managing secret engines with the CLI, see Secrets Management via CLI.