Orchestrator user guide

DELIVERY:

Last updated Apr 28, 2025

HashiCorp Vault Integration

HashiCorp Vault is a plugin you can use as a credential store with Orchestrator.

There are two plugins included:

HashiCorp Vault – a read-write plugin (secrets are created through Orchestrator)
HashiCorp Vault (read-only) – a read-only plugin (you must provision the secrets in the vault directly)

Prerequisites

You must configure one of the supported authentication methods:
- AppRole (recommended)
- UsernamePassword
- LDAP
- Token
  
  See how to configure authentication.
You must configure one of the supported secrets engines:
- KeyValueV1 - available for both HashiCorp Vault and HashiCorp Vault (read-only) plugins
- KeyValueV2 - available for both HashiCorp Vault and HashiCorp Vault (read-only) plugins
- ActiveDirectory - available only for HashiCorp Vault (read-only) plugin
The chosen authentication method must have a policy that allows the following capabilities on the path where you plan to store your secrets:
- For HashiCorp Vault (read-only) plugin: read
- For HashiCorp Vault plugin: create, read, update, delete, and optionally delete on the metadata path, if using the KeyValueV2 secrets engine

Configuring the Integration

The following is an example of how to configure a development version of HashiCorp Vault, running in a docker container, to be used as a credential store with Orchestrator. The examples should be adapted to your own environment. Please consult the official documentation of HashiCorp Vault for details.

Configuring Authentication

To start creating and reading secrets, you first need to configure the authentication method by taking the following steps:

Open a shell inside the container:
```
docker exec -it dev-vault shdocker exec -it dev-vault sh
```
Log in as root. Make sure you have the root token displayed in the logs to set an environment variable with it by running the following command:
```
export VAULT_TOKEN=s.hA7RJ5lBqSnKUPd8nrQBaK1fexport VAULT_TOKEN=s.hA7RJ5lBqSnKUPd8nrQBaK1f
```
Check the Vault status by running the following command:
```
vault statusvault status
```

Add a dummy secret for Orchestrator in the KV store:

vault kv put secret/applications/orchestrator/testSecret supersecretpassword=123456vault kv put secret/applications/orchestrator/testSecret supersecretpassword=123456

Give Orchestrator access to the newly created secret/applications/orchestrator path. For this, you must first create a policy for reading and writing to this path and all its subpaths by running the following command:
```
cat <<EOF | vault policy write orchestrator-policy -
path "secret/data/applications/orchestrator/*" {
  capabilities = ["create", "read", "update", "delete"]
}
path "secret/metadata/applications/orchestrator/*" {
  capabilities = ["delete"]
}
EOFcat <<EOF | vault policy write orchestrator-policy -
path "secret/data/applications/orchestrator/*" {
  capabilities = ["create", "read", "update", "delete"]
}
path "secret/metadata/applications/orchestrator/*" {
  capabilities = ["delete"]
}
EOF
```
Note:
When using a KeyValueV2 secrets engine , secrets are written and fetched at path <mount>/data/<secret-path>, as opposed to <mount>/<secret-path> in KeyValueV1. It does not change any of the CLI commands (i.e., you do not specify data in your path).

However, it does change the policies, since capabilities are applied to the real path. In the previous example, the path is secret/data/applications/orchestrator/* since we are working with a KeyValueV2 secrets engine. If a KeyValueV2 were used, the path would have been secret/applications/orchestrator/*.

The capability to delete on the metadata path is needed only if you want to ensure Orchestrator does not leave behind test keys when verifying connectivity. If this capability is not granted, then a key will be created and left behind when creating the Credential Store in Orchestrator.
Enable authentication using the userpass authentication method, then create a user for Orchestrator and assign the previously created policy:
```
vault auth enable userpass
vault write auth/userpass/users/orchestrator password=123456 policies=orchestrator-policyvault auth enable userpass
vault write auth/userpass/users/orchestrator password=123456 policies=orchestrator-policy
```
Note: Orchestrator supports multiple authentication modes. See the HashiCorp Vault documentation for how to configure them.

Check that you have configured everything correctly by logging in and trying to read the secret you created earlier:

vault login -method=userpass username=orchestrator password=123456vault login -method=userpass username=orchestrator password=123456

Output of this command:

WARNING! The VAULT_TOKEN environment variable is set! This takes precedence
over the value set by this command. To use the value set by this command,
unset the VAULT_TOKEN environment variable or set it to the token displayed
below.
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key                    Value
---                    -----
token                  s.nwombWQH3gGPDhJumRzxKqgI
token_accessor         aGJL6Pzc6fRRuP8d8tTjS2Kj
token_duration         768h
token_renewable        true
token_policies         ["default" "orchestrator-policy"]
identity_policies      []
policies               ["default" "orchestrator-policy"]
token_meta_username    orchestratorWARNING! The VAULT_TOKEN environment variable is set! This takes precedence
over the value set by this command. To use the value set by this command,
unset the VAULT_TOKEN environment variable or set it to the token displayed
below.
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key                    Value
---                    -----
token                  s.nwombWQH3gGPDhJumRzxKqgI
token_accessor         aGJL6Pzc6fRRuP8d8tTjS2Kj
token_duration         768h
token_renewable        true
token_policies         ["default" "orchestrator-policy"]
identity_policies      []
policies               ["default" "orchestrator-policy"]
token_meta_username    orchestratorWARNING! The VAULT_TOKEN environment variable is set! This takes precedence
over the value set by this command. To use the value set by this command,
unset the VAULT_TOKEN environment variable or set it to the token displayed
below.
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key                    Value
---                    -----
token                  s.nwombWQH3gGPDhJumRzxKqgI
token_accessor         aGJL6Pzc6fRRuP8d8tTjS2Kj
token_duration         768h
token_renewable        true
token_policies         ["default" "orchestrator-policy"]
identity_policies      []
policies               ["default" "orchestrator-policy"]
token_meta_username    orchestratorWARNING! The VAULT_TOKEN environment variable is set! This takes precedence
over the value set by this command. To use the value set by this command,
unset the VAULT_TOKEN environment variable or set it to the token displayed
below.
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key                    Value
---                    -----
token                  s.nwombWQH3gGPDhJumRzxKqgI
token_accessor         aGJL6Pzc6fRRuP8d8tTjS2Kj
token_duration         768h
token_renewable        true
token_policies         ["default" "orchestrator-policy"]
identity_policies      []
policies               ["default" "orchestrator-policy"]
token_meta_username    orchestrator

Take this token and set it instead of the root token, then try to read the test secret:

export VAULT_TOKEN=s.nwombWQH3gGPDhJumRzxKqgI
vault kv get secret/applications/orchestrator/testSecretexport VAULT_TOKEN=s.nwombWQH3gGPDhJumRzxKqgI
vault kv get secret/applications/orchestrator/testSecret

Output of this command:

====== Metadata ======
Key              Value
---              -----
created_time     2020-10-12T06:24:41.7827631Z
deletion_time    n/a
destroyed        false
version          1
=========== Data ===========
Key                    Value
---                    -----
supersecretpassword    123456====== Metadata ======
Key              Value
---              -----
created_time     2020-10-12T06:24:41.7827631Z
deletion_time    n/a
destroyed        false
version          1
=========== Data ===========
Key                    Value
---                    -----
supersecretpassword    123456====== Metadata ======
Key              Value
---              -----
created_time     2020-10-12T06:24:41.7827631Z
deletion_time    n/a
destroyed        false
version          1
=========== Data ===========
Key                    Value
---                    -----
supersecretpassword    123456====== Metadata ======
Key              Value
---              -----
created_time     2020-10-12T06:24:41.7827631Z
deletion_time    n/a
destroyed        false
version          1
=========== Data ===========
Key                    Value
---                    -----
supersecretpassword    123456

Note:

You can also enable appRole Orchestrator by running the following command:

/ # vault auth enable approle 
/ # vault write auth/approle/role/orchestrator policies=orchestrator-policy 
/ # vault read auth/approle/role/orchestrator/role-id 
/ # vault write -f auth/approle/role/orchestrator/secret-id/ # vault auth enable approle 
/ # vault write auth/approle/role/orchestrator policies=orchestrator-policy 
/ # vault read auth/approle/role/orchestrator/role-id 
/ # vault write -f auth/approle/role/orchestrator/secret-id

You will now have a role-id and secret-id for configuring in Orchestrator.

Configuring the Active Directory Secrets Engine

To configure the Active Directory secrets engine, take the following steps:

Enable the Active Directory secrets engine by running the following command:
```
vault secrets enable advault secrets enable ad
```

Configure the credentials that HashiCorp Vault uses to communicate with Active Directory to generate passwords:

vault write ad/config \
    binddn=$USERNAME \
    bindpass=$PASSWORD \
    url=ldaps://138.91.247.105 \
    userdn='dc=example,dc=com'vault write ad/config \
    binddn=$USERNAME \
    bindpass=$PASSWORD \
    url=ldaps://138.91.247.105 \
    userdn='dc=example,dc=com'

Configure a role that maps a name in HashiCorp Vault to an account in Active Directory. When applications request passwords, password rotation settings will be managed by this role.
```
vault write ad/roles/orchestrator service_account_name="[email protected]"vault write ad/roles/orchestrator service_account_name="[email protected]"
```

Grant orchestrator access to its credentials at ad/creds/orchestrator using an authentication method, such as AppRole.

cat <<EOF | vault policy write orchestrator-policy -
path "ad/creds/orchestrator" {
  capabilities = ["read"]
}
EOFcat <<EOF | vault policy write orchestrator-policy -
path "ad/creds/orchestrator" {
  capabilities = ["read"]
}
EOF

Using HashiCorp Vault (read-only)

When using HashiCorp Vault (read-only) plugin, the Vault admin is responsible for correctly provisioning the secrets that Orchestrator will use. The format in which these secrets must be provisioned differs between secret types (asset versus robot password) and between secret engines.

For instructions on how to provision the secrets, see the following: