Create a service account library

Create a library of service accounts that users and machines can check out as needed. Vault automatically rotates the account password when clients return the service account to the library.

Before you start

Check your Vault permissions. You must have permission to enable and configure plugins in Vault.
You must have an LDAP plugin configured for OpenLDAP or Active Directory. If you do not already have an LDAP plugin enabled, follow the setup guide.
Create the library accounts on your LDAP server. We highly recommend creating a dedicated accounts for the library.

Step 1: Create a library configuration file

For easier maintenance and reuse, create a JSON file library.json, with the credential library configuration details.

{
  "service_account_names":         "<list_of_LDAP_accounts>",
  "ttl":                           "<default_checkout_period>",
  "max_ttl":                       "<max_allowed_checkout_period>",
  "disable_check_in_enforcement":  "false"
}

For example:

{
  "service_account_names":         "fizz@example.com,buzz@example.com",
  "ttl":                           "10h",
  "max_ttl":                       "24h",
  "disable_check_in_enforcement":  "false"
}

the following configuration file:

defines the set of accounts in the library as fizz@example.com and buzz@example.com
sets a default checkout time of 10 hours
disallows renewals after 24 hours
requires that the same Vault entity or client token checking out a service account also be the one to check the account back into the library.

Tip

If your workflow uses a clean up process such that the client returning the service account regularly uses a different token than the client checking the account out, set disable_check_in_enforcement=true.

Step 2: Configure the plugin

Apply the libray configuration file to your plugin.

Use vault write with the {mount_path}/library/{set_name} path to apply your library.json configuration file:

$ vault write <mount_path>/library/<set_name> @library.json

For example:

$ vault write devcreds/library/accounting-team @library.json

Make a POST call to {mount_path}/library/{set_name} to apply your library.json configuration file:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @library.json                                \
  ${VAULT_ADDR}/v1/<mount_path>/library/<set_name>

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @library.json                                \
  ${VAULT_ADDR}/v1/devcreds/library/accounting-team

Step 3: Verify the service account settings

To verify the library settings, view the set status.

Use vault read with the {mount_path}/library/{set_name} path to check the status of your library:

$ vault read <mount_path>/library/<set_name>

For example:

$ vault read devcreds/library/accounting-team

Key                 Value
---                 -----
buzz@example.com    map[available:true]
fizz@example.com    map[available:true]

Make a POST call to {mount_path}/library/{set_name} to check the status of your library:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/<mount_path>/library/<set_name>

For example:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/devcreds/library/accounting-team

Step 3: Test the check-out process

To test the connection between Vault and your LDAP server, try checking out and returning a service account.

Use vault write with the -f flag and {mount_path}/library/{set_name}/check-out path to request a service account:

$ vault write -f <mount_path>/library/<set_name>/checkout

For example:

$ vault write -f devcreds/library/accounting-team/checkout

Key                     Value
---                     -----
lease_id                devcreds/library/accounting-team/check-out/EpuS8cX7uEsDzOwW9kkKOyGW
lease_duration          10h
lease_renewable         true
password                ?@09AZKh03hBORZPJcTDgLfntlHqxLy29tcQjPVThzuwWAx/Twx4a2ZcRQRqrZ1w
service_account_name    fizz@example.com

Tip

If the default checkout time is longer than you need, omit the -f flag and provide an explict ttl value so Vault can reclaim the account sooner if it becomes abandoned for some reason.

Use vault write with the service account name and {mount_path}/library/{set_name}/check-out path to request a service account:

$ vault write <mount_path>/library/<set_name>/check-in \
  service_account_names=[<account_list>]

For example:

$ vault write -f devcreds/library/accounting-team/check-in \
  service_account_names=["fizz@example.com"]

Tip

If the caller only has one account checked out, you can omit the account list and use the -f flag to call the endpoint without explicit parameters.

Make a POST call to {mount_path}/library/{set_name}/check-in with the service account name to return the service account:

$ curl                                                     \
  --request POST                                           \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"              \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}"      \
  --data '{"service_account_names": [<account_list>]}'     \
  ${VAULT_ADDR}/v1/<mount_path>/library/<set_name>/check-in

For example:

$ curl                                                     \
  --request POST                                           \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"              \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}"      \
  --data '{"service_account_names": ["fizz@example.com"]}' \
  ${VAULT_ADDR}/v1/devcreds/library/accounting-team/check-in

Tip

If the default checkout time is longer than you need, provide an explict ttl value so Vault can reclaim the account sooner if it becomes abandoned for some reason.

Make a POST call to {mount_path}/library/{set_name}/check-out to request a service account:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/<mount_path>/library/<set_name>/checkout

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/devcreds/library/accounting-team/checkout

Tip

If the caller only has one account checked out, you can omit the account list and make an empty POST call to the endpoint.