Dan Heath
3f4cd53d16
* docs: Update headings for new style rule * docs: Fix headings - Get started * docs: Fix headings - Install * docs: Fix headings - Concepts * docs: Fix typos * docs: Fix headings - Configuration * docs: Fix headings - Operations * docs: Fix headings - Troubleshoot * docs: Fix headings - Clients and Develop * docs: Fix headings - HCP and ENT * docs: Fix headings - Release notes * docs: Fix typos * docs: Fix capitalization in TOC
185 lines
6.8 KiB
Plaintext
185 lines
6.8 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Domain model - credential stores
|
|
description: |-
|
|
The anatomy of a Boundary credential store
|
|
---
|
|
|
|
# Credential stores
|
|
|
|
A credential store is a resource
|
|
that can retrieve, store, and potentially generate [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.
|
|
A credential store can also contain [credential libraries][].
|
|
|
|
## 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 [PKI workers] can handle Vault requests.
|
|
This allows the use of private Vault instances with Boundary. PKI workers
|
|
deployed in the same network as a private Vault instance can access and relay
|
|
Vault requests to Boundary controllers.
|
|
~> **Note:** A PKI 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/concepts/domain-model/credential-libraries
|
|
[credential libraries]: /boundary/docs/concepts/domain-model/credential-libraries
|
|
[credential]: /boundary/docs/concepts/domain-model/credentials
|
|
[credentials]: /boundary/docs/concepts/domain-model/credentials
|
|
[project]: /boundary/docs/concepts/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 it's [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 listed below. An explanation
|
|
for the use of each capability is given.
|
|
|
|
```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"]
|
|
}
|
|
```
|
|
|
|
The above [`boundary-controller` policy](https://boundaryproject.io/data/vault/boundary-controller-policy.hcl) is
|
|
available for download. Below is an example of writing this policy to Vault:
|
|
|
|
```shell-session
|
|
# Download the policy
|
|
$ curl https://boundaryproject.io/data/vault/boundary-controller-policy.hcl -O -s -L
|
|
|
|
# Write the policy to Vault
|
|
$ 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 type `username_password`.
|
|
|
|
[token_requirements]: /boundary/docs/concepts/domain-model/credential-stores#vault-token-requirements
|
|
[token_policy]: /boundary/docs/concepts/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
|
|
[PKI workers]: /boundary/docs/configuration/worker/pki-worker
|
|
[filter]: /boundary/docs/concepts/filtering/worker-tags
|