mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
222 lines
7.9 KiB
222 lines
7.9 KiB
---
|
|
layout: docs
|
|
page_title: Credential store resource
|
|
description: >-
|
|
Learn about using the credential store resource to store and retrieve credentials. Understand the Vault and static credential store attributes you can configure.
|
|
---
|
|
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
|
|
# Credential stores
|
|
|
|
A credential store is a resource
|
|
that can retrieve [credentials][]
|
|
of differing types and differing access levels.
|
|
It belongs to a [project][] and supports the
|
|
[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
|
|
by providing mechanisms to limit the [credentials][] it can access
|
|
to the minimum necessary for the project it is in.
|
|
|
|
Credential stores contain either credential libraries or credentials, depending on the type:
|
|
|
|
- Vault credential stores contain [credential libraries][].
|
|
Targets use credential libraries to issue credentials for sessions.
|
|
|
|
- Static credential stores contain credentials, not credential libraries.
|
|
When you use static credential stores, the credentials are stored directly in Boundary.
|
|
|
|
## Attributes
|
|
|
|
A credential store has the following configurable attributes:
|
|
|
|
- `name` - (optional)
|
|
If set, the `name` must be unique within the credential store's project.
|
|
|
|
- `description` - (optional)
|
|
|
|
### Vault credential store attributes
|
|
|
|
A Vault credential store has the following additional attributes:
|
|
|
|
- `address` - (required)
|
|
The address of the Vault server.
|
|
This should be a complete URL such as `https://127.0.0.1:8200`.
|
|
|
|
- `token` - (required)
|
|
A token used for accessing Vault.
|
|
This token must meet the [Vault token requirements][token_requirements] described below.
|
|
Each Vault credential store must be configured with a unique Vault token.
|
|
|
|
- `ca_cert` - (optional)
|
|
A PEM-encoded CA certificate to verify the Vault server's TLS certificate.
|
|
|
|
- `tls_server_name` - (optional)
|
|
Name to use as the SNI host when connecting to Vault via TLS.
|
|
|
|
- `tls_skip_verify` - (optional)
|
|
Disable verification of TLS certificates.
|
|
Using this option is highly discouraged as it decreases the security of data
|
|
transmissions to and from the Vault server.
|
|
|
|
- `client_certificate` - (optional)
|
|
A PEM-encoded client certificate to use for TLS authentication to the Vault server.
|
|
|
|
- `client_certificate_key` - (optional)
|
|
A PEM-encoded private key matching the client certificate from `client_certificate`.
|
|
|
|
- `namespace` - (optional)
|
|
A Vault [namespace][]. Requires Vault Enterprise.
|
|
|
|
- `worker_filter` <sup>HCP/ENT</sup> - (optional)
|
|
A [filter] used to control which workers can handle Vault requests.
|
|
This allows the use of private Vault instances with Boundary. Workers
|
|
deployed in the same network as a private Vault instance can access and relay
|
|
Vault requests to Boundary controllers.
|
|
A worker that matches the worker filter must exist before defining the Vault credential store, as it
|
|
will perform the Vault calls needed to set up the credential store with Boundary.
|
|
|
|
### Static credential store attributes
|
|
|
|
A static credential store has no type-specific attributes.
|
|
|
|
## Referenced by
|
|
|
|
- [Credential library][]
|
|
- [Credential][]
|
|
- [Project][]
|
|
|
|
## Service API docs
|
|
|
|
The following services are relevant to this resource:
|
|
|
|
- [Credential store service](/boundary/api-docs/credential-store-service)
|
|
|
|
[credential library]: /boundary/docs/domain-model/credential-libraries
|
|
[credential libraries]: /boundary/docs/domain-model/credential-libraries
|
|
[credential]: /boundary/docs/domain-model/credentials
|
|
[credentials]: /boundary/docs/domain-model/credentials
|
|
[project]: /boundary/docs/domain-model/scopes#projects
|
|
|
|
## Vault token requirements
|
|
|
|
Each Vault credential store must be configured with a unique Vault token.
|
|
The Vault tokens for all credential stores
|
|
must be [periodic][], [renewable][], and an [orphan][].
|
|
All tokens must also have the capabilities of the
|
|
[Vault Boundary controller policy][token_policy] described below.
|
|
|
|
### Vault policies
|
|
|
|
The credential store's token must have the capabilities to issue credentials for
|
|
each of its credential libraries plus the capabilities of the
|
|
[Vault Boundary controller policy][token_policy] described below.
|
|
|
|
We recommend creating a unique Vault policy for each Vault credential store that
|
|
grants the minimum set of permissions needed by the credential store's
|
|
libraries. We also recommend the [Vault Boundary controller
|
|
policy][token_policy] be kept distinct from any other Vault policies. This
|
|
allows each credential store to have a token that is configured with two
|
|
polices: one shared by all credential stores and one unique to that credential
|
|
store. This also allows a credential store to be created with the minimum
|
|
permissions necessary at any point in time. The policy unique to a credential
|
|
store can then be updated as needed when credential libraries are added and
|
|
removed from the credential store.
|
|
|
|
#### Vault Boundary controller policy
|
|
|
|
The token Boundary receives must have the capabilities in the policy below. An explanation for each capability is documented above the written policy.
|
|
|
|
```hcl
|
|
# Allow Boundary to read and verify the properties of the token. This is
|
|
# provided by the "default" policy.
|
|
path "auth/token/lookup-self" {
|
|
capabilities = ["read"]
|
|
}
|
|
|
|
# Allow Boundary to renew the token. This is provided by the "default"
|
|
# policy.
|
|
path "auth/token/renew-self" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
# Allow Boundary to revoke the token when the credential store is updated
|
|
# to use a new token or the credential store is deleted. This is provided
|
|
# by the "default" policy.
|
|
path "auth/token/revoke-self" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
# Allow Boundary to renew the credentials in active sessions. This is
|
|
# provided by the "default" policy.
|
|
path "sys/leases/renew" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
# Allow Boundary to revoke the credentials issued for a session when the
|
|
# session is terminated.
|
|
path "sys/leases/revoke" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
# Allow Boundary to read and verify the token's capabilities for each Vault
|
|
# path used by the credential store. This is provided by the "default"
|
|
# policy.
|
|
path "sys/capabilities-self" {
|
|
capabilities = ["update"]
|
|
}
|
|
```
|
|
|
|
Follow the steps below to write this policy to Vault.
|
|
|
|
Create the policy:
|
|
|
|
```shell-session
|
|
$ cat > boundary-controller-policy.hcl <<EOF
|
|
path "auth/token/lookup-self" {
|
|
capabilities = ["read"]
|
|
}
|
|
|
|
path "auth/token/renew-self" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
path "auth/token/revoke-self" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
path "sys/leases/renew" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
path "sys/leases/revoke" {
|
|
capabilities = ["update"]
|
|
}
|
|
|
|
path "sys/capabilities-self" {
|
|
capabilities = ["update"]
|
|
}
|
|
EOF
|
|
```
|
|
|
|
Write the policy to Vault:
|
|
|
|
```shell-session
|
|
$ vault policy write boundary-controller boundary-controller-policy.hcl
|
|
```
|
|
|
|
## Static credential store
|
|
|
|
A static credential store allows user-supplied credentials to be managed by Boundary. Credentials are encrypted and stored directly in Boundary. Currently, the static credential store can hold credentials of types `username_password`, `username_password_domain`, `ssh_private_key`, and `json`.
|
|
|
|
[token_requirements]: /boundary/docs/domain-model/credential-stores#vault-token-requirements
|
|
[token_policy]: /boundary/docs/domain-model/credential-stores#vault-boundary-controller-policy
|
|
[vault]: https://www.vaultproject.io/
|
|
[namespace]: /vault/docs/enterprise/namespaces
|
|
[renewable]: /vault/api-docs/auth/token#renewable-1
|
|
[periodic]: /vault/api-docs/auth/token#token_period
|
|
[orphan]: /vault/api-docs/auth/token#orphan
|
|
[filter]: /boundary/docs/workers/worker-tags
|