Secret vault credentials

OpsChain reads and writes secret vault values as the user making the request, using that user's own secret vault credentials. After following this guide you should know how to:

• register a secret vault credential for the vault you use
• give an API key secret vault access
• recreate an API key created before this access existed

Where your access comes from

Credentials belong to a secret vault: the bundled secret vault or one of the external secret vaults registered with OpsChain. One credential for a vault applies to every project, environment, asset and template that uses it, whatever mount path each one uses.

• LDAP users sign in to the bundled secret vault when they sign in to OpsChain, as described in secret vault LDAP login. They need no credential for the bundled secret vault.
• Everyone else - local users, and LDAP users of an external secret vault - registers a credential for each vault they use: a secret vault token issued to them by the administrator of that vault.

Changes, workflow steps and template action refreshes do not use your credential. They use a runner credential that a superuser has tagged on their project, environment or asset, or OpsChain's own default for the vault.

When OpsChain needs a credential you have not registered, the request fails with a message naming the vault, for example You do not have a credential registered for the Team vault secret vault.

An LDAP user's access to the bundled secret vault comes from their most recent sign-in with a password. If OpsChain cannot get it, the sign-in still succeeds, a warning is shown and an error:secret_vault:user_session event is recorded. A request then fails with You are not signed in to the bundled secret vault - sign out and sign in again. Vault policies granted or removed since you signed in also apply only once you sign in again, so a refused request on the bundled secret vault ends - if your secret vault access has changed, sign out and sign in again.

Register a credential

In the OpsChain GUI, open My account from the user menu and choose the Secret vault credentials tab. Add a credential, choosing the vault it is for and pasting your secret vault token. OpsChain checks the token with that vault before saving it.

The same can be done:

• with the OpsChain CLI, by passing the vault's code to the system credential commands with --vault. The CLI can also list the vaults you can choose from
• through the API, by sending the vault's code as external_vault_code to POST /api/user_system_credentials. Leave it out, or send bundled, for the bundled secret vault. GET /api/external_vaults lists the vaults and their codes

You can register one credential per vault, and registering a second one for the same vault fails. To replace a token, for example when it expires, update the credential instead:

• in the GUI, choose Replace token next to the credential on the Secret vault credentials tab
• with the OpsChain CLI, run opschain system-credentials update <id> with --token-file
• through the API, send the new token to PATCH /api/user_system_credentials/:id

If an administrator changes a vault's address, your credential keeps working, as long as the vault still accepts the token.

API keys

An API key gets secret vault access only when it is created with your password. Supply the password when creating the key:

• in the GUI, enter it in the Give this key secret vault access field of the Create API key dialog
• with the OpsChain CLI, create the key with --username and --password
• through the API, authenticate the /api/tokens/api_key_token request with basic auth or credentials in the request body, or send your password in the request body alongside an access token

An incorrect password is rejected and the key is not created. A key created without a password has no secret vault access.

A key created with your password uses the credentials you have registered, looked up afresh on every request, so registering, replacing or deleting a credential changes the key's access straight away. For an LDAP user, the password also gives the key its own login to the bundled secret vault. If you have no credential registered when the key is created, the key is still created and a warning tells you to register one. The key's login to the bundled secret vault ends if you are blocked, the policies mapped to you change (including losing your superuser assignment), or your LDAP password changes, and an info:secret_vault:api_key:revoked event is recorded. Create a new key with your password to restore its access.

Existing API keys

API keys created before this release have no access through your registered credentials. To give one secret vault access, create a new key with your password and revoke the old one. In the GUI's API key list, the key icon beside a key without this access opens the Create API key dialog for its replacement.