# AD Secret Engine {% hint style="info" %} This feature is part of the Enterprise plan. If it is not enabled for your organization, please contact StrongDM at the [StrongDM Help Center](https://help.strongdm.com/hc/en-us). {% endhint %} 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](https://docs.strongdm.com/admin/access/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** as the type of secret engine, and then set the following properties, then click save. {% hint style="info" %} 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. {% endhint %} ### Secret engine properties These properties are required, other than **Node Selector** and **Tags**. | Property | Requirement | Description | | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | Required | Descriptive name that clearly indicates what the engine is for | | **Secret Store** | Required | Secret store where the secrets you wish to manage are located | | **Secret Store Root Path** | Required | Path to the secret store where the secrets are located, for example, `/secret/data/ad` | | **Node Selector** | Optional | Tag that you intend to attach to node(s) (gateways, relays, proxy clusters) that you wish to be used to contact your secret store; if a value is provided, only nodes with this exact tag will be used to interact with this secret engine; if blank, any healthy node is used | | **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: ```sh 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__=true`: ```sh 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. ```sh $ 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.
```shellscript 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:
```shellscript 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets) and [sdm managedsecrets](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/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: ```sh 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: ```sh 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. ```sh 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](https://docs.strongdm.com/admin/principals/identity-alias), it could be named after the specific identity it is mapped to. 3. For **Select secret engine**, select the engine you just created. 4. 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_PATH?key=`, filling in the values for `` from your secret engine configuration, `` from your managed secret configuration, and `` 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](https://docs.strongdm.com/admin/secrets) section. * For instructions on entitling users to access particular secrets, see the [Entitle Secrets via Policy](https://docs.strongdm.com/admin/secrets/policy-secrets-management) section. * For details on managing secret engines with the CLI, see [Secrets Management via CLI](https://docs.strongdm.com/admin/secrets/secrets-management-cli).