# Secrets Management via CLI

This section provides Secrets Management configuration steps and usage information for the StrongDM CLI. Administrators can use the [StrongDM CLI](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/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](https://github.com/strongdm/docs/blob/main/gitbook-content/admin/secrets/secrets-management.md#manage-secret-engines-with-the-strongdm-admin-ui) section of this guide.

### Secret Engine CLI Commands

Manage secret engines in the CLI with [sdm admin secretengines](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines "mention") and its subcommands:

* [`sdm admin secretengines create`](#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.

```sh
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.

```sh
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`:

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

Example:

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

{% hint style="info" %}
This tag should be added to all nodes that have been configured to access both the secret store and the external secrets system.
{% endhint %}

See the CLI Reference for a copy of the help text available for [sdm admin secretengines create](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/create "mention").

#### sdm admin secretengines list

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

```sh
sdm admin secretengines list
```

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

```sh
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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/list "mention").

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

```sh
sdm admin secretengines show eng-12a3456b78cd9e1f
```

See the CLI Reference for a copy of the help text available for [sdm admin secretengines show](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/show "mention").

#### 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:

```sh
$ 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/list-available-stores "mention").

#### sdm admin secretengines healthcheck

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

Example:

```sh
$ 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/healthcheck "mention").

**sdm admin secretengines rotate**

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

Example:

```sh
sdm admin secretengines rotate eng-12abc45678d9f1g0
```

See the CLI Reference for a copy of the help text available for [sdm admin secretengines rotate](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/rotate "mention").

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

```sh
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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/update "mention").

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

```sh
sdm admin secretengines delete eng-12a3456b78cd9e1f
```

See the CLI Reference for a copy of the help text available for [sdm admin secretengines delete](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/secretengines/delete "mention").

### Managed Secrets CLI Commands

You can work with managed secrets in the CLI with [sdm admin managedsecrets](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets "mention") 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 update`: updates a managed secret.
* `sdm admin managedsecrets delete`: deletes a managed secret.
* `sdm admin managedsecrets logs`: displays logs for managed secrets.

As well as with the [sdm managedsecrets](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/managedsecrets "mention") commands:

* `sdm managedsecrets list`: list all managed secrets you have access to
* `sdm managedsecrets show`: shows details of a managed secret without sensitive data.
* `sdm managedsecrets retrieve/read`: shows details of a manage secrets with sensitive data.
* `sdm managedsecrets rotate`: rotates a managed secret.
* `sdm managedsecrets validate`: shows whether a managed secret is currently valid.

#### 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:

```sh
sdm admin managedsecrets create <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
```

Example:

```sh
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.

```sh
$ 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/create "mention").

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

```sh
sdm admin managedsecrets list <SECRET_ENGINE_NAME>
```

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

```sh
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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/list "mention").

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

```sh
sdm admin managedsecrets show <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
```

Example:

```sh
$ 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/show "mention").

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

```sh
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:

```sh
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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/update "mention").

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

```sh
sdm admin managedsecrets delete <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
```

Example:

```sh
sdm admin managedsecrets delete exampleAD Bob
```

See the CLI Reference for a copy of the help text available for [sdm admin managedsecrets delete](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/delete "mention").

#### 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:

```sh
$ 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/logs "mention").

#### sdm managedsecrets list

Secrets available to the currently logged in principal are able to be listed with `sdm managedsecrets list`.

```sh
$ sdm managedsecrets list
```

See the CLI Reference for a copy of the help text available for [sdm managedsecrets list](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/managedsecrets/list "mention")

#### sdm managedsecrets show

Use `sdm managedsecrets show` to show details about a specific secret without showing the sensitive data associated with it, such as password values.

```sh
sdm managedsecrets show <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
```

See the CLI Reference for a copy of the help text available for [sdm managedsecrets show](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/managedsecrets/show "mention").

#### sdm managedsecrets retrieve

Use `sdm managedsecrets retrieve` to show details about a specific secret that include the sensitive data associated with it, such as password values.

```sh
sdm managedsecrets retrieve <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
```

See the CLI Reference for a copy of the help text available for [sdm managedsecrets retrieve](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/managedsecrets/retrieve "mention").

Managed secrets also may be retrieved in the Admin UI's **Access** > **Secrets** page.

#### sdm managedsecrets rotate

Secrets created with a secret engine that allows rotation are able to be rotated with `sdm 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:

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

See the CLI Reference for a copy of the help text available for [sdm managedsecrets rotate](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/managedsecrets/rotate "mention")

Managed secrets also may be rotated in the Admin UI's **Access** > **Secrets** page.

#### sdm managedsecrets validate

Use `sdm managedsecrets validate` to show whether a managed secret is currently valid. When running the command, specify the name of the secret engine and the name of the managed secret.

```sh
sdm managedsecrets validate <SECRET_ENGINE_NAME> <MANAGED_SECRET_NAME>
```

Example:

```sh
sdm managedsecrets validate exampleAD Bob
```

See the CLI Reference for a copy of the help text available for [sdm managedsecrets validate](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/managedsecrets/validate "mention").

Managed secrets also may be validated in the Admin UI's **Access** > **Secrets** page.

### Configure 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](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/admin/managedsecrets/create)
* [sdm admin managedsecrets update](https://app.gitbook.com/s/4XOJmXFslCMVCzIG2rKp/cli/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.

```sh
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
```