Secret vault LDAP login

When OpsChain uses LDAP authentication and the OpsChain secret vault, users can sign in to the secret vault with the same username and password they use for OpsChain. OpsChain sets this up each time the OpsChain API starts, using its own LDAP settings, so it works on a new installation and on an existing one after it is upgraded.

After following this guide you should know how to:

• sign in to the secret vault with your LDAP credentials
• give an LDAP group access to secrets
• administer the secret vault as an OpsChain superuser
• adjust how the secret vault connects to your LDAP server or Active Directory

When LDAP login is available

LDAP login is set up only when both of these apply:

• OPSCHAIN_AUTH_STRATEGY is ldap.
• The vault_ldap_auth.enabled setting is not false.

It is set up on the OpsChain secret vault only. A registered external secret vault is never changed.

Sign in to the secret vault

In the secret vault UI, at the address you set in global.secretVaultExternalHostName, choose LDAP as the sign-in method and enter your OpsChain username and password.

From the command line, point the OpenBao CLI at the same address and sign in with the ldap method:

export BAO_ADDR="https://vault.my-company.com"
bao login -method=ldap username=jsmith

Signing in on its own gives you no access to secrets. The token you receive can do one thing: create further tokens for yourself, with bao token create, so you can hand a narrower, separately revocable token to a script. Access to secrets comes from an administrator granting it to your LDAP group, as described below.

Give an LDAP group access to secrets

Create a secret vault policy describing what the group may do, then map the group to it. OpsChain superusers do both in the GUI: create the policy under Manage security → Vault policies, then use Edit vault policies on the group's row of the Groups table. For example, a policy letting the bank-team group read and write the secrets under secrets/bank/ holds the rule:

path "secrets/bank/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

The same can be done through the API, with /api/admin/secret_vault_policies for the policies and /api/admin/secret_vault_ldap_groups (or /api/admin/secret_vault_ldap_users) for the mappings. These are only available when OpsChain uses the bundled secret vault with LDAP authentication. OpsChain only accepts policies whose rules stay within the secret vault's key/value stores. Writing a policy directly with bao policy write needs the secret vault root token.

Members of bank-team receive the policy the next time they sign in. To grant a policy to one person rather than a group, use Edit vault policies on their row of the Users table, or /api/admin/secret_vault_ldap_users, instead.

Groups are named by their cn

A group is mapped by its cn - the same group name OpsChain shows and uses in policy assignments.

OpsChain does not remove or rewrite the policies and mappings you create, apart from adding or removing its own opschain-vault-admin policy, described next. Deleting a policy removes it from every user and group it is mapped to, and signs those users out of the secret vault.

Administer the secret vault as a superuser

OpsChain superusers are the secret vault's administrators. Assigning the superuser policy to an LDAP user or group maps that user or group to the opschain-vault-admin policy in the secret vault, and removing the assignment removes it again. Any other policies an administrator mapped to the same user or group are kept.

A superuser signed in to the secret vault can:

• create, read, update, delete and list secrets in every key/value store in the secret vault
• read and list secret vault policies
• map LDAP users and groups to policies
• create tokens

A superuser cannot change the policies OpsChain itself maintains (those named opschain-*), the LDAP connection configuration, the secret vault's sign-in methods or storage mounts, or seal or re-initialise the secret vault. The secret vault root token keeps working for those tasks - see secret vault root token for how to retrieve it.

The superuser policy is applied to the secret vault when the OpsChain API starts, every hour, and shortly after a superuser assignment is changed. An assignment to all users, or to a local user, is not applied, as local users cannot sign in to the secret vault. Removing a superuser assignment signs the users it covered out of the secret vault.

Blocked users

Assigning the block user access policy to an LDAP user also blocks them from the secret vault. Their current tokens stop working, tokens they created stop working, and they cannot sign in again until the block is removed. A user can be blocked before they have ever signed in to the secret vault.

Removing a policy mapped to a user ends the secret vault login of every API key they own straight away, and removing their superuser assignment ends it shortly afterwards. Blocking a user, any other change to the policies mapped to them (including granting one), or a change to their LDAP password ends it when OpsChain next renews the key's login, which it does every two hours; a blocked user's keys stop working at once. An info:secret_vault:api_key:revoked event is recorded for each key. To restore a key's access, create a new key with the user's password.

When the policy is assigned to an LDAP group, each member of the group is blocked. New members are picked up by the hourly update. Removing the block restores access only for the users OpsChain blocked, so a user disabled directly in the secret vault stays disabled.

Configure the secret vault's LDAP connection

OpsChain builds the secret vault's LDAP configuration from its own LDAP settings, so a directory that works for OpsChain sign-in normally works for the secret vault without further configuration. The connection details, bind account, user and group search settings, and the certificate authorities in OpsChain's trust store are written each time the OpsChain API starts. They are written again shortly after any of the ldap, vault_ldap_auth or auth_strategy system configuration settings is saved, so a change to them needs no restart. A change to the trust store reaches the secret vault the next time the API starts. To apply it straight away, restart the API:

kubectl -n ${KUBERNETES_NAMESPACE} rollout restart deployment/opschain-api

note

Unlike OpsChain's own LDAPS connection, the secret vault verifies the directory's certificate chain. If your directory uses a private certificate authority, add it to OpsChain's trust store, or supply it in the certificate key of vault_ldap_auth.config.

The vault_ldap_auth settings adjust this configuration. Edit them in the Vault LDAP login section of the system configuration screen, or in the system configuration. OpsChain applies them to the secret vault shortly after they are saved. For example:

{
  "vault_ldap_auth": {
    "bind_dn": "CN=svc-vault-read,CN=Users,DC=myopschain,DC=io",
    "bind_password": "ReadOnlyPassword!",
    "config": "{\"upndomain\": \"myopschain.io\", \"use_token_groups\": true}"
  }
}

vault_ldap_auth.enabled

Default value: none (enabled)

Set to false to stop OpsChain managing the secret vault's LDAP sign-in. The existing configuration, policies and mappings are left as they are, and superuser and block assignments are no longer applied to the secret vault.

vault_ldap_auth.bind_dn

Default value: none - the ldap.admin setting is used.

The account the secret vault binds as to search the directory. The secret vault only ever searches, while OpsChain's own account also needs to create users, so a dedicated read-only account is recommended for your own directory.

vault_ldap_auth.bind_password

Default value: none - the ldap.password setting is used.

The password for vault_ldap_auth.bind_dn. It is stored encrypted.

vault_ldap_auth.config

Default value: none

A JSON object of OpenBao LDAP settings, written to the secret vault after the settings OpsChain derives. Use it for anything OpsChain does not set itself, or to replace a value it does. Settings you leave out of the object keep their current value in the secret vault.

Active Directory

These vault_ldap_auth.config keys cover the Active Directory arrangements OpsChain's LDAP settings do not describe:

If your directory	Add to vault_ldap_auth.config
signs users in as user@domain	"upndomain": "myopschain.io"
uses nested groups	"use_token_groups": true
holds more than 1000 entries in a search	"max_page_size": 1000
requires TLS 1.3	"tls_max_version": "tls13"

The secret vault does not follow LDAP referrals. If your users span several domains, point ldap.host and ldap.port at a Global Catalog (port 3268, or 3269 for LDAPS).

Use an existing LDAP sign-in method

If the secret vault already had an LDAP sign-in method at ldap/ before OpsChain was upgraded, OpsChain leaves its configuration alone and records an error:secret_vault:ldap_auth event saying so. Superuser and block assignments are still applied to it.

OpsChain manages an ldap/ sign-in method whose description is Managed by OpsChain. Handing an existing one over replaces part of its configuration, so follow hand over secret vault LDAP sign-in you set up yourself.

Troubleshooting

Problems setting up LDAP sign-in never stop OpsChain from starting. They are recorded as error:secret_vault:ldap_auth events, with the details in the event's message data key, at most once an hour for the same problem. They include:

• an existing ldap/ sign-in method that OpsChain did not create
• warnings the secret vault returned while accepting the LDAP configuration, such as a filter it considers unsafe
• the secret vault or the directory being unreachable while the configuration or the superuser and block assignments were being applied

If members of a group do not receive the policy you mapped to it, check that the group is mapped by its cn, and that ldap.groups_filter and ldap.group_attribute find the group when OpsChain looks up the user's membership. The secret vault finds no groups at all, without an error, when they do not.