diff --git a/website/content/docs/integrations/vault/index.mdx b/website/content/docs/integrations/vault/index.mdx index 3030c302b0..16580838f4 100644 --- a/website/content/docs/integrations/vault/index.mdx +++ b/website/content/docs/integrations/vault/index.mdx @@ -7,75 +7,101 @@ description: |- # Vault integration -The integration between Boundary and Vault aims to improve two main areas of concern for organizations: +The integration between Boundary and Vault improves two main areas of concern for organizations: -- Security posture in relation to remote access +- Security posture for remote access - Workflow efficiency -Boundary and Vault achieve these two goals by removing the requirement for the end-user to have to know about what the credentials are or have anything to do with using them to gain access to a resource. +Integrating Boundary and Vault achieves these goals by enabling end-users to access targets without needing to manually distribute credentials. -From a security perspective, we can use dynamic, ephemeral credentials that are only valid for the lifetime of the session, unless a specific time to live (TTL) has been attached to the Vault token that would result in a session having a finite amount of time. +From a security perspective, credentials can be configured to be dynamic and ephemeral, and only valid for the lifetime of the session. Or a specific time to live (TTL) can be attached to the Vault token, resulting in a session having a finite amount of time. -The security benefits extend past an organization's internal team and cater to third-parties or contractors that may need to access resources. It is preferable to not expose credentials to temporary staff, while still ensuring that access to resources is secure and granted in a timely manner. +These security benefits can be extended to third-parties or contractors that may need to access resources. It is preferable to not expose credentials to temporary staff, while still ensuring that access to resources is secure and granted in a timely manner. -Ensuring access is granted in a timely manner then leads to that improvement in workflow efficiency. This is the result of end-users not having to be concerned with credentials, therefore removing a large bottleneck, in relation to gaining credentials through access requests and the time associated with such a task. +Timely access to resources creates improvements in workflow efficiency by removing manual approvals for access to highly-scoped, preconfigured access requests. Additional end-workflow improvements are added by removing credential management from the end-user. ## Credential management -Vault can work with Boundary to be a credential [store](https://developer.hashicorp.com/boundary/docs/concepts/domain-model/credential-stores) and [library](https://developer.hashicorp.com/boundary/docs/concepts/domain-model/credential-libraries), which allows for credentials to be stored in Vault and used by Boundary. There are two configuration options: +Within Boundary, Vault can be configured as a [credential store](/boundary/docs/concepts/domain-model/credential-stores) and [credential library](/boundary/docs/concepts/domain-model/credential-libraries). + +There are two configuration options: - Generic secrets - SSH certificates -Generic secrets reference a Vault key-value path where static secrets are stored, for example, username and password. You can use generic secrets to broker credentials to the end-user when they connect to a target. +Generic secrets reference a Vault key-value path where static secrets are stored, such as username/password or SSH keypairs. Generic secrets can be brokered to the end-user when they connect to a target. + +SSH certificates have the advantage of using Vault as the certificate authority (CA) and being able to use the [HashiCorp Vault SSH Secrets Engine](/vault/docs/secrets/ssh). -SSH certificates have the advantage of using Vault as the certificate authority (CA) and being able to use the [HashiCorp Vault SSH Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/ssh). You can inject SSH certificates directly into the Boundary session. +Both generic secrets and SSH certificates can be injected directly into Boundary sessions using an HCP Boundary or Boundary Enterprise deployment. + + -It is worth detailing that you must bring your own Vault deployment to Boundary. + You must bring your own Vault deployment to Boundary. + + ### Brokered credentials -Brokered credentials were added in Boundary 0.4. They let you use Boundary as a credential broker for infrastructure targets, by binding credentials with user sessions, and surfacing those credentials during session initialization, with the help of Vault. +Brokered credentials let you use Boundary as a credential broker for infrastructure targets by binding credentials with user sessions. Credentials are surfaced during session initialization, after being brokered from Vault. -An example workflow and use case for this feature is database access. Certain teams within an organization, such as finance, need to access sensitive data that resides in a database. Irrespective of the frequency that the database needs to be accessed, having long-lived credentials that could be purposely or accidentally leaked, can pose a huge risk to a company. +Consider database access as an example. Within an organization, the finance team might need to access sensitive data that within in a database. Regardless of how often the database needs to be accessed, long-lived credentials create a security liability. These credentials could be purposely or accidentally be leaked, creating risk for a company. -Integrating Boundary and Vault mitigates this security risk. You can enable the Vault database secrets engine, with the relevant database plugin configured, to then be able to issue dynamic and short-lived database credentials to end-users. Organizations can set a limit on the amount of times these credentials are valid and once they have timed-out, access is automatically revoked. +Integrating Boundary and Vault helps mitigate this security risk. Vault secrets engines can be configured to issue static or dynamic short-lived database credentials to end users. Organizations can also define how long credentials are valid for, and once they have timed-out access can automatically be revoked. ![Brokered Credentials](/img/brokered-creds-ui.png) -When you connect to the database using Boundary, Boundary displays the newly generated credentials to the end user so that they can connect to the target. +When you connect to the database using Boundary, Boundary displays the brokered credentials to the end user so that they can connect to the target. Once the session is closed or terminated, Boundary requires the user to request a new session to the target. ### Injected credentials HCP/ENT -Currently credential injection with Vault can be configured using static or dynamic credentials: +Credentials can be injected directly into sessions using HCP Boundary or Boundary Enterprise. This removes the need for a end users to manually use a brokered credential to access the target after Boundary has established a session, and prevents users from ever accessing the credential. Injected credentials are never passed back to the end user. + +Credential injection with Vault can be configured using static or dynamic credentials: -1. [KV secrets engine](/vault/docs/secrets/kv/kv-v2) (static credentials) -1. [SSH secrects engine](/vault/docs/secrets/ssh) (dynamic credentials) +- [KV secrets engine](/vault/docs/secrets/kv/kv-v2) (static credentials) +- [SSH secrects engine](/vault/docs/secrets/ssh) (dynamic credentials) The KV secrets engine can be used for static username/password secrets, or static keypair secrets. -When using the SSH secrets engine, Vault is configured to act as the certificate authority (CA), to ensure that the users’ authenticity is determined by a certificate signed by a trusted CA. When key pairs are generated dynamically, they are signed by Vault to then be used to access the resources. There are two options for the key pair generation, depending on the type of Vault endpoint that you use within the Boundary credential library for SSH certification. +When using the SSH secrets engine, Vault can be configured to act as the certificate authority (CA), or an external CA can be configured. When using Vault as the CA, it ensures that a user's certificate is signed before being brokered to Boundary. When key pairs are generated dynamically, they are signed by Vault to then be used to access the resources. -`/issue` - Vault generates and signs the key pair for you. +There are two options for the key pair generation, depending on the type of Vault endpoint that you use within the Boundary credential library for SSH certification. -`/sign` - The Boundary controllers generate the key pair and then send it to Vault to sign. +- `/issue`: Vault generates and signs the key pair for you. -When you connect to a target that uses Vault for dynamic SSH certificates, a new certificate is generated for every target connection. As long as the target trusts the CA, then access is granted without you having any visibility into the credentials involved. +- `/sign`: The Boundary controllers generate the key pair and then send it to Vault to sign. + +When you connect to a target that uses Vault for dynamic SSH certificates, a new certificate is generated for every target connection. As long as the target trusts the CA, access is granted without the end user having visibility into the credentials being injected. ## Secrets management -Within Boundary, you can configure one or more credential stores. This could be a dedicated credential store per Boundary project, and/or multiple credential stores within the same Boundary project. You can either configure the credential store as static, which is Boundary's native store, or by integrating it with HashiCorp Vault. The purpose of the credential store that is integrated with Vault is to fetch secrets from Vault on behalf of Boundary users. +Within Boundary you can configure one or more credential stores. There are two types of credential stores: + +- [Static credential store](/boundary/docs/concepts/domain-model/credential-stores#static-credential-store) +- [Vault credential store](/boundary/docs/concepts/domain-model/credential-stores#vault-policies) + +A static credential store is built into Boundary if you wish to manage secrets without integrating Vault. The Vault credential store can fetch secrets from Vault on behalf of Boundary users. -Organizations may have valid reasons for multiple credential stores within Boundary. As you can only create credential stores at the project level, there may be different projects within an org scope that have different requirements from their credential stores. For example, within an org scope you may have two project scopes: Database and Compute. These two projects need to be isolated and therefore would have a dedicated credential store per project. +Organizations may have valid reasons for using multiple credential stores within Boundary. Credential stores can only be created at the [project](/boundary/docs/concepts/domain-model/scopes#projects) scope, and each project can contain multiple credential stores. Projects within an org scope may have different requirements from their credential stores. For example, within an org scope you may have two projects: Database and Compute. These two projects may need to be isolated, and can have a dedicated credential store per project. -When it is integrated with Vault, Boundary has to be assigned a periodic, renewable, orphan token from Vault. Each credential store that is created within Boundary that leverages Vault equates to one Vault token being created. The number of Boundary targets that source credentials from the stores, the number of users connecting to the targets, the number of sessions that get created, or how many credential libraries the credential store contains, all have no impact on the client count in Vault. +When integrated with Vault, Boundary has to be assigned a periodic, renewable, [orphan token](/docs/concepts/domain-model/credential-stores#vault-token-requirements) from Vault. Each credential needs a separate Vault token. + +The following have no impact on Vault's [client count](/vault/docs/concepts/client-count/counting): + +- The number of Boundary targets that source credentials from the stores +- The number of users connecting to the targets +- The number of sessions that get created +- The number of credential libraries the credential store contains -If there is more than one credential library that is part of the same credential store, there is the potential for that single Vault token to have access to all of the Vault paths defined in the credential libraries. HashiCorp recommends that you operate the model of least privilege. +Credential stores may contain multiple credential libraries. This means a single Vault token can provide access to all the Vault paths defined in the credential libraries. HashiCorp recommends that you operate using the model of least privilege when setting up credential stores. ## Vault as an identity provider -Boundary supports OIDC, LDAP, and username/password as authentication methods. Boundary can leverage Vault as an OIDC bridge provider. This allows Vault to delegate authentication to an external OIDC provider, such as Google, Okta, Entra as some examples, which then map the authenticated user's claims to Vault policies and identities. This allows users to authenticate to Boundary with any of Vault's supported authentication methods, even ones that Boundary does not natively support. When Boundary leverages Vault as an OIDC provider, each user leveraging the authentication method then counts as a Vault client. \ No newline at end of file +Boundary supports OIDC, LDAP, and username/password as [authentication methods](/boundary/docs/concepts/iam#access-management). Boundary can leverage Vault as an [OIDC bridge provider](/vault/tutorials/auth-methods/oidc-identity-provider). This allows Vault to delegate authentication to an external OIDC provider, such as Google Cloud, Okta, or Microsoft Entra ID. + +These providers then map the authenticated user's claims to Vault policies and identities. This allows users to authenticate to Boundary with any of Vault's supported authentication methods, even ones that Boundary does not natively support. When Boundary leverages Vault as an OIDC provider, each user leveraging the authentication method then counts as a Vault client. \ No newline at end of file