mirror of https://github.com/hashicorp/boundary
Add documentation for credentials to website (#1356)
Michael Gaffney
5 years ago
committed by
GitHub
parent
86c9a90554
commit
28f48df026
@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Domain Model - Credential Libraries
|
||||
description: |-
|
||||
The anatomy of a Boundary credential library
|
||||
---
|
||||
|
||||
# Credential Libraries
|
||||
|
||||
A credential library is a resource
|
||||
that provides [credentials][]
|
||||
of the same type and same access level
|
||||
from a single [credential store][].
|
||||
|
||||
## Attributes
|
||||
|
||||
A credential library has the following configurable attributes:
|
||||
|
||||
- `name` - (optional)
|
||||
If set, the `name` must be unique within the credential library's parent
|
||||
[credential store][].
|
||||
|
||||
- `description` - (optional)
|
||||
|
||||
### Vault Credential Library Attributes
|
||||
|
||||
A Vault credential library has the following additional attributes:
|
||||
|
||||
- `path` - (required)
|
||||
The path in Vault to request credentials from.
|
||||
|
||||
- `http_method` - (optional: defaults to `GET`)
|
||||
The HTTP method the library uses when requesting credentials from Vault.
|
||||
Can be either `GET` or `POST`.
|
||||
|
||||
- `http_request_body` - (optional)
|
||||
The body of the HTTP request the library sends to Vault when requesting credentials.
|
||||
Only valid if `http_method` is set to `POST`.
|
||||
|
||||
## Referenced By
|
||||
|
||||
- [Credential][]
|
||||
- [Credential Store][]
|
||||
- [Target][]
|
||||
|
||||
[credential store]: /docs/concepts/domain-model/credential-stores
|
||||
[credential stores]: /docs/concepts/domain-model/credential-stores
|
||||
[credential]: /docs/concepts/domain-model/credentials
|
||||
[credentials]: /docs/concepts/domain-model/credentials
|
||||
[project]: /docs/concepts/domain-model/scopes#projects
|
||||
[projects]: /docs/concepts/domain-model/scopes#projects
|
||||
[target]: /docs/concepts/domain-model/targets
|
||||
[targets]: /docs/concepts/domain-model/targets
|
||||
|
||||
## Service API Docs
|
||||
|
||||
The following services are relevant to this resource:
|
||||
|
||||
- [Credential Library Service](/api-docs/credential-library-service)
|
||||
@ -0,0 +1,166 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## 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
|
||||
@ -0,0 +1,27 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Domain Model - Credentials
|
||||
description: |-
|
||||
The anatomy of a Boundary credential
|
||||
---
|
||||
|
||||
# Credentials
|
||||
|
||||
A credential is a data structure containing one or more secrets
|
||||
that binds an identity to a set of permissions or capabilities
|
||||
on a [host][] for a [session][].
|
||||
|
||||
## Attributes
|
||||
|
||||
## Referenced By
|
||||
|
||||
- [Credential Store][]
|
||||
- [Credential Library][]
|
||||
- [Session][]
|
||||
|
||||
[credential library]: /docs/concepts/domain-model/credential-libraries
|
||||
[credential libraries]: /docs/concepts/domain-model/credential-libraries
|
||||
[credential store]: /docs/concepts/domain-model/credential-stores
|
||||
[credential stores]: /docs/concepts/domain-model/credential-stores
|
||||
[host]: /docs/concepts/domain-model/hosts
|
||||
[session]: /docs/concepts/domain-model/sessions
|
||||
@ -0,0 +1,37 @@
|
||||
# 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"]
|
||||
}
|
||||
Loading…
Reference in new issue