Secrets Management

Overview #

Secrets Management in StrongDM allows administrators to control access to and rotate secrets stored in various secret stores. This guide explains how to use the StrongDM Admin UI and CLI to set up Secrets Management, validate and rotate managed secrets, and define policies for user access to secrets.

Secret Stores #

Secrets such as username/password credentials or other “secret” data are stored in your organization’s user-provided secret stores. The currently supported secret store types for Secrets Manager are AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, and HashiCorp Vault.

Secret stores need to be configured first in order to connect to StrongDM and enable StrongDM to manage user access and rotation of the stored secrets. Please see the secret stores documentation to learn how to add secret stores to your StrongDM environment.

Secret Engines and Managed Secrets #

A secret engine is what connects StrongDM to the secret store. When a secret engine is created in StrongDM, the ID of the secret store to be used and the secret store root path where the secret engine’s configuration will be stored are specified. For HashiCorp Vault, the secret store root path is a path inside a HashiCorp Vault KV engine.

Your secrets are still kept in the secret store, but they are “managed secrets” because you are using the StrongDM secret engine to manage how and when users access secrets, facilitate the rotation of eligible secrets, and set password complexity rules for secrets that are rotated and updated. All managed secrets paths that are managed by the secret engine begin with the configured secret store root path.

Supported Secret Engines #

StrongDM supports the following types of secret engines for Secrets Management:

• Active Directory (AD): Manages and rotates passwords for AD accounts
• Key Value: Stores secrets without rotation

Note that all secret engine types require a backing secret store.

Prerequisites #

To set up Secrets Management, the following general requirements must be met:

• Have the Admin permission level in StrongDM.
• Have a secret store integration configured in StrongDM.

AD secret engine prerequisites #

If you intend to use an Active Directory (AD) secret engine, please note the following information and prerequisites that are specific to AD. This information is important because only secrets for AD accounts managed within StrongDM (not Key Value managed secrets) can be rotated via StrongDM Secrets Management.

The AD connection is set up within either the StrongDM Admin UI or the StrongDM CLI, and the process generally involves providing AD configuration information to connect to the on-premises AD and enabling secrets updates within AD. Connection to AD is orchestrated through StrongDM nodes. Once the connection is established, the secrets are rotated on AD.

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.

For AD, the following requirements must be met:

• The user must have the privilege to change passwords for users in scope detailed in the Required AD account privileges section.
• Authorization details must be provided during configuration.
• Open port 636 for TLS encrypted connections.
• Open port 389 for unencrypted connections.

Required 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.

Secrets Management in the Admin UI #

This section provides instructions on how to set up Secrets Management in the StrongDM Admin UI. The process generally involves configuring secret store integration, adding managed secrets, creating a secret engine to facilitate the management of the managed secrets in the secret store, and entitling users to the managed secrets via policy. When setup is complete, eligible users can view managed secrets in either the Admin UI or CLI.

If you wish to use the CLI instead of the Admin UI, please see the Secrets Management in the CLI section of this guide.

Add a secret store #

If you haven’t already done so, configure secret store integration with StrongDM. This ensures that a secret store is already set up to contain secrets that can be managed. You may skip this step if you already have a secret store configured.

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

1. Log in to the Admin UI and go to Settings > Secrets Management. The settings that display are organized into four tabs for setting up secret stores, secret engines, secrets, and certificate authorities.
2. Select the Secret Stores tab and click the add secret store button.
3. On the form that displays, set the properties for the specific secret store you wish to add. Please see the secret store documentation for requirements, properties, and configuration details for your specific secret store type.

The Secret Stores tab now displays the secret store that you just added.

Create a secret engine #

You can add either an Active Directory (AD) or Key Value secret engine to your organization. If you intend to add an AD secret engine, please see the prerequisites for AD secret engines. This information is important because only AD managed secrets (not Key Value) can be rotated via StrongDM Secrets Management.

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, set the following properties:
   • Name: Enter a unique name for the secret engine. This name will display throughout StrongDM and help you to identify the secret engine.
   • Key-Value: This type of secret engine does not support the rotation of managed secrets. Select Key-Value if you want to manage access to secrets in a secret store without rotating them.
   • Active-Directory: This type of secret engine supports the rotation of managed secrets in Active Directory. Select Active-Directory if you want to both manage access to secrets in AD and be able to rotate them.
   • Secret Store: Use the dropdown menu to select the name of the secret store where your secrets are located.
   • Secret Store Root Path: Enter the path to the secret store or Active Directory, where the secrets are located (for example, /secret/data/ad).
   • Select node(s): Use the dropdown menu to select the name of the node (gateway or relay) to be used to contact the secret store or Active Directory.
   • Select or add tags: Optionally assign tags to the secret engine.
4. Click Save.

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

Add managed secrets #

To add managed secrets in the Admin UI, follow these steps.

1. In the Admin UI and go to Settings > Secrets Management.
2. Select the Secrets tab and click Add Secrets.
3. On the dialog that displays, set the following properties:
   • Name: Enter a unique name for this secret. This name will display throughout StrongDM and help you to identify the managed secret.
   • Description: Optionally enter a description of the secret to help you to remember what it is for.
   • Select Secret Engine: Use the dropdown menu to select the secret engine to use to manage how and when users access secrets and facilitate the rotation of secrets.
   • Select or add tags: Optionally assign tags to the managed secret.
4. Click Save.

The Secrets tab now displays the secret that you just added, along with any other managed secrets that have been added via the Admin UI and CLI. You may now edit the secret’s settings in order to schedule rotation and set a password complexity rules, view entitlements for the secret, and see any activities related to the secret.

Secrets settings #

After you have created a managed secret, you can set password complexity requirements, such as the number of symbols required, for passwords that are generated, rotated, or updated, to suit the needs of your organization.

For AD managed secrets only (not Key Value), you may schedule automatic password rotation by setting the credential rotation interval. A secret is valid for the given amount of time set, after which it is automatically rotated. If no interval is set or it is set to the default zero seconds, then there is no automatic password rotation, and rotation will need to be done manually for the secret on the Secrets tab.

The Settings tab is where you can update the secret’s properties, set your password policy, and schedule automatic rotation. To get to the settings in the Admin UI, go back to Settings > Secrets Management Secrets. Click on the name of a managed secret and then click on the Settings tab to view or edit the secret’s details. Alternatively, you can click Actions > View.

The following properties are shown on the Settings tab.

Secrets entitlements #

From the Secrets tab, click on the name of a managed secret and then click on the Entitlements tab to view all the entitlements for the selected secret. Alternatively, you can click Actions > View. For managed secrets, entitlements are the specific actions (for example, retrieve, rotate, or validate) that the user or service account is allowed to perform on the given secret, as permitted by policy.

The Entitlements tab displays the following fields.

Secrets activity #

From the Secrets tab, click on the name of a managed secret and then click on the Activity tab to view all activities for the selected secret. Alternatively, you can click Actions > View.

For managed secrets, activities are the actions that a user has taken on the managed secret (for example, viewing, rotating, or validating). Note that activities are different than entitlements, as activities are what the user has actually done versus what the user is permitted to do.

The Activity tab displays the following fields.

Entitlement of Secrets to Users and Groups and PBAC #

Once managed secrets and secret engines are fully configured, via the Admin UI or CLI, you may create policies to entitle managed secrets to users and/or groups of users, as well as enforce fine-grained policy-based access control (PBAC) for the users who are entitled to access those managed secrets. Entitlement means using policies to allow specific users or groups of users to access and perform specific actions on managed secrets. Your policy statements can specify the users permitted to access specific secrets and what actions users are permitted to perform, such as reading, retrieving, rotating, or validating managed secrets. These policies can also include annotations (to require users to justify their actions, or receive an MFA challenge) and context-based conditions (such as access based on the user’s location) for enhanced control and flexibility.

After such policies are saved, entitlements for managed secrets are shown in the Admin UI in Settings > Secrets Management > Secrets > Entitlements.

The sections that follow describe how to structure policy statements to allow users and/or groups to access and perform actions on managed secrets. For all other information about policies, please see Policies.

Actions for Secrets Management #

In a policy statement, StrongDM Secrets Management actions are set in the format StrongDM::ManagedSecret::Action::"<ACTION>", where <ACTION> is the name of the action (for example, StrongDM::ManagedSecret::Action::"rotate").

The possible actions for managed secrets are:

• read
• retrieve
• rotate
• validate

The resource in the policy statement also must be set as resource is StrongDM::ManagedSecret.

In the Policy Editor, if you are typing into the editing area directly, enter the action(s) (and resource) in the following way.

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"retrieve"],
    resource is StrongDM::ManagedSecret
);

If multiple actions on managed secrets are allowed, enter each action in the following way.

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
);

Actions for managed secrets may be set in policy statements in combination with context and annotations. Examples are shown in the next section.

Example policy statements for entitlement and PBAC #

This section provides some examples of policy statements that entitle managed secrets to users and groups, as well as enforce policy actions on managed secrets operations.

Allow users to conduct particular Secrets Management actions when the user’s employeeNumber matches the managed secret’s employeeNumber tag value:

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"validate", StrongDM::ManagedSecret::Action::"rotate"],
    resource is StrongDM::ManagedSecret
) when {
    principal.employeeNumber != "" &&
        resource.tags["employeeNumber"] == principal.employeeNumber
    };

Allow retrieval of managed secrets where the user’s employeeNumber matches the value of the managed secret’s employeeNumber tag:

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"retrieve"],
    resource is StrongDM::ManagedSecret
) when {
    principal.employeeNumber != "" &&
        resource.tags["employeeNumber"] == principal.employeeNumber
    };

Allow users with the “secrets-admin” role to perform public read/rotate/validate actions on managed secrets (note that the role value is the role ID rather than the role name in the example shown):

permit (
    principal in StrongDM::Role::"r-5e367aa86759a7b8",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
);

Allow users with the “production-access” role to perform retrieve/public read/rotate/validate actions on managed secrets tagged with env=production:

@justify("Please provide a reason to do this.")
permit (
    principal in StrongDM::Role::"r-3618ea926759a881",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.getTag("env") == "production"
    };

Allow users with the “development-access” role to perform retrieve/public read/rotate/validate actions on managed secrets tagged with env=development:

@justify("Please provide a reason to do this.")
permit (
    principal in StrongDM::Role::"r-496d29476759a8c6",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.getTag("env") == "development"
    };

Allow users with the “staging-access” role to perform retrieve/public read/rotate/validate actions on managed secrets tagged with env=development:

permit (
    principal in StrongDM::Role::"r-2725a45a6759a8ed",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.getTag("env") == "staging"
    };

Allow retrieve/public read/rotate/validate actions on managed secrets tagged with “owner” equal to the principal’s email:

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.getTag("owner") == principal.email
};

Allow admins to access managed secrets:

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    principal.permissionLevel == "admin"
    };

Allow all Secrets Management actions on secrets tagged with foo=bar:

permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"validate", StrongDM::Action::"rotate", StrongDM::ManagedSecret::Action::"retrieve"],
    resource is StrongDM::ManagedSecret
) when {
    resource.tags["foo"] == "bar"
};

Forbid access to managed secrets if there is an error:

@error("this is a test")
forbid (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve"],
    resource
) when {
    context.network.clientIp.isInRange(ip("99.174.173.5/32"))
};

Logging #

Logs for secrets retrieval and rotation are recorded in the following areas within StrongDM:

• Activity logs: Secret engine and managed secrets activities
• Secrets logs: All user activity related to rotation, validation, and retrieval operations
• Policy logs: Any activity that matches the defined policy

All admin actions to set up Secrets Management and rotation are recorded in logs, including when a secret engine or managed secret is created, updated, and deleted. Rotation and retrieval of managed secrets are logged when the expiration time of the managed secret is changed.

End User Interaction With Secrets #

Users who are eligible to view secrets may do so from the Admin UI in Settings > Secrets Management > Secrets tab. In addition, users can see the actions (such as read, retrieve, rotate, and validate) they can perform on the managed secrets based on the access being provided by the admin.

The Secrets tab displays the following details for each secret:

• Name: Name of the secret
• Type: Type of secret, either Active Directory or Key Value
• Secret Engine: Name of the secret engine to be used to manage the secret
• Tags: Any tags associated with the secret
• Actions: Possible actions to take on the secret, either view or delete

If users are not entitled to view or take any action on managed secrets, the Secrets tab is empty.

Secrets Management in the CLI #

This section provides Secrets Management configuration steps and usage information for the StrongDM CLI. Administrators can use the StrongDM CLI to add, update, read, delete, and otherwise manage secret engines and managed secrets.

If you wish to use the Admin UI instead of the CLI, please see the Admin UI section of this guide.

Secret engine CLI commands #

Manage secret engines in the CLI with sdm admin secretengines and its subcommands:

• sdm admin secretengines create: Creates a new secret engine
• sdm admin secretengines list: Lists all secret engines in your organization
• sdm admin secretengines show: Shows details about a secret engine
• sdm admin secretengines list-available-stores: Lists the secret stores that can be used with the secret engines in your organization
• sdm admin secretengines healthcheck: Checks the health of secret engines on all nodes
• sdm admin secretengines rotate: Rotates a secret engine’s credentials
• sdm admin secretengines update: Updates the secret engine
• sdm admin secretengines delete: Deletes a secret engine

sdm admin secretengines create #

The sdm admin secretengines create command is used to add a new secret engine to your organization. You can create an AD (active_directory) secret engine or Key Value (key_value) secret engine.

To create an AD secret engine, run the sdm admin secretengines create active_directory command with all required options set, as in the following example.

sdm admin secretengines create active_directory
--binddn "cn=admin,dc=example,dc=com"
--bindpass="Example"
--secret-store-id se-1234a12345bcd123
--name exampleAD
--url ldaps://<HOSTNAME>:<PORT>
--secret-store-root-path="/secret/data/ad"

For the --secret-store-id option, the value should be the ID of an existing secret store. For --url, the URL should be in the format <HOSTNAME>:<PORT>, prepended by either ldap:// for an unencrypted connection or ldaps:// for a TLS encrypted connection.

To create a Key Value secret engine, run sdm admin secretengines create key_value with all required options set, as in the following example.

sdm admin secretengines create key_value
--secret-store-id se-1234a12345bcd125
--name exampleKeyValue
--secret-store-root-path="/secret/data/keyvalue"

After secret engine creation, configure the node (gateway or relay) to be used to contact the secret store or Active Directory. To do this, run the following command to update the relevant node and set a tag in the form of eng__<SECRET_ENGINE_NAME>=true:

sdm admin nodes update <NODE_ID> --tags eng__<SECRET_ENGINE_NAME>=true

Example:

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

See the CLI Reference for a copy of the help text available for sdm admin secretengines create.

sdm admin secretengines list #

Use the following command to list all existing secret engines in your organization.

sdm admin secretengines list

If any secret engines are already created, the returned output looks similar to the following.

ID                      Name        Type                Tags    Secret Store            Secret Store Root Path
eng-12a3456b78cd9e1f    AD          active_directory            se-1234a12345bcd123     /secret/data/ad
eng-22a3456b78cd9e1h    Key Value   key_value                   se-1234a12345bcd125     /secret/data/keyvalue

See the CLI Reference for a copy of the help text available for sdm admin secretengines list.

sdm admin secretengines show #

Use sdm admin secretengines show to show details about a specific secret engine. You must specify the secret engine ID, as in the following example.

sdm admin secretengines show eng-12a3456b78cd9e1f

See the CLI Reference for a copy of the help text available for sdm admin secretengines show.

sdm admin secretengines list-available-stores #

Use sdm admin secretengines list-available-stores to list the secret stores that can be used with the secret engines in your organization.

Example:

$ sdm admin secretengines list-available-stores   
ID                      Name                  Type           Tags
se-0e111e2222db33fa     secretStore1        gcp            
se-111c222222b33ad4     vaultExample         vaultToken     
se-1ad22ac3333e4444     vaultExample2       vaultToken 

See the CLI Reference for a copy of the help text available for sdm admin secretengines list-available-stores.

sdm admin secretengines healthcheck #

Use sdm admin secretengines healthcheck <SECRET_ENGINE_ID> to check the health of a secret engine on nodes.

Example:

$ sdm admin secretengines healthcheck eng-12abc45678d9f1g0
nodeID                 status
n-123123ab123123c1     OK

See the CLI Reference for a copy of the help text available for sdm admin secretengines healthcheck.

sdm admin secretengines rotate #

Use sdm admin secretengines rotate <SECRET_ENGINE_ID> to rotate a secret engine’s secrets.

Example:

sdm admin secretengines rotate eng-12abc45678d9f1g0

See the CLI Reference for a copy of the help text available for sdm admin secretengines rotate.

sdm admin secretengines update #

Use sdm admin secretengines update to make changes to a specific secret engine. You must specify the secret engine type (active_directory or key_value), and set the options that you wish you change, as in the following example.

sdm admin secretengines update active_directory --name New AD Name

See the CLI Reference for a copy of the help text available for sdm admin secretengines update.

sdm admin secretengines delete #

Use sdm admin secretengines delete to delete a secret engine. You must specify the secret engine ID, as in the following example.

sdm admin secretengines delete eng-12a3456b78cd9e1f

See the CLI Reference for a copy of the help text available for sdm admin secretengines delete.

Managed secrets CLI commands #

You can work with managed secrets in the CLI with sdm admin managedsecrets and its subcommands:

• sdm admin managedsecrets create creates a new managed secret.
• sdm admin managedsecrets list lists all managed secrets in the secret engine.
• sdm admin managedsecrets show shows details of managed secrets without sensitive data.
• sdm admin managedsecrets rotate rotates a managed secret.
• sdm admin managedsecrets update updates a managed secret.
• sdm admin managedsecrets delete deletes a managed secret.
• sdm admin managedsecrets logs displays logs for managed secrets.

sdm admin managedsecrets create #

Use sdm admin managedsecrets create to add secrets for a user for a specific secret engine. When running this command, you must, at minimum, specify the secret engine name and the desired name for the secrets you’re adding.

For Key Value, run the following:

sdm admin managedsecrets create <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>

Example:

sdm admin managedsecrets create key_value alice

For Active Directory, you also must set the user_dn, which is the distinguished name of the account that is managed.

In the following example, secrets are created for user Bob for an AD secret engine.

$ sdm admin managedsecrets create exampleAD Bob user_dn="cn=Bob Belcher,ou=people,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

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets create.

sdm admin managedsecrets list #

Use the following command to list all existing managed secrets in your organization. You must specify the name of the secret engine being used.

sdm admin managedsecrets list <SECRET_ENGINE_NAME>

If any managed secrets are already present, the returned output looks similar to the following.

ID                      Secret Engine ID         Name           Last Rotated At     Next Rotation At     Tags
ms-1111f22b33e4fb55     eng-1234aa5678e9faab     exampleAD     NEVER               NEVER                employeeNumber=12345

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets list.

sdm admin managedsecrets show #

Use this command to get information about a specific managed secret and the associated secret engine. The returned details include the secret engine ID, when the secrets were last rotated (if ever), when their next rotation is scheduled to occur (if at all), information about the password complexity policy, and any tags associated with the secrets. When running this command, you must specify the name of the secret engine and the name of the managed secret.

sdm admin managedsecrets show <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>

Example:

$ sdm admin managedsecrets show exampleAD exampleManagedSecret
ID                   ms-1111f22b33e4fb55
Secret Engine ID     eng-1234aa5678e9faab
Name                 exampleManagedSecret
Last Rotated At      NEVER
Next Rotation At     NEVER
Policy               PasswordPolicy: Length: 0, Digits: 0, Symbols: 0, AllowRepeat: false, ExcludedCharacters: "", ExcludeUpperCase: false
Tags                 employeeNumber=12345

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets show.

sdm admin managedsecrets rotate #

Secrets created for AD (active_directory) secret engines are able to be rotated with sdm admin managedsecrets rotate. For example, to rotate user Bob’s password, run the following command with the name of the secret engine and the name of the managed secret:

$ sdm admin managedsecrets rotate exampleAD Bob
Rotated managed secret: ms-1a234b5c67de8912

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets rotate.

sdm admin managedsecrets update #

Use sdm admin managedsecrets update to make changes to existing secrets for a specific secret engine. When running the command, specify the name of the secret engine, the name of the managed secret, and the new values of the options that you want to update.

sdm admin managedsecrets update <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
--name value
--password-length value
--password-num-digits value
--password-num-symbols value
--password-allow-repeat bool 
--password-exclude-characters value
--password-exclude-uppercase bool
--delete-password-policy bool
--password value
--user-dn value
--ttl value
--after-read-ttl value

Example:

sdm admin managedsecrets update exampleAD Bob
--name new-secrets-name
--password-length 50
--password-num-digits 50
--password-num-symbols 2

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets update.

sdm admin managedsecrets delete #

Use sdm admin managedsecrets delete to delete secrets. When running the command, specify the name of the secret engine and the name of the managed secret.

sdm admin managedsecrets delete <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>

Example:

sdm admin managedsecrets delete exampleAD Bob

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets delete.

sdm admin managedsecrets logs #

Use sdm admin managedsecrets logs to get information about managed secrets, including the date and time when the secrets were created, the ID of the secret engine they were created for, the account ID of the user using them, and the last action taken.

Example:

$ sdm admin managedsecrets logs
ID                   Created At                               Managed Secret ID       Secret Engine ID         Account ID             Action       Debug
77ac90f066fa7d79     2024-09-30 10:29:13.485862 +0000 UTC     ms-1111f22b33e4fb55     eng-1234aa5678e9faab     a-123a4567890af1c2     validate 

See the CLI Reference for a copy of the help text available for sdm admin managedsecrets logs.

Schedule Automatic Password Rotation in the CLI #

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 admin secretengines rotate or on the Admin UI’s 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=admin,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=Bob Belcher,ou=people,dc=example,dc=com"
--ttl="12h"

Set maximum backoff duration in the CLI #

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=admin,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"

Set Password Complexity Requirements in the CLI #

When a managed secret is created, you have the option to set password complexity requirements, such as the number of symbols required, for passwords that are generated, rotated, or updated, to suit the needs of your organization. The available options for passwords are:

• --password-length: Password length (default: 0)
• --password-num-digits: Number of digits to use when generating the password (default: 0)
• --password-num-symbols: Number of symbols to use when generating the password (default: 0)
• --password-allow-repeat: If set to true, allows for consecutive characters to repeat
• --password-exclude-characters: Set of characters to exclude when generating password

Password complexity requirements may be set as options with the following CLI commands:

• sdm admin managedsecrets create
• sdm admin managedsecrets update

In the following example, the AD managed secret is updated to require generated passwords to be 24 digits long, have 2 symbols, exclude # characters, and not repeat themselves or exclude uppercase letters.

sdm admin managedsecrets update exampleAD Bob
--password-length="24"
--password-num-digits="24"
--password-num-symbols="2"
--password-allow-repeat=false
--password-exclude-characters="#"
--password-exclude-uppercase=false

AD Secrets Management Setup in the CLI #

Your organization can use StrongDM to facilitate the rotation of secrets for Active Directory (AD) accounts managed within StrongDM. The AD connection is set up within the StrongDM CLI, and the process generally involves providing AD configuration information to connect to the on-premises AD and enabling secrets updates within AD. Connection to AD is orchestrated through StrongDM nodes. Once the connection is established, the secrets are rotated on AD. This section provides information about the requirements for AD Secrets Management and provides an example of how to use the CLI commands to manage AD secret engines and managed secrets.

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.

For AD, the following requirements must be met:

• The user must have the privilege to change passwords for users in scope detailed in the Required AD account privileges section.
• Authorization details must be provided during configuration.
• Open port 636 for TLS encrypted connections.
• Open port 389 for unencrypted connections.

Required 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.

CLI example for AD #

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=admin,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=Bob Belcher,ou=example,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.

   $ sdm admin managedsecrets show AD Bob
   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
   last_rotated_at:2024-08-28T14:17.22.26234Z password:fdlsfjkdsjflksdjflskdjgdkl,user_dn:cn=Bob Belcher,ou=example,dc=example,dc=com]
   Tags
   

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 admin secretengines rotate AD Bob
   Rotated managed secret: ms-1a234b5c67de8912
   

6. Retrieve the new password to confirm that the rotation was successful. Notice that the Secret Value is different and there is now a date and time for the last rotation.

   $ sdm admin managedsecrets show AD Bob
   ID                   ms-1a234b5c67de8912
   Secret Engine ID     eng-12a3456b78cd9e1f
   Name                 Bob
   Last Rotated At      2024-08-28T14:17.30.00000Z
   Next Rotation At     NEVER
   Policy               password.excludeuppercase=false,password.length=0,password.numsymbols=0,password.numdigits=0.password.allowrepeat=false
   last_rotated_at:2024-08-28T14:17.30.00000Z password:abcabcabcabcabcabcabcabcab,user_dn:cn=Bob Belcher,ou=example,dc=example,dc=com]
   Tags
   

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

Key Value Secrets Management Setup #

Your organization can use the Key Value secret engine to manage access to secrets in a secret store without rotating them. This section provides an example of how to use the CLI commands to manage Key Value secret engines and managed secrets.

CLI example for Key Value #

1. Get the ID of an available secret store to be used for storing secrets:

   $ sdm admin secretengines list-available-stores
   ID                      Name         Type           Tags
   se-0e599e2866db23fa     example 1    gcp            
   se-102c276965b83ad9     example 2    vaultToken     
   se-3ad72ac6620e8038     example 3    vaultToken
   

2. Create the secret engine:

   sdm admin secretengines create key_value
   --name keyvalue-example
   --secret-store-id se-1ab23ac6620e8038
   --secret-store-root-path="/secret/data/keyvalue"
   

3. Configure the node (gateway or relay) to be used to contact the secret store. 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__keyvalue-example=true
   

4. Define a managed secret that will manage the passwords for a user:

   $ sdm admin managedsecrets create key_value alice username=alice password=pass1
   ID                   ms-2de34ab567c8b910
   Secret Engine ID     eng-3b4b567891c23dd4
   Name                 alice
   Last Rotated At      <nil>
   Policy               password.allowrepeat=false,password.excludeuppercase=false,password.length=0,password.numsymbols=0,password.numdigits=0
   Tags                
   

5. Retrieve the password for the created user, which is shown in the Secret Value that is returned:

   $ sdm admin managedsecrets show key_value alice
   ID                    ms-2de34ab567c8b910
   Secret Engine ID      eng-3b4b567891c23dd4
   Name                  alice
   Last Rotated At       <nil>
   Policy                password.allowrepeat=false,password.excludeuppercase=false,password.length=0,password.numsymbols=0,password.numdigits=0
   Secret Store Path    
   Secret Value          password=pass1,username=alice
   Tags                  
   

6. Make changes to the managed secret:

   $ sdm admin managedsecrets update key_value alice email=alice.glick@strongdm.com
   ID                   ms-2de34ab567c8b910
   Secret Engine ID     eng-3b4b567891c23dd4
   Name                 alice
   Last Rotated At      <nil>
   Policy               password.numsymbols=0,password.numdigits=0,password.allowrepeat=false,password.excludeuppercase=false,password.length=0
   Tags                
   

7. View details about the managed secret to confirm the changes were made:

   $ sdm admin managedsecrets show key_value alice                        
   ID                    ms-2de34ab567c8b910
   Secret Engine ID      eng-3b4b567891c23dd4
   Name                  alice
   Last Rotated At       <nil>
   Policy                password.length=0,password.numsymbols=0,password.numdigits=0,password.allowrepeat=false,password.excludeuppercase=false
   Secret Store Path    
   Secret Value          username=alice,email=alice.glick@strongdm.com,password=pass1
   Tags        
   

8. List all managed secrets for the secret engine:

   $ sdm admin managedsecrets list key_value                              
   ID                      Secret Engine ID         Name    Last Rotated At     Tags
   ms-01b0524966c590c6     eng-3b4b567891c23dd4     alice   <nil>              
   

9. Delete the managed secret:

   $ sdm admin managedsecrets delete key_value alice
   Deleted managed secret: ms-2de34ab567c8b910
   

10. Optionally log in to the Admin UI and go to Access > Secrets to view and validate managed secrets.

You can find resources and information about the following StrongDM topics in this section:

• Certificate Authorities
• Secret Stores