threshold/website/content/docs/domain-model/credential-stores.mdx

---
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.
---

# 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 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 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