HashiCorp Boundary Security: Hardening Workers, KMS, Credentials and Recording

HashiCorp Boundary brokers identity-based sessions to servers, databases and Windows hosts, so the controllers, workers, KMS keys and credential stores behind it become part of your privileged access path. Boundary is designed so users reach targets without network-level access or standing credentials, and its own security model rests on mutual TLS, an allow-only permissions model, scopes and envelope encryption with external key management. Most of the settings that make that model work in practice are in the customer's hands: KMS configuration, worker registration, role grants, credential store tokens, event sinks and session recording storage. This guide walks through each of those for platform and security engineers running self-managed Boundary (Community or Enterprise) or HCP Boundary. Secrets storage itself is covered in the HashiCorp Vault Guide; this page covers Boundary.

This is an independent guide from NHI Mgmt Group, based on HashiCorp's public Boundary documentation as of November 2026. It is not sponsored or reviewed by HashiCorp. Product features change, so confirm settings against HashiCorp's current documentation.

Key takeaways

• Protect controller and worker hosts as tier zero, because HashiCorp's security model explicitly places host-level access to controllers and workers outside what Boundary itself can defend.
• Use external KMS for every key purpose in production, keep the recovery KMS block out of the controller configuration except when needed, and encrypt the configuration file with the config purpose.
• Grant through roles scoped to orgs and projects, using Boundary's allow-only grant strings, and avoid broad grants to u_anon or u_auth.
• Prefer credential injection, then brokering, with Vault issuing short-lived or dynamic credentials, so users never hold long-lived target passwords or keys.
• Turn on audit events and session recording deliberately: set audit_enabled, ship events to your SIEM, configure the bsr KMS key, and apply a storage policy for retention.

How identity and access work in HashiCorp Boundary

Boundary has three components. Controllers form the control plane: users authenticate to them, and they hold resources and permissions and talk to the database, KMS, Vault, identity providers and plugins. Workers form the data plane: they proxy sessions between clients and targets, can chain together in multi-hop sessions to reach deeper networks, and perform SSH protocol decryption for credential injection and session recording. The client (CLI, desktop client or Client Agent) runs on the user's device.

Resources live in a hierarchy of scopes: the global scope, orgs and projects. Users sign in through auth methods (such as password, OIDC or LDAP), belong to groups or managed groups, and receive permissions through roles. A user requests a session to a target; Boundary authorises it, selects a worker, optionally fetches credentials from a credential store and the session runs for a fixed time limit.

HashiCorp's security model names the mechanisms that make this secure: mTLS between clients, controllers and workers; RBAC with an allow-only model; scopes for partitioning; and envelope encryption of sensitive database values with external KMS. It also states clearly what is the customer's responsibility. The model does not cover a party with code execution or privileged access on controller or worker hosts, the security of end-user and administrator devices, or the security of external credential sources such as Vault. That makes host hardening, device security and Vault configuration part of any Boundary hardening plan.

Admin roles and privileged access

Boundary declares permissions as grant strings of the form ids=...;type=...;actions=...;output_fields=..., supplied as text or JSON, and maps them to principals with roles. Principals are users, groups and managed groups. Every role assigns grants within the scopes named by its grant scope IDs, and child scopes can inherit roles from parents. The model is allow-only and composable: a user's grants are the union of every matching role.

Two built-in principals need special care. A role that lists u_auth applies to any logged-in user, and one that lists u_anon applies to anonymous requests. Keep grants to these principals to the minimum needed for sign-in and discovery, and put real access in roles bound to groups or managed groups.

Practical controls for the privileged tier:

• Use an OIDC auth method with managed groups so administrator status follows your identity provider's groups and its MFA policy, rather than local passwords.
• Treat the recovery KMS as break-glass: HashiCorp describes it as able to authenticate almost any operation, with requests shown as user u_recovery. It recommends leaving the recovery kms block out of the controller configuration except when needed, using change control to authorise adding it, and removing it afterwards. See the Break-Glass Account Guide.
• Manage configuration as code: HashiCorp documents initialising Boundary without default resources and using Terraform, authenticated by the recovery KMS, to create the initial auth methods, so every resource has a reviewed source.
• Review grants regularly: list roles per scope and check for wildcard ids=* with broad actions=*.

For the wider pattern, see the JIT Access Guide and the Privileged Session Management Guide.

Integrations, API tokens and service accounts

KMS key purposes

Boundary uses KMS stanzas in controller and worker configuration, each with a purpose. Supported external KMS types include AWS KMS, Azure Key Vault, GCP Cloud KMS, OCI KMS, AlibabaCloud KMS, IBM Key Protect and Vault Transit. HashiCorp notes that the aead KMS type is mostly for development or testing, because the key is visible to anyone who can read the configuration file.

Within each scope, Boundary creates DEKs for audit (secret values in the event log), database, oidc, oplog, tokens and sessions. boundary scopes rotate-keys creates new active versions (with -rewrap to rewrap DEKs immediately), and destroy-key-version re-encrypts data before destroying old key material; the latest version cannot be destroyed until a rotation creates a new one. For the general pattern, see the Envelope Encryption and KMS Integration Patterns Guide.

Worker registration

Workers authenticate with one of three registration mechanisms:

• Controller-led: an operator creates a one-time activation token with boundary workers create controller-led and supplies it through controller_generated_activation_token, which can reference env:// or file:// rather than a literal value.
• Worker-led: the worker writes an authorisation request token to its auth_storage_path, and an operator submits it with boundary workers create worker-led.
• KMS-led: the worker and controller share a worker-auth KMS key and re-authenticate against it on each connection.

Whichever you choose, restrict who can run worker create actions, protect auth_storage_path with file permissions and the worker-auth-storage key, and use worker tags and filters so sessions to sensitive networks only route through workers placed for that purpose. Watch worker health through Last Seen (UI) or Last Status Time (CLI) and the worker health endpoint.

Credential stores and Vault

Boundary supports two credential store types: a built-in static store (username and password, username, password and domain, SSH private key, SSH certificate and JSON credentials) and a Vault store. HashiCorp describes three user workflows, and is explicit about their order of preference:

With Vault, Boundary credential libraries can use the KV engine (static secrets), the LDAP engine (static or dynamic directory credentials) and the SSH engine (certificates, generated for every connection, through /issue or /sign). Dynamic credentials can be valid only for the lifetime of the session. Hardening points for the Vault link:

• Scope the Vault token: the token Boundary uses should hold a Vault policy that reads only the paths its credential libraries reference. Audit it with How to audit HashiCorp Vault tokens, policies and auth methods.
• Verify TLS to Vault: set the CA Certificate, and the Client Certificate for mutual TLS, in the Vault credential store; use Vault namespaces (Vault Enterprise) to separate tenants.
• Prefer dynamic secrets: SSH certificates and dynamic LDAP or database credentials remove standing passwords. See the Dynamic Secrets and Ephemeral Credentials Guide.
• Reach private Vault through a worker: workers can proxy controller traffic to a private Vault, so Vault does not need to be reachable from wider networks.

Availability: HashiCorp documents credential injection and multi-hop sessions for HCP Boundary and Boundary Enterprise, and session recording and storage policies for HCP Boundary Plus and Boundary Enterprise. KMS purposes such as root and recovery are configured on self-managed Enterprise or Community deployments.

Logging and detection

Boundary emits events (error, observation, system, audit and telemetry types) in cloudevents or hclog format, encoded as text or JSON. The events stanza turns types on with audit_enabled, observations_enabled, sysevents_enabled and telemetry_enabled, and sends them to file or stderr sinks with allow_filters and deny_filters. If no sink is configured, events go to a default stderr sink. HashiCorp's guidance for file sinks is to create the log directory in advance, owned by the Boundary service user, for example with mode 750. Secret values in audit events are encrypted with the scope's audit DEK.

• Collect: enable audit events on every controller and worker, write them to a file sink in JSON, and forward that file with your log agent to the SIEM. See the SIEM Log Source Onboarding Checklist.
• Alert on: role and grant changes, new auth methods, worker registrations, any request by u_recovery, credential store and library changes, storage policy changes, and sessions to sensitive targets outside expected hours.
• Record: session recording stores sessions in BSR format. Workers write to local storage during the session and upload to an S3, MinIO or S3-compatible storage bucket when it ends; the bsr KMS key encrypts recordings and checks their integrity. Set recording_storage_minimum_available_capacity so workers with low disk are not chosen for recording.
• Retain: storage policies set retain_for_days (-1 for indefinite) and delete_after_days, and can be set at global or org scope; set the _overridable flags to false where a regulatory minimum must not be lowered by an org.
• Protect recordings at the bucket: because recordings live outside Boundary and can be modified or deleted there, NHI Mgmt Group recommends bucket access policies, versioning or object lock in the storage provider, and keep bucket credentials narrow. HashiCorp also documents how to validate recorded sessions and the external data store.

Metrics

• Share of targets using credential injection or dynamic credentials rather than static brokered or user-held credentials.
• Number of principals with global-scope grants.
• Number of controller start-ups with the recovery block present, against approved recovery events.
• Share of sensitive targets with session recording on and a storage policy attached (target 100 per cent).
• Age of the active scope keys against your rotation target.

Hardening baseline

1. Harden hosts first: dedicated controller and worker hosts, restricted shell access, protected data directories and binaries, and patching. Apply HashiCorp security updates promptly.
2. Move keys to external KMS: replace aead keys with a cloud KMS or Vault Transit for root, worker-auth and bsr; encrypt remaining secrets in config with the config purpose. Test in a non-production cluster; roll back by restoring the previous stanza alongside previous-root during migration.
3. Remove the recovery block from running configuration and document the procedure to add it under change control.
4. Restructure roles: move users to OIDC with managed groups, build org and project roles, trim u_anon and u_auth grants, and test each change with a pilot group before removing old roles.
5. Move credentials into stores: static store first, then Vault with dynamic engines; switch SSH and RDP targets to injection project by project, keeping brokering as the rollback.
6. Enable events and recording: turn on audit events, add sinks, configure storage buckets, attach storage policies and enable recording on sensitive targets.
7. Review: quarterly role and credential library reviews, regular key rotation with rotate-keys, and recording validation tests.

Decision guidance

• HCP Boundary versus self-managed: HCP Boundary runs the controllers for you, which removes controller host hardening and some KMS configuration from your scope; self-managed deployments give full control of KMS purposes and the recovery mechanism, with the matching responsibility.
• Brokering versus injection: use injection wherever the target type allows (SSH, RDP); use brokering for TCP targets, ideally with dynamic Vault credentials that expire with the session.
• Registration method: controller-led suits automated deployments with a secure token channel; KMS-led suits environments that already have a KMS trust domain per network.

Framework mapping

Common misconfigurations

• aead keys carried into production: development-style keys sit in plain configuration. Fix: external KMS for each purpose and boundary config encrypt.
• Recovery block left in place: the controller always accepts recovery-authenticated requests. Fix: remove it and add it only under change control.
• Broad grants to u_auth: every signed-in user receives wide access. Fix: bind access roles to groups and managed groups.
• Static passwords brokered for SSH: users see long-lived credentials. Fix: inject Vault SSH certificates or dynamic credentials.
• Over-scoped Vault token: the credential store token can read far more than its libraries need. Fix: a dedicated Vault policy limited to those paths.
• Recordings without retention or bucket controls: Fix: attach storage policies and apply access controls and versioning on the storage bucket.

Practitioner checklist

• Harden and restrict access to controller and worker hosts, data directories and binaries.
• Configure external KMS for root, worker-auth, worker-auth-storage and bsr; encrypt config with the config purpose.
• Keep the recovery KMS block out of running configuration and alert on any u_recovery activity.
• Build roles per org and project, bind them to OIDC managed groups and trim grants to u_anon and u_auth.
• Use credential injection for SSH and RDP targets and dynamic Vault credentials for brokered targets.
• Limit the Vault token's policy to the paths Boundary uses and verify Vault TLS with a CA certificate.
• Enable audit_enabled and forward JSON event files to the SIEM.
• Enable session recording on sensitive targets with storage policies and protected storage buckets.
• Rotate scope keys on a schedule with boundary scopes rotate-keys.
• Apply HashiCorp security updates promptly and review roles and credential libraries quarterly.

Standards and references

• HashiCorp: Boundary security model
• HashiCorp: Data encryption in Boundary
• HashiCorp: Permissions in Boundary
• HashiCorp: Credentials in Boundary
• HashiCorp: Boundary Vault integration
• HashiCorp: Register workers
• HashiCorp: Session recording
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: HashiCorp Vault Guide · Privileged Session Management Guide · JIT Access Guide · Dynamic Secrets and Ephemeral Credentials Guide · Privileged Access Management Guide