Add documentation for credentials to website (#1356)

2021-06-25 15:31:10 -04:00
1 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
@@ -31,6 +31,23 @@ All resources have an ID which is unique within Boundary.
  issued from a configured [authentication method][]
  which can be used to establish the identity of a [user][].

+- **[Credential][]** :
+  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][].
+
+- **[Credential Library][]** :
+  A credential library is a resource
+  that provides [credentials][]
+  of the same type and same access level
+  from a single [credential store][].
+
+- **[Credential Store][]** :
+  A credential store is a resource
+  that can retrieve, store, and potentially generate [credentials][]
+  of differing types and differing access levels.
+  It may also contain [credential libraries][].
+
 - **[Authentication Method][]** :
  An authentication method is a resource
  that provides a mechanism
@@ -68,8 +85,10 @@ All resources have an ID which is unique within Boundary.
  which are granted to any principal assigned to the role.

 - **[Session][]** :
-  A session is a set of related connections
-  between a [user][] and a [host][].
+  A session is a set of related connections between a [user][] and a [host][].
+  A session may include a set of [credentials][]
+  which define the permissions granted to the [user][] on the [host][] for the duration
+  of the session.

 - **[Scope][]** :
  A scope is a [permission][] boundary modeled as a container.
@@ -77,6 +96,7 @@ All resources have an ID which is unique within Boundary.
 - **[Target][]** :
  A target is a resource
  that represents a networked service
+  with an associated set of permissions
  a [user][] can connect to
  and interact with
  through Boundary
@@ -101,6 +121,12 @@ That page can help you understand the structure of resources within Boundary.
 [accounts]: /docs/concepts/domain-model/accounts
 [authentication method]: /docs/concepts/domain-model/auth-methods
 [authentication methods]: /docs/concepts/domain-model/auth-methods
+[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
+[credential]: /docs/concepts/domain-model/credentials
+[credentials]: /docs/concepts/domain-model/credentials
 [group]: /docs/concepts/domain-model/groups
 [groups]: /docs/concepts/domain-model/groups
 [host catalog]: /docs/concepts/domain-model/host-catalogs
@@ -114,6 +140,7 @@ That page can help you understand the structure of resources within Boundary.
 [roles]: /docs/concepts/domain-model/roles
 [scope]: /docs/concepts/domain-model/scopes
 [scopes]: /docs/concepts/domain-model/scopes
+[project]: /docs/concepts/domain-model/scopes#projects
 [session]: /docs/concepts/domain-model/sessions
 [sessions]: /docs/concepts/domain-model/sessions
 [target]: /docs/concepts/domain-model/targets
@@ -36,7 +36,7 @@ An org can directly contain:
 A project is a scope directly contained by an org scope.
 There can be multiple projects within an org.
 A project can directly contain:
-[roles][], [targets][], and [host catalogs][]
+[roles][], [targets][], [host catalogs][], and [credential stores][].

 ## Attributes

@@ -50,6 +50,7 @@ A scope has the following configurable attributes:
 ## Referenced By

 - [Auth Method][]
+- [Credential Store][]
 - [Group][]
 - [Host Catalog][]
 - [Role][]
@@ -58,6 +59,8 @@ A scope has the following configurable attributes:

 [auth method]: /docs/concepts/domain-model/auth-methods
 [auth methods]: /docs/concepts/domain-model/auth-methods
+[credential store]: /docs/concepts/domain-model/credential-stores
+[credential stores]: /docs/concepts/domain-model/credential-stores
 [global]: /docs/concepts/domain-model/scopes#global
 [group]: /docs/concepts/domain-model/groups
 [groups]: /docs/concepts/domain-model/groups
@@ -10,12 +10,19 @@ description: |-
 A session is
 a set of related connections
 between a [user][] and a [host][].
+A session may include a set of [credentials][]
+which define the permissions granted to the [user][] on the [host][] for the duration
+of the session.
+
 A user initiates a session
 by requesting access to a [target][].
 If a user has the proper [permissions][],
 a session is created
 and the [expiration time][] and [connection limit][]
 are set based on the [target's attributes][].
+If the [target][] is associated with [credential libraries][],
+[credentials][] are retrieved and returned from each
+[credential library][].
 A snapshot of the data
 relevant to authorizing the session
 is also captured and stored in the Boundary data warehouse
@@ -37,6 +44,7 @@ A session is forcefully terminated when one of the following occurs:
 - Any resource associated with the session is deleted
  or removed from the [target][].
  This includes: the [host][], the [host set][], the [host catalog][],
+  a [credential][], a [credential library][], a [credential store][],
  the [target][] itself, the [project][], the [organization][],
  the [user][], the user's [account][], or the account's [authentication method][].

@@ -46,12 +54,16 @@ when the user closes all connections
 and no additional connections are allowed
 because of a connection limit.

+Any [credentials][] associated with the session are revoked when the session is
+terminated.
+
 Permissions are only evaluated at session establishment.
 Changes to a user's permissions do not effect existing sessions.

 ## Referenced By

 - [Project][]
+- [Credential][]

 [expiration time]: /docs/concepts/domain-model/targets#session_max_seconds
 [connection limit]: /docs/concepts/domain-model/targets#session_connection_limit
@@ -60,6 +72,12 @@ Changes to a user's permissions do not effect existing sessions.
 [accounts]: /docs/concepts/domain-model/accounts
 [authentication method]: /docs/concepts/domain-model/auth-methods
 [authentication methods]: /docs/concepts/domain-model/auth-methods
+[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
+[credential]: /docs/concepts/domain-model/credentials
+[credentials]: /docs/concepts/domain-model/credentials
 [host catalog]: /docs/concepts/domain-model/host-catalogs
 [host catalogs]: /docs/concepts/domain-model/host-catalogs
 [host set]: /docs/concepts/domain-model/host-sets
@@ -9,6 +9,7 @@ description: |-

 A target is a resource
 that represents a networked service
+with an associated set of permissions
 a [user][] can connect to
 and interact with
 through Boundary
@@ -16,6 +17,8 @@ by way of a session.
 A target can only be defined within a [project][].
 A target can contain references to [host sets][] from [host catalogs][]
 which belong to the same project as the target.
+A target can contain references to [credential libraries][]
+from [credential stores][] which belong to the same project as the target.
 A user can establish a session with a [host][]
 in any host set referenced by the target
 if the user has been assigned a [role][]
@@ -58,10 +61,15 @@ TCP targets have the following additional attributes:

 ## Referenced By

+- [Credential Library][]
 - [Host Set][]
 - [Project][]
 - [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 catalog]: /docs/concepts/domain-model/host-catalogs
 [host catalogs]: /docs/concepts/domain-model/host-catalogs
 [host set]: /docs/concepts/domain-model/host-sets
@@ -123,6 +123,18 @@
            "title": "Auth Methods",
            "path": "concepts/domain-model/auth-methods"
          },
+          {
+            "title": "Credentials",
+            "path": "concepts/domain-model/credentials"
+          },
+          {
+            "title": "Credential Libraries",
+            "path": "concepts/domain-model/credential-libraries"
+          },
+          {
+            "title": "Credential Stores",
+            "path": "concepts/domain-model/credential-stores"
+          },
          {
            "title": "Groups",
            "path": "concepts/domain-model/groups"
@@ -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"]
+}