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

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

### Static Credential Store Attributes

A Static credential store has no additional attributes and only supports the optional attributes.

## Referenced By

- [Credential Library][]
- [Credential][]
- [Project][]

## Service API Docs

The following services are relevant to this resource:

- [Credential Store Service](/api-docs/credential-store-service)

[credential library]: /docs/concepts/domain-model/credential-libraries
[credential libraries]: /docs/concepts/domain-model/credential-libraries
[credential]: /docs/concepts/domain-model/credentials
[credentials]: /docs/concepts/domain-model/credentials
[project]: /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](/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
```

[token_requirements]: /docs/concepts/domain-model/credential-stores#vault-token-requirements
[token_policy]: /docs/concepts/domain-model/credential-stores#vault-boundary-controller-policy
[vault]: https://www.vaultproject.io
[namespace]: https://www.vaultproject.io/docs/enterprise/namespaces
[renewable]: https://www.vaultproject.io/api-docs/auth/token#renewable-1
[periodic]: https://www.vaultproject.io/api-docs/auth/token#token_period
[orphan]: https://www.vaultproject.io/api-docs/auth/token#orphan

### Static Credential Store

A Static credential store allows for a user-supplied credentials managed by Boundary. Credentials are encrypted and stored directly in Boundary. Currently, the static credential store can hold credentials of type `username_password`.