diff --git a/website/content/docs/concepts/domain-model/credential-libraries.mdx b/website/content/docs/concepts/domain-model/credential-libraries.mdx new file mode 100644 index 0000000000..0bdd4304ea --- /dev/null +++ b/website/content/docs/concepts/domain-model/credential-libraries.mdx @@ -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) diff --git a/website/content/docs/concepts/domain-model/credential-stores.mdx b/website/content/docs/concepts/domain-model/credential-stores.mdx new file mode 100644 index 0000000000..81287e81a0 --- /dev/null +++ b/website/content/docs/concepts/domain-model/credential-stores.mdx @@ -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 diff --git a/website/content/docs/concepts/domain-model/credentials.mdx b/website/content/docs/concepts/domain-model/credentials.mdx new file mode 100644 index 0000000000..df14152469 --- /dev/null +++ b/website/content/docs/concepts/domain-model/credentials.mdx @@ -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 diff --git a/website/content/docs/concepts/domain-model/index.mdx b/website/content/docs/concepts/domain-model/index.mdx index 9f2b371645..0566997d67 100644 --- a/website/content/docs/concepts/domain-model/index.mdx +++ b/website/content/docs/concepts/domain-model/index.mdx @@ -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 diff --git a/website/content/docs/concepts/domain-model/scopes.mdx b/website/content/docs/concepts/domain-model/scopes.mdx index 6ce46e768f..8df929c9ce 100644 --- a/website/content/docs/concepts/domain-model/scopes.mdx +++ b/website/content/docs/concepts/domain-model/scopes.mdx @@ -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 diff --git a/website/content/docs/concepts/domain-model/sessions.mdx b/website/content/docs/concepts/domain-model/sessions.mdx index 5ad97fe73f..1bd04ca09d 100644 --- a/website/content/docs/concepts/domain-model/sessions.mdx +++ b/website/content/docs/concepts/domain-model/sessions.mdx @@ -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 diff --git a/website/content/docs/concepts/domain-model/targets.mdx b/website/content/docs/concepts/domain-model/targets.mdx index a93fdc9992..9b8dffc979 100644 --- a/website/content/docs/concepts/domain-model/targets.mdx +++ b/website/content/docs/concepts/domain-model/targets.mdx @@ -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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 6fa919098b..8d1fe0f0c9 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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" diff --git a/website/public/data/vault/boundary-controller-policy.hcl b/website/public/data/vault/boundary-controller-policy.hcl new file mode 100644 index 0000000000..d8c920b337 --- /dev/null +++ b/website/public/data/vault/boundary-controller-policy.hcl @@ -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"] +}