diff --git a/website/content/docs/concepts/auditing.mdx b/website/content/docs/concepts/auditing.mdx new file mode 100644 index 0000000000..a4034cf14b --- /dev/null +++ b/website/content/docs/concepts/auditing.mdx @@ -0,0 +1,86 @@ +--- +layout: docs +page_title: Auditing +description: |- + An overview of using Boundary to audit for compliance and threat management +--- + +# Auditing + +A fundamental challenge of securing access to sensitive computing resources is creating a system of record around users' access and actions over remote sessions. +Organizations are typically motivated to invest in recording capabilities to address at least one of the following: + +1. **Compliance management**: Organizations need to prove compliance of their infrastructure's security posture to internal or external auditors. +Records of remote access are often required. + + Various laws and regulations have record keeping requirements. + These laws and regulations specify what activities need to be recorded and how long the records must be kept. + One of the reasons an organization records access to a system is to comply with the record keeping requirements of a law or regulation. + +2. **Threat management**: Organizations must monitor, investigate, and react to security incidents and malicious activity. +Further, security teams seek to prevent incidents and proactively identify potential threats in real time. + + In the course of their investigations, security teams may need to identify suspicious activity conducted by a specific principal or against a specific target. + Administrators may require a breakdown of session information by user or a time-based view of past activities, for example. + +## Session recording + +Boundary provides auditing capabilities via [session recording](/boundary/docs/concepts/domain-model/session-recordings). +In Boundary, a session represents a set of connections between a user and a host from a target. +The session begins when an authorized user requests access to a target, and it ends when that access is terminated. +All sessions have a fixed time limit, and all connections are proxied through a worker. + +Sessions are recorded by workers. +Workers are the proxy between an end user and a target. +No session data is routed through a controller during the recording stage. +The worker stores the session recording on local disk during the recording phase, and then moves the recording to the external object store when the session is terminated. Session recordings are stored in the [BSR](#bsr-directory-structure) (Boundary Session Recording) format. +Any credentials needed to access the external object store are passed from the controller to the recording worker when the session is established. + +In a multi-hop session, the worker that is configured to access the external object store is the worker that records the session. +If no worker can access the storage backend, the session is canceled and an error is returned. + +You view session recordings with a session player that runs in a web browser. +The session player is an aggregation of web components that work together to present the different parts of a session recording as a logical whole. +A controller retrieves the contents of a recording from a worker with access to the external object store. +The controller decodes the contents of the recording into a format that is usable by the player. +The player then retrieves the data from the controller. + +## Storage buckets + +A resource known as a [storage bucket](/boundary/docs/concepts/domain-model/storage-buckets) is used to store the recorded sessions. +The storage bucket represents a bucket in an external object store. +At this time, the only supported storage for storage buckets is AWS S3. +In AWS S3, a storage bucket contains the bucket name, region, and optional prefix, as well as any credentials needed to access the bucket, such as the secret key. + +Before you can use a storage bucket to record sessions, you must configure a worker with local storage to act as a cache. +The entire recording is written to the local storage cache before it is uploaded. +Once the session is complete, the files are automatically synced with the external storage bucket and deleted from the worker's local storage. + +A storage bucket exists in either the Global scope or an Org scope. +A storage bucket that is associated with the Global scope can be associated with any target. +However, a storage bucket in an Org scope can only be associated with targets in a project from the same Org scope. +Any storage buckets associated with an Org scope are deleted when the Org itself is deleted. + +Deleting a storage bucket in Boundary does not delete the bucket in the external object store, nor does it delete the recorded sessions in the bucket. +The storage bucket's lifecycle does not affect the lifecycle of the bucket in the external object store. +Any session recording metadata that is attached to the storage bucket is deleted when the storage bucket is deleted. + +## BSR directory structure + +The BSR (Boundary Session Recording) defines a hierarchical directory structure of files and a binary file format. +It contains all the data transmitted between a user and a target during a single session. + +Boundary creates the top-level directory of the BSR as `.bsr`. This top level directory contains session summary information and subdirectories for connections. + +A BSR connections directory contains a summary of connections, as well as inbound and outbound requests. +If you use a multiplexed protocol, there are subdirectories for the channels. + + +BSR directories are validated based on the contents in the directory. +Each BSR directory contains a SHA256SUMS and SHA256SUMS.sign file that can be used to cryptographically verify the BSR directory's contents. +The SHA256SUMS file contains rows of file names paired with a checksum for the file contents. +The SHA256SUMS.sign is a copy of the SHA256SUMS file, signed with the BSR's private key. + + + +For more information, refer to the [overview of configuring session recording](/boundary/docs/configuration/session-recording). diff --git a/website/content/docs/concepts/domain-model/accounts.mdx b/website/content/docs/concepts/domain-model/accounts.mdx index f47126468f..6a59b7ff90 100644 --- a/website/content/docs/concepts/domain-model/accounts.mdx +++ b/website/content/docs/concepts/domain-model/accounts.mdx @@ -36,7 +36,7 @@ Password account types have the following additional attributes: - `password` - (optional) Not setting the `password` disables the account. -### LDAP Account Attributes +### LDAP Account Attributes Beta LDAP account types have the following additional attributes: @@ -57,8 +57,8 @@ LDAP account types have the following additional attributes: - `dn` - (output only) Maps to the distinguished name for the authenticated user, and is updated every time the user successfully authenticates. It is empty until the - user's first successful authentication. - + user's first successful authentication. + - `member_of_groups` - (output only) A list of the groups the authenticated user is a member of. It is empty until the user's first successful authentication. diff --git a/website/content/docs/concepts/domain-model/auth-methods.mdx b/website/content/docs/concepts/domain-model/auth-methods.mdx index 191f40bc03..cf0dc1f250 100644 --- a/website/content/docs/concepts/domain-model/auth-methods.mdx +++ b/website/content/docs/concepts/domain-model/auth-methods.mdx @@ -31,7 +31,7 @@ The password auth method has the following additional attributes: - `min_password_length` - (required) The default is 8. -### LDAP Auth Method Attributes +### LDAP Auth Method Attributes Beta The ldap auth method has the following additional attributes: @@ -43,7 +43,7 @@ The ldap auth method has the following additional attributes: - `insecure_tls` - (optional) If true, skips LDAP server SSL certificate validation, which is insecure and should be used with caution. Defaults to - false. + false. - `discover_dn` - (optional) If true, use anon bind to discover the bind DN (Distinguished Name) of a user. Defaults to false. @@ -52,19 +52,19 @@ The ldap auth method has the following additional attributes: group searches. Defaults to false. - `upn_domain` - (optional) If set, the userPrincipalDomain is used to construct - the UPN string for the authenticating user. The constructed UPN appears as + the UPN string for the authenticating user. The constructed UPN appears as [username]@UPNDomain Example: example.com, which causes Boundary to bind as username@example.com when it authenticates the user. - `urls` - (required) The LDAP URLS that specify LDAP servers to connect to. There must be at least one URL for each LDAP auth method. When attempting to - connect, the URLs are tried in the order specified. + connect, the URLs are tried in the order specified. - `user_dn` - (optional) If set, the base DN under which to perform user search. Example: ou=Users,dc=example,dc=com -- `user_attr` - (optional) If set, defines the attribute on a user's entry - matching the login-name passed when the user authenticates. Examples: cn, uid +- `user_attr` - (optional) If set, defines the attribute on a user's entry + matching the login-name passed when the user authenticates. Examples: cn, uid - `user_filter` - (optional) If set, the Go template used to construct an LDAP user search filter. The template can access the following context variables: @@ -94,7 +94,7 @@ The ldap auth method has the following additional attributes: - `certificates` - (optional) If set, PEM encoded x509 certificates in ASN.1 DER form that can be used as trust anchors when connecting to an LDAP - provider. + provider. - `client_certificate` - (optional) If set, a PEM encoded x509 certificate in ASN.1 DER form to be used as a client certificate. It must be set, if you @@ -103,17 +103,17 @@ The ldap auth method has the following additional attributes: - `client_certificate_key` - (optional) If set, a PEM encoded certificate key in PKCS #8, ASN.1 DER form. It must be set, if you specify the optional client_certificate. - -- `bind_dn` - (optional) If set, the distinguished name of entry to bind when + +- `bind_dn` - (optional) If set, the distinguished name of entry to bind when performing user and group searches. Example: - cn=vault,ou=Users,dc=example,dc=com + cn=vault,ou=Users,dc=example,dc=com - `bind_password` - (optional) If set, the password to use along with bind_dn when performing user search. It must be set, if you specify the optional bind_dn. - `use_token_groups` - (optional) If true, use the Active Directory tokenGroups - constructed attribute of the user to find the group memberships. This + constructed attribute of the user to find the group memberships. This finds all security groups, including nested ones. - `account_attribute_maps` - (optional) If set, the attribute maps from custom @@ -121,7 +121,7 @@ The ldap auth method has the following additional attributes: maps are represented as key=value where the key equals the from_attribute, and the value equals the to_attribute. For example, "preferredName=fullName". All attribute names are case insensitive. - + ## Referenced By diff --git a/website/content/docs/concepts/domain-model/index.mdx b/website/content/docs/concepts/domain-model/index.mdx index e5db6a2407..4662f003bb 100644 --- a/website/content/docs/concepts/domain-model/index.mdx +++ b/website/content/docs/concepts/domain-model/index.mdx @@ -88,19 +88,19 @@ significant number of resources exist. that binds an identity to a set of permissions or capabilities on a [host][] for a [session][]. -- **[Credential Library][]** : +- **[Credential library][]** : A resource that provides [credentials][] of the same type and same access level from a single [credential store][]. -- **[Credential Store][]** : +- **[Credential store][]** : 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][]** : +- **[Authentication method][]** : A resource that provides a mechanism for [users][] to authenticate to Boundary. @@ -116,17 +116,17 @@ significant number of resources exist. that represents a computing element with a network address reachable from Boundary. -- **[Host Catalog][]** : +- **[Host catalog][]** : A resource that contains [hosts][] and [host sets][]. -- **[Host Set][]** : +- **[Host set][]** : A resource that represents a collection of [hosts][] which are considered equivalent for the purposes of access control. -- **[Managed Group][]** : +- **[Managed group][]** : A resource that groups [accounts][] based on criteria established by a third-party service backing the [authentication method][]. It can be used as a principal in [roles][]. @@ -142,9 +142,16 @@ significant number of resources exist. which define the permissions granted to the [user][] on the [host][] for the duration of the session. +- **[Session recordings][]** : + A session recording represents a directory structure of files in an external object store that together are the recording of a single [session][] between a [user][] and a [target][]. + - **[Scope][]** : A [permission][] boundary modeled as a container. +- **[Storage bucket][]** : + A storage bucket is used to store [session recordings][]. + The storage bucket represents a bucket in an external object store. + - **[Target][]** : A resource that represents a networked service @@ -194,7 +201,9 @@ Refer to the [Scopes] section to help you understand the structure of resources [scopes]: /boundary/docs/concepts/domain-model/scopes [project]: /boundary/docs/concepts/domain-model/scopes#projects [session]: /boundary/docs/concepts/domain-model/sessions +[session recordings]: /boundary/docs/concepts/domain-model/session-recordings [sessions]: /boundary/docs/concepts/domain-model/sessions +[storage bucket]: /boundary/docs/concepts/domain-model/storage-buckets [target]: /boundary/docs/concepts/domain-model/targets [targets]: /boundary/docs/concepts/domain-model/targets [user]: /boundary/docs/concepts/domain-model/users diff --git a/website/content/docs/concepts/domain-model/managed-groups.mdx b/website/content/docs/concepts/domain-model/managed-groups.mdx index d35e9175cb..ee98461ef2 100644 --- a/website/content/docs/concepts/domain-model/managed-groups.mdx +++ b/website/content/docs/concepts/domain-model/managed-groups.mdx @@ -41,7 +41,7 @@ OIDC managed groups have the following additional attributes: [filtering concepts]: /boundary/docs/concepts/filtering [oidc managed groups filtering]: /boundary/docs/concepts/filtering/oidc-managed-groups -### LDAP Managed Group Information and Attributes +### LDAP Managed Group Information and Attributes Beta Membership in LDAP managed groups is evaluated when the auth method is used for authentication, based on information contained within the LDAP server. Every diff --git a/website/content/docs/concepts/domain-model/session-recordings.mdx b/website/content/docs/concepts/domain-model/session-recordings.mdx new file mode 100644 index 0000000000..a54c5fb850 --- /dev/null +++ b/website/content/docs/concepts/domain-model/session-recordings.mdx @@ -0,0 +1,66 @@ +--- +layout: docs +page_title: Domain Model - Session Recordings +description: |- + The anatomy of a Boundary session recording +--- + +# Session recordings HCP/ENT + + +A session recording represents a directory structure of +files in an external object store that together are the +recording of a single [session][] between a [user][] and a [target][]. + +The lifecycle of a session recording does not affect the +lifecycle of any files stored in the external object store. + +A session recording belongs to one and only one [storage bucket][]. +It is deleted when you delete the [storage bucket][] it belongs to. + +A session recording is associated with the +[target][] that the recorded session was against. +However, the lifecycle of a session recording is not tied to +the lifecycle of the [target][] it is associated with. +If the [target][] associated wtih a session recording is deleted, +the association to the [target][] is deleted, not the session recording itself. + +Deleting a session recording does not delete or modify +any of the files in the external object store that the session recording represents. + +The session recording captures all interactions that take place during +the session, including metadata about the [user][], [target][] and any +[hosts][], [host sets][], [host catalogs][], or [credentials][] used. + +A session recording represents [connections][] as separate +entities within the recording. Each recorded connection may also contain a recorded channel. This represents a single channel +in which the [user][] interacted with the [target][] in protocols that +multiplex user interactions over single connections. For example, +the SSH protocol multiplexes user interactions in a single +connection, so a user's interactions over SSH are recorded +in a channel. + +A session recording belongs to the scope of the [storage bucket][] +it is stored in. The scope can be either the global scope or an [organization][] +scope. + +## Referenced by + +- [Storage Bucket][] + +## Service API Docs + +The following services are relevant to this resource: + +- [Session recording service](/boundary/api-docs/session-recording-service) + +[connections]: /boundary/docs/concepts/domain-model/session-connections +[credentials]: /boundary/docs/concepts/domain-model/credentials +[host catalogs]: /boundary/docs/concepts/domain-model/host-catalogs +[host sets]: /boundary/docs/concepts/domain-model/host-sets +[hosts]: /boundary/docs/concepts/domain-model/hosts +[target]: /boundary/docs/concepts/domain-model/targets +[user]: /boundary/docs/concepts/domain-model/users +[organization]: /boundary/docs/concepts/domain-model/scopes#organizations +[session]: /boundary/docs/concepts/domain-model/sessions +[storage bucket]: /boundary/docs/concepts/domain-model/storage-buckets \ No newline at end of file diff --git a/website/content/docs/concepts/domain-model/storage-buckets.mdx b/website/content/docs/concepts/domain-model/storage-buckets.mdx new file mode 100644 index 0000000000..611d2ad242 --- /dev/null +++ b/website/content/docs/concepts/domain-model/storage-buckets.mdx @@ -0,0 +1,74 @@ +--- +layout: docs +page_title: Domain Model - Storage Bucket +description: |- + The anatomy of a Boundary storage bucket +--- + +# Storage buckets HCP/ENT + + +A resource known as a storage bucket is used to store the [session recordings][]. +The storage bucket represents a bucket in an external object store. +A storage bucket's name is optional, but it must be unique if you define one. +Storage buckets can be associated with zero to many [targets][]. + +A storage bucket exists in either the Global scope or an Org scope. +A storage bucket that is associated with the Global scope can be associated with any target. +However, a storage bucket in an Org scope can only be associated with targets in a project from the same Org scope. +Any storage buckets associated with an Org scope are deleted when the Org itself is deleted. + +Deleting a storage bucket in Boundary does not delete the bucket in the external object store, nor does it delete the recorded sessions in the bucket. +The storage bucket's lifecycle does not affect the lifecycle of the bucket in the external object store. +Any session recording metadata that is attached to the storage bucket is deleted, when the storage bucket is deleted. + +## Attributes + +A storage bucket has the following configurable attributes: + +- `name` - (Optional) The name of the resource in Boundary. +The name is optional, but if you set it, it must be unique within the scope ID. +- `description` - (Optional) A description of the resource. +- `bucket_name` - (Required) The name of the bucket in the external object store. +You must provide a name for the bucket in the external object store. +- `bucket_prefix` - (Optional) The prefix used to organize the data that is stored in the external object store. +- `plugin_name` - (Required) The plugin name must reference an installed plugin. +- `worker_filter` - (Required) A filter to identify the worker or workers that can process requests for the storage bucket. +- `attributes` - (Optional) A collection of fields the plugin uses to interface with the backing service. +- `secrets` - (Optional) A collection of sensitive fields, like [credentials][], which the plugin uses to interface with the backing service. +These fields are write only. + +### AWS S3 attributes and secrets + +At this time, the only supported storage for storage buckets is AWS S3. +In AWS S3, a storage bucket contains the bucket name, region, and optional prefix, as well as any credentials needed to access the bucket, such as the secret key. + +#### Attributes + +AWS S3 buckets have the following attributes: + +- `region` - (Required) The S3 region to configure the storage bucket in. +- `disable_credential_rotation` - (Optional) If set to `true`, credential rotation is not performed. +By default, the AWS plugin [rotates credentials](https://github.com/hashicorp/boundary-plugin-aws/blob/main/README.md#credential-rotation). + +#### Secrets + +AWS S3 buckets have the following secrets: + +- `access_key_id` - (Required) The access key ID for the IAM user to use with this storage bucket. +- `secret_access_key` - (Required) The secret access key for the IAM user to use with this storage bucket. + +# Referenced by + +- [Session recordings](/boundary/docs/concepts/domain-model/session-recordings) + +## Service API Docs + +The following services are relevant to this resource: + +- [Session recording service](/boundary/api-docs/session-recording-service) + +[session recordings]: /boundary/docs/concepts/domain-model/session-recordings +[credentials]: /boundary/docs/concepts/domain-model/credentials +[targets]: /boundary/docs/concepts/domain-model/targets +[scope]: /boundary/docs/concepts/domain-model/scopes \ No newline at end of file diff --git a/website/content/docs/concepts/domain-model/targets.mdx b/website/content/docs/concepts/domain-model/targets.mdx index ba11d06ca9..d50713fba3 100644 --- a/website/content/docs/concepts/domain-model/targets.mdx +++ b/website/content/docs/concepts/domain-model/targets.mdx @@ -79,7 +79,7 @@ TCP targets have the following additional attributes: The default is 8 hours (28800 seconds). This value must be greater than 0. -### SSH target attributes HCP Only +### SSH target attributes HCP/ENT SSH targets can source username/password or SSH private key credentials from Vault [credential libraries][] or static [credentials][]. Boundary then injects credentials into the SSH session between a client and end host. This allows users to @@ -102,7 +102,11 @@ SSH targets have the following additional attributes: You can configure an egress filter to enable [multi-hop](/boundary/docs/configuration/worker/pki-worker#multi-hop-workershcp-only) connections. If you do not configure an egress filter, then Boundary uses a single worker to connect to the controller. -- `ingress_worker_filter` - (optional) HCP Only +- `enable_session_recording` - (optional) + Set to `true` to enable [session recordings][] for a target. + If you enable session recording, the `storage_bucket_id` is required. + +- `ingress_worker_filter` - (optional) HCP/ENT A boolean expression to [filter][] which ingress workers can handle sessions for this target. Ingress worker filters determine which workers you connect with to initiate a session. @@ -123,12 +127,17 @@ SSH targets have the following additional attributes: The default is 8 hours (28800 seconds). This value must be greater than 0. +- `storage_bucket_id` - (optional) + Designates the storage bucket to be used for session recording. + This attribute is required if you set `enable_session_recording` to `true`. + ## Referenced by - [Credential Library][] - [Host Set][] - [Project][] - [Session][] +- [Session Recordings][] - [Worker Filtering][] [credentials]: /boundary/docs/concepts/domain-model/credentials @@ -150,6 +159,7 @@ SSH targets have the following additional attributes: [roles]: /boundary/docs/concepts/domain-model/roles [session]: /boundary/docs/concepts/domain-model/sessions [sessions]: /boundary/docs/concepts/domain-model/sessions +[session recordings]: /boundary/docs/concepts/domain-model/session-recordings [filter]: /boundary/docs/concepts/filtering/worker-tags [worker filtering]: /boundary/docs/concepts/filtering/worker-tags [user]: /boundary/docs/concepts/domain-model/users diff --git a/website/content/docs/concepts/iam.mdx b/website/content/docs/concepts/iam.mdx index 8b9de26e0a..1f2d83503d 100644 --- a/website/content/docs/concepts/iam.mdx +++ b/website/content/docs/concepts/iam.mdx @@ -54,13 +54,13 @@ as the auth method. The accounts and users are only created once the user authen ### Granting permissions When setting up access controls for a user, it is important to first consider which scope(s) the user needs access to. **Each scope requires its own set of roles**, -giving users permission to perform actions through [grants strings](/boundary/docs/concepts/security/permissions/grants). +giving users permission to perform actions through grants strings. It is recommended to add the user to a group, and then add the group to the role(s), instead of adding the user directly to the role(s). This way, you can manage multiple users at the same time, and it is easier to change the permissions of the user by adding/removing them from groups. You can manage OIDC/LDAP users and managed groups the same way, directly in the provider. ## Examples Here are a few examples of access management for personas, using this sample scope structure. In this structure, there are 7 scopes overall: 1 global, 2 Orgs, and 4 -Projects. To learn more about writing grants, refer to [grants strings](/boundary/docs/concepts/security/permissions/grants). +Projects. ![IAM Example Structure](/img/iam-example-structure.png) diff --git a/website/content/docs/concepts/security/permissions/advanced.mdx b/website/content/docs/concepts/security/permissions/assignable-permissions.mdx similarity index 64% rename from website/content/docs/concepts/security/permissions/advanced.mdx rename to website/content/docs/concepts/security/permissions/assignable-permissions.mdx index 6ed3bab7f8..b1f65df4dd 100644 --- a/website/content/docs/concepts/security/permissions/advanced.mdx +++ b/website/content/docs/concepts/security/permissions/assignable-permissions.mdx @@ -1,20 +1,26 @@ --- layout: docs -page_title: Advanced Concepts +page_title: Assignable Permissions description: |- - Advanced permissions concepts + Assignable Permissions --- -# Advanced Concepts - ## Assignable Permissions -Resources identified by the ID/Type selectors have permissions granted to the user in the form of actions and visibility (via `output_fields`). -### Advanced Actions -From a permissions standpoint, all actions take place against directly implemented -or abstract types. There may be actions that are only implemented by some concrete -types (e.g., not all auth-method implementations support a change-password -action), but the permissions model still defines these capabilities at the abstract -type level. This helps keep the overall system relatively simple and predictable. + +Resources identified by the ID/Type selectors have permissions granted to the +user in the form of actions and visibility (via `output_fields`). Each of these +is detailed in the subsections below. + +### Actions + +Actions convey the ability to perform some action against a resource or +collection. Many of these are common CRUD actions (`create`, `read`, `update`, +`delete`) but many resources also specify actions specific to their type; for +instance, a `target` has an `authorize-session` action to allow you to request +making a connection to that target, and `auth-method` resources have an +`authenticate` action to allow you to authenticate to Boundary. For the most +part these are straightforward, however there are a couple of special cases to +know. #### Subactions @@ -39,7 +45,27 @@ Boundary (that is, granting access to `u_anon`). By granting the `no-op` action to users, they can see the resources in the output of a list command without needing other capability grants as well. -### Output fields +### Anonymous User Restrictions + +Starting in Boundary 0.9.0, there are severe limits placed on the actions +allowed to be assigned to the anonymous user `u_anon`. This is meant to avoid +situations where an operator accidentally or mistakenly adds the anonymous user +to a role that provides more privileges than might be intended for +unauthenticated users. + +The set of actions is currently restricted to listing scopes and auth methods +and authentication to auth methods (plus `no-op` actions for listing +visibility). If further use-cases arise from user feedback this list can be +expanded. + +Note: there is no special error message returned when access is denied due to it +being disallowed to the anonymous user. It is still possible to assign grants to +a role on which the anonymous user is a principal that can never match the +anonymous user. In the future this may change, but trying to limit this +introduces other restrictions on reasonable administrative workflows so an +acceptable set of tradeoffs would need to be figured out. + +### Output Fields Grant strings can contain an `output_fields` field. This allows fine-grained control over visibility of data returned to users. @@ -108,84 +134,4 @@ composition, is equivalent to using Boundary's default; however the moment that grants start specifying output fields, it is composed from an empty set and thus nothing is contained unless explicitly specified. (An actual empty set is not currently supported, as we don't perform validation on the values given. -However, this means setting `output_fields=none` is functionally equivalent!) - -### Anonymous user restrictions - -Starting in Boundary 0.9.0, there are severe limits placed on the actions -allowed to be assigned to the anonymous user `u_anon`. This is meant to avoid -situations where an operator accidentally or mistakenly adds the anonymous user -to a role that provides more privileges than might be intended for -unauthenticated users. - -The set of actions is currently restricted to listing scopes and auth methods -and authentication to auth methods (plus `no-op` actions for listing -visibility). If further use cases arise from user feedback, this list can be -expanded. - -When an anonymous user is denied access, there is no special error message that is returned. -It is still possible to assign grants to -a role on which the anonymous user is a principal that can never match the -anonymous user. In the future this may change, but trying to limit this -introduces other restrictions on reasonable administrative workflows, so an -acceptable set of tradeoffs would need to be figured out. - -## Wildcard - -Various wildcard possibilities are allowed: - -### Wildcard ID - -When you use only a wildcard for the ID, `*`, it matches all IDs of the given type. You can use this format -with both top-level resource types or none. For example: - -`id=*;type=host-set;actions=create,read,update,set-hosts` - -### Wildcard type - -You can use a wildcard for the `type` for any non-top-level resources with pinned IDs: - -`id=hcst_1234567890;type=*;actions=create,read,update` - -This grant format would allow `create`, `read`, and `update` actions for all types of -subordinate resources (in this case host sets and hosts) underneath the host -catalog with ID `hcst_1234567890`. - -### Wildcard ID and type - -If ID and type are both wildcards, the grant is essentially a catch-all that -matches any resource of any type within the scope and allows the given -actions. - -`id=*;type=*;actions=read,list` - -### Wildcard ID, type, and actions - -Finally, ID, type, and actions can all be wildcards: - -`id=*;type=*;actions=*` - -Such a grant is essentially a full administrator grant for a scope. - -## Templates - -A few template possibilities exist, which will -substitute the given value into the ID field of the grant string at grant evaluation time: - -- `{{.Account.Id}}`: The substituted value is the account ID associated with the - token used to perform the action. As an example, - `id={{.Account.Id}};actions=read,change-password"` is one of Boundary's - default grants to allow users that have authenticated with the Password auth - method to change their own password. - - **NOTE**: Prior to Boundary 0.11.1, `{{account.id}}` must be used instead. - Boundary 0.11.1+ changes this for consistency with other places within - Boundary that are gaining templating support, but supports both formats for - backwards compatibility. - -- `{{.User.Id}}`: The substituted value is the user ID associated with the token - used to perform the action. - - **NOTE**: Prior to Boundary 0.11.1, `{{user.id}}` must be used instead. - Boundary 0.11.1+ changes this for consistency with other places within - Boundary that are gaining templating support, but supports both formats for - backwards compatibility. - +However, this means setting `output_fields=none` is functionally equivalent!) \ No newline at end of file diff --git a/website/content/docs/concepts/security/permissions/grants.mdx b/website/content/docs/concepts/security/permissions/grants.mdx deleted file mode 100644 index 7114be18f7..0000000000 --- a/website/content/docs/concepts/security/permissions/grants.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -layout: docs -page_title: Grant Strings -description: |- - Grant Strings ---- - -# Grant Strings - -In Boundary, grants are a set of permissions that you give to the principals, or -[users](/boundary/docs/concepts/domain-model/users) and [groups](/boundary/docs/concepts/domain-model/groups), -of a specific role defined in a specific scope. - -When you write grant strings, you should consider the following questions: - -- Which specific scope should these permissions be applied to? -- Which specific role should have these permissions? -- Which specific resources should this grant apply to? -- What resource types should this apply to? -- What kinds of actions should the principals (users and groups) be able to perform? - -Grant strings can be composed of up to 4 parts: -- [ID](#id) -- [Type](#type) -- [Actions](#actions) -- [Output fields](#output-fields) - -You use selectors to indicate which resources the grant should apply to. -Selectors can be specific IDs or wildcard IDs and type selectors. There are currently two types of selectors: - -- An `id` field that indicates a specific resource or a wildcard to match all - -- A `type` field that indicates a specific resource type or a wildcard to match - all; it might also be used to grant permissions on collections of resources - -Additionally, there are two types of assigned permissions: - -- An `actions` field indicates which actions to allow the client to perform on - the resources matched by `id` and `type` - -- An `output_fields` field indicates which top-level fields to return in the - response - -The format of a full grant string is: - -- `id=;type=;actions=;output_fields=` - -You can find grant [examples](#common-grant-examples) at the bottom of this page. - - -`output_fields` is omitted in most examples for brevity, but they are valid -in all of them. It is also valid in each case to omit `actions` and specify -_only_ `output_fields`. - - -## ID - -The **ID** is the specific resource that you select for the grant. -You can use a [wildcard](/boundary/docs/concepts/security/permissions/advanced#wildcard) (*) to include all resources of the type and scope. -Each grant string supports only 1 ID or a wildcard. By specifying a single ID, the top-level resource -is "pinned", meaning the permissions only apply to that resource and any subordinate resources. - -Some examples of valid IDs are: - -- `id=*` (all) -- `id=ttcp_123456789` -- `id=w_abcdefghi` - - -## Type - -The **Type** is the type of resource that you select for the grant. -You can use a [wildcard](/boundary/docs/concepts/security/permissions/advanced#wildcard) (*) to -include all resource types in the scope. -Each grant string supports only 1 type or a wildcard. - -Some commonly used types are: - -- `*` (all) -- `session` -- `target` -- `user` -- `worker` - -For a full list of types, see the [Resource Table](/boundary/docs/concepts/security/permissions/resource-table). - -## Actions - -**Actions** convey the ability to perform some action against a resource or collection. -You can select which actions you want to apply to a grant. -You can also use a [wildcard](/boundary/docs/concepts/security/permissions/permission-grant-formats#wildcard-id) to include all valid actions. -Each grant string can include one or more comma separated actions. -Some commonly used actions include: - -- `*` (all) -- `list` -- `create` -- `read` -- `update` -- `delete` - -To learn more about actions, see [advanced actions](/boundary/docs/concepts/security/permissions/advanced#advanced-actions). -For a full list of actions, see the [Resource Table](/boundary/docs/concepts/security/permissions/resource-table). - -## Output fields - -**Output fields** are top-level fields that are returned in the response. Output fields -are **optional** and not commonly used. - -Examples of valid output fields include: - -- `none` -- `id` -- `name` -- `description` - -To learn more about output fields, see [output fields](/boundary/docs/concepts/security/permissions/advanced#output-fields) - -## Common grant examples - -The following are examples of commonly used grant strings for specific roles and scopes. - -**All actions** - -This grant string allows users to perform any actions on any resources in the scope: - -- `id=*;type=*;actions=*` - -**View all** - -This grant string allows users to list and read any resources in the scope: - -- `id=*;type=*;actions=read,list` - -**View targets only** - -This **project scope** grant string allows users to list and read any targets in the specific project. -This example is only applicable to project scopes because targets can only exist inside a project: - -- `id=*;type=target;actions=read,list` - -**Connect to any target** - -This **project scope** grant string allows users to list, read, and connect to any targets in a specific project. -In addition, these grants allow the user to list, read, and cancel any sessions initiated by the same user. -This example is only applicable to project scopes, since targets can only exist in a project: - -- `id=*;type=target;actions=list,read,authorize-session` -- `id=*;type=session;actions=read:self,cancel:self,list` - -**Connect to a specific target** - -This **project scope** grant string allows users to list, read, and connect to a specific target. -In addition, these grants let users list, read, and cancel any sessions initiated by the same user. -If you want to include several specific targets, you can duplicate the first grant string using the respective IDs of those targets. -This example is only applicable to project scopes, since targets can only exist in a project: - -- `id=;actions=read,authorize-session` -- `type=target;actions=list` -- `id=*;type=session;actions=read:self,cancel:self,list` - -## General grant examples - -The following are examples of general grant strings for any scope: - -**Manage all of 1 resource type** - -- `id=*;type=;actions=*` - -**View all of 1 resource type** - -- `id=*;type=;actions=list,read` - -**Manage a specific resource item** - -- `type=;actions=list` -- `id=;actions=*` - -**View a specific resource item** - -- `type=;actions=list` -- `id=;actions=read` \ No newline at end of file diff --git a/website/content/docs/concepts/security/permissions/index.mdx b/website/content/docs/concepts/security/permissions/index.mdx index 63e8cc4547..efa5a187f4 100644 --- a/website/content/docs/concepts/security/permissions/index.mdx +++ b/website/content/docs/concepts/security/permissions/index.mdx @@ -1,6 +1,6 @@ --- layout: docs -page_title: Permissions Overview +page_title: Permissions Index description: |- Boundary's permissions model --- @@ -10,9 +10,10 @@ description: |- ## Overview Boundary's permissions model is a composable, RBAC, allow-only model that -attempts to marry flexibility with usability. This section discusses the permission -model's fundamental concepts, provides examples grant strings, and contains a table -that acts as a cheat sheet to help those new to its grant syntax with crafting roles. +attempts to marry flexibility with usability. This page discusses the permission +model's fundamental concepts, provides examples of the specific forms of allowed +grants, and contains a table that acts as an easy cheat sheet to help those new +to its grant syntax with crafting roles. Boundary's [domain model](/boundary/docs/concepts/domain-model) is based on resource types. These can be implemented directly, such as with targets, or they can be @@ -20,33 +21,58 @@ abstract types that are implemented by concrete types within the system. As an example of the latter, a host catalog is an abstract type and a Static host catalog is a concrete type. +From a permissions standpoint, all actions take place against directly +implemented or abstract types. There may be actions that are only implemented by +some concrete types (e.g., not all `auth-method` implementations will support a +`change-password` action), but the permissions model still defines these +capabilities at the abstract type level. This helps keep the overall system +relatively simple and predictable. + At a very high level, permissions within Boundary are declared via grant strings and mapped to users via roles. +### Grant Strings + +A grant string has a form similar to: + +`id=;type=;actions=;output_fields=` + +Each grant string is a mapping that describes a resource or set of resources and +the permissions that should be granted on them. + +There are currently two types of selectors: -## Grant strings +- An `id` field that indicates a specific resource or a wildcard to match all -A [grant string](/boundary/docs/concepts/security/permissions/grants) is a mapping -that describes a resource or set of resources and the permissions that should be -granted on them. Grant strings can be composed of up to 4 parts: -- ID -- Type -- Actions -- Output fields +- A `type` field that indicates a specific resource type or a wildcard to match + all; this might also be used to grant permissions on collections of resources -To learn about writing grant strings with examples, see [Grant Strings](/boundary/docs/concepts/security/permissions/grants). +Selectors are used to indicate which resources on which the grant should apply, +using specific IDs or wildcard IDs and type selectors. (The acceptable grant +string formats are detailed later on this page.) -## Roles +Additionally, there are two types of assigned permissions: -A [role](/boundary/docs/concepts/domain-model/roles) maps grant strings to principals (users and groups). -Every role assigns grants within a **specific scope**: either the scope in which the role +- An `actions` field indicating which actions to allow the client to perform on + the resources matched by `id` and `type` + +- An `output_fields` field indicating which top-level fields to return in the + response (0.2.1+) + +Grant strings can be supplied via a human-friendly string syntax or via JSON. + +### Roles + +Roles map grant strings to _principals_, currently users and groups. Every role +assigns grants within a specific scope: either the scope in which the role exists, or a scope that is a child of the scope in which the role exists, -as determined by the role's "grant scope ID" value. +controlled by the role's "grant scope ID" value -When a user makes a request, the scope in which to discover grants is either provided by the client -(if against a resource collection itself) or is looked up using the resource's ID. This scope ID, -along with the user's ID and the IDs of the groups the user belongs to, controls which roles are -fetched to provide grants for the request. +When a request is made, the scope in which to discover grants is either provided +by the client (if against a resource collection itself) or is looked up using +the resource's ID. This scope ID, along with the user's ID and the IDs of the +groups the user belongs to, controls which roles are fetched to provide grants +for the request. A role provides grants for a request if the grant scope ID matches the request's scope ID and one or more of the following are true: @@ -62,6 +88,4 @@ scope ID and one or more of the following are true: role Roles are composable; a user's final set of grants will be composed of grants -that originate from all matching roles. - -To learn more about Boundary's access management system, see [Identity and Access Management](/boundary/docs/concepts/iam). \ No newline at end of file +that originate from all matching roles. \ No newline at end of file diff --git a/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx b/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx new file mode 100644 index 0000000000..9383017925 --- /dev/null +++ b/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx @@ -0,0 +1,130 @@ +--- +layout: docs +page_title: Permission Grant Formats +description: |- + Permission Grant Formats +--- + +## Permission Grant Formats + +Because of the aforementioned properties of the permissions model, grants are +relatively simple. All grants take one of four forms. These examples use the +canonical string syntax; the JSON equivalents are simply an object with a string +`id` value, a string `type` value, a string array `actions` value, and a string +array `output_fields` value. + +~> `output_fields` is omitted in most example below for brevity but are valid +in all of them. It is also valid in each case to omit `actions` and specify +_only_ `output_fields`. + +### ID Only + +This is the simplest form: for a given specific resource, allow these actions. +Example: + +`id=hsst_1234567890;actions=read,update` + +This grants `read` and `update` actions to that single resource. It is invalid +to specify `create` or `list` as actions in this format, as this format +explicitly identifies a resource, whereas those actions operate exclusively on +collections. + +### Type Only + +For a given type, allow these actions. Example: + +`type=host-catalog;actions=create,list` + +Because type specifies only a collection as opposed to specific resources within +that collection, only collection actions are allowed in this format. Currently, +this is `create` and `list`. + +There is one additional restriction: this is only valid against "top-level" +resource types, which currently are: + +- Auth Methods +- Auth Tokens +- Groups +- Host Catalogs +- Roles +- Scopes +- Sessions +- Targets +- Users + +The reason for this is that other types of resources are contained within one of +these resource types; for instance, accounts are instantiated within an auth +method. To specify actions against those, you must also specify to which +specific containing resource you want the grants to apply. This can be done with +the pinned format shown below. + +### Pinned ID + +This form "pins" actions to a non-top-level type within a specific ID. It's +easiest to explain with an example: + +`id=hcst_1234567890;type=host-set;actions=create,read,update` + +In this example, the user is able to create, read, or update host sets within +the scope, but _only the host sets belonging to host catalog hcst_1234567890_. +Pinning is essentially a way to use top-level resources to create mini +permission boundaries for their subordinate resources. + +### Wildcard ID + +Various wildcard possibilities are allowed: + +#### Wildcard ID + +When just the ID is `*`, it matches all IDs of the given type. This can be used +with both top-level resource types and not. Example: + +`id=*;type=host-set;actions=create,read,update,set-hosts` + +#### Wildcard Type + +For non-top-level resources with pinned IDs, the `type` can be a wildcard: + +`id=hcst_1234567890;type=*;actions=create,read,update` + +This would allow `create`, `read`, and `update` actions for all types of +subordinate resources (in this case host sets and hosts) underneath the host +catalog with ID `hcst_1234567890`. + +#### Wildcard ID and Type + +If ID and type are both a wildcard, the grant is essentially a catch-all that +will match any resource of any type within the scope and allow the given +actions. + +`id=*;type=*;actions=read,list` + +#### Wildcard ID, Type, and Actions + +Finally, ID, type, and actions can all be wildcards: + +`id=*;type=*;actions=*` + +Such a grant is essentially a full administrator grant for a scope. + +### Templates + +A few template possibilities exist, which will at grant evaluation time +substitute the given value into the ID field of the grant string: + +- `{{.Account.Id}}`: The substituted value is the account ID associated with the + token used to perform the action. As an example, + `id={{.Account.Id}};actions=read,change-password"` is one of Boundary's + default grants to allow users that have authenticated with the Password auth + method to change their own password. + - **NOTE**: Prior to Boundary 0.11.1, `{{account.id}}` must be used instead. + Boundary 0.11.1+ changes this for consistency with other places within + Boundary that are gaining templating support, but supports both formats for + backwards compatibility. + +- `{{.User.Id}}`: The substituted value is the user ID associated with the token + used to perform the action. + - **NOTE**: Prior to Boundary 0.11.1, `{{user.id}}` must be used instead. + Boundary 0.11.1+ changes this for consistency with other places within + Boundary that are gaining templating support, but supports both formats for + backwards compatibility. diff --git a/website/content/docs/concepts/security/permissions/resource-table.mdx b/website/content/docs/concepts/security/permissions/resource-table.mdx index c87a36746e..43d1a8da24 100644 --- a/website/content/docs/concepts/security/permissions/resource-table.mdx +++ b/website/content/docs/concepts/security/permissions/resource-table.mdx @@ -5,7 +5,7 @@ description: |- Resource Table --- -# Resource table +## Resource Table The following table works as a quick cheat-sheet to help you manage your permissions. Note that it's not exhaustive; for brevity it does _not_ show diff --git a/website/content/docs/configuration/session-recording/create-storage-bucket.mdx b/website/content/docs/configuration/session-recording/create-storage-bucket.mdx new file mode 100644 index 0000000000..1159c0ac3f --- /dev/null +++ b/website/content/docs/configuration/session-recording/create-storage-bucket.mdx @@ -0,0 +1,105 @@ +--- +layout: docs +page_title: Create a storage bucket +description: |- + How to create a storage bucket for session recording in Boundary +--- + +# Create a storage bucket + +As of Boundary 0.13.0, you can record and audit user sessions. +A resource known as a [storage bucket](/boundary/docs/concepts/domain-model/storage-buckets) is used to store the recorded sessions. +The storage bucket represents a bucket in an external store. +Before you can enable session recording, you must create one or more storage buckets. + +A storage bucket can only belong to the Global scope or an Org scope. +A storage bucket that is associated with the Global scope can be associated with any target. +However, a storage bucket in an Org scope can only be associated with targets in a project from the same Org scope. +Any storage buckets associated with an Org scope are deleted when the Org itself is deleted. + +For more information about using session recording to audit user sessions, refer to [Auditing](/boundary/docs/concepts/auditing). + +**Requirements**: +- An AWS S3 storage bucket +- A Boundary PKI worker with access to the AWS S3 storage bucket + + At this time, the only supported storage for storage buckets is AWS S3. + In AWS S3, a storage bucket contains the bucket name, region, and optional prefix, as well as any credentials needed to access the bucket, such as the access and secret key. + +- An AWS IAM role policy with the following statement: + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:GetObjectAttributes" + ], + "Effect": "Allow", + "Resource": "arn:aws:s3:::session_recording_storage/foo/bar/zoo/*" + }, + { + "Action": [ + "iam:DeleteAccessKey", + "iam:GetUser", + "iam:CreateAccessKey" + ], + "Effect": "Allow", + "Resource": "arn:aws:iam::123456789012:user/JohnDoe" + } + ] + } + ``` + +Complete the following steps to create a storage bucket for session recording: + + + + +1. Log in to Boundary. +1. Use the following command to create a storage bucket: + + ```bash + boundary storage-buckets create -bucket-name mybucket1 -plugin-name aws -secrets ‘{“access_key_id”: “123456789” , “secret_access_key” : “123/456789/12345678”}’ -worker-filter ‘“dev” in “/tags/type”’ -attributes ‘{“region”:”us-east-1”,”disable_credential_rotation”:true}’ -scope-id o_1234567890 + ``` + + Replace the values above with the following required AWS secrets and any optional [attributes](/boundary/docs/concepts/domain-model/storage-buckets) you want to associate with the storage bucket: + + - `region`: (Required) The AWS region to use. + - `access_key_id`: (Required) The AWS access key to use. + - `secret_access_key_id`: (Required) The AWS secret access key to use. + This attribute contains the secret access key for static credentials. + - `shared_credentials_file`: (Optional) The shared credentials file to use. + - `shared_credentials_profile`: (Optional) The profile name to use in the shared credentials file. + + + + + +1. Log in to Boundary. +1. Select **Storage Buckets** in the navigation bar. +1. Select **New Storage Bucket**. +1. Complete the following fields: + - **Name**: (Optional) The name field is optional, but if you enter a name it must be unique. + - **Description**: (Optional) An optional description of the bucket for identification purposes. + - **Scope**: (Required) A storage bucket can belong to the Global scope or an Org scope. + It can only associated with targets from the scope it belongs to. + - **Bucket name**: (Required) Name of the bucket in AWS. + - **Bucket prefix**: (Optional) A base path where session recordings are stored. + - **Region**: (Required) The AWS region to use. + - **Access key ID**: (Required) The access key ID that AWS generates for the IAM user to use with the storage bucket. + - **Secret access key**: (Required) The secret access key that AWS generates for the IAM user to use with this storage bucket. + - **Worker filter** (Required) A filter that indicated which Boundary workers have access to the storage. + - **Disable credential rotation** (Optional) Although credentials are stored encrypted within Boundary, by default the [AWS plugin](https://github.com/hashicorp/boundary-plugin-aws) attempts to rotate the credentials you provide. The given credentials are used to create a new credential, and then the original credential is revoked. After rotation, only Boundary knows the client secret the plugin uses. + + Select this option to disable this behavior and prevent the automatic rotation of credentials. + +1. Select **Save**. + + + + +Boundary creates the storage bucket and provides you with the bucket's ID. +Once the storage bucket is created, you can use the bucket's ID to [enable session recording on targets](/boundary/docs/configuration/session-recording/enable-session-recording). \ No newline at end of file diff --git a/website/content/docs/configuration/session-recording/enable-session-recording.mdx b/website/content/docs/configuration/session-recording/enable-session-recording.mdx new file mode 100644 index 0000000000..f7c90bb2c6 --- /dev/null +++ b/website/content/docs/configuration/session-recording/enable-session-recording.mdx @@ -0,0 +1,88 @@ +--- +layout: docs +page_title: Create a storage bucket +description: |- + How to enable session recording on a target in Boundary +--- + +# Enable session recording on a target + +You must enable session recording for any targets that you want to record sessions on. +When you [create a storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket), Boundary provides you with an ID. +You use the storage bucket's ID to associate a target with the storage bucket. + +**Requirements**: + +- One or more storage buckets to store the recordings +- Session recording is only supported for SSH targets at this time. +- The targets must be configured with an ingress or egress worker filter that includes a worker with access to the storage bucket you created. +Refer to [SSH target attributes](/boundary/docs/concepts/docmain-model/targets#ssh-target-attributes-hcp-ent) for more information. +- You must enable injected application credentials on any target that you want to use for session recording. + +Complete the following steps to enable session recording on a target. + + + + +1. Log in to Boundary. +1. Do one of the following: + + - To enable an existing SSH target for session recording, run the following commmand: + + ```bash + boundary targets update ssh -scope-id p_1234567890 -id tssh_1234567890 -enable-session-recording true -storage-bucket-id sb_1234567890 + ``` + + Make sure to add the `-enable-session-recording true` flag to turn on session recording for the target. + Add the `-storage-bucket-id ID` for the storage bucket you want to associate with this target. + + - To create a new target and enable it for session recording, run the following command: + + ```bash + boundary targets create ssh -scope-id p_1234567890 -default -port 22 -name test1 -address 99.12.345.67 -enable-session-recording true -storage-bucket-id sb_1234567890 + ``` + + Make sure to add the `-enable-session-recording true` flag to turn on session recording for the target. + Add the `-storage-bucket-id ID` for the storage bucket you want to associate with this target. + You can configure any other [target attributes](/boundary/docs/concepts/domain-model/targets). + + You can now view the target from the **Targets** page in the Boundary console. + + + + + +1. Log in to Boundary. +1. Select **Orgs** in the navigation pane. +1. Select the org that contains the target you want to enable for session recording. +1. Select the project that contains the target you want to enable for session recording. +1. Select **Targets** in the navigation pane. +1. Do one of the following: + + - To create a new target, select **New Target**. + - To edit an existing target, select the target, and then select **Edit Form**. +1. Configure the target with any relevant [attributes](/boundary/docs/concepts/domain-model/targets). +The following settings are required for session recording: + + - Select **SSH** for the **Type**. + - On the **Injected Application Credentials** tab, select the inject application credential sources you want to use for this target. + + ![Add injected application credentials](/img/inject-creds.png) + +1. Select **Save**. +1. Select **Enable recording**. + + ![Enable session recording](/img/enable-session-recording.png) + +1. Enable the **Record sessions for this target** option. +1. Select the storage bucket where you want to store recordings from this target. + + You can also [create a new storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket). + +1. Select **Save**. + + + + +The target is now enabled for session recording. +Any user session that connects to the target is automatically recorded. \ No newline at end of file diff --git a/website/content/docs/configuration/session-recording/index.mdx b/website/content/docs/configuration/session-recording/index.mdx new file mode 100644 index 0000000000..bc45348bd0 --- /dev/null +++ b/website/content/docs/configuration/session-recording/index.mdx @@ -0,0 +1,17 @@ +--- +layout: docs +page_title: Overview +description: |- + An overview of session recording in Boundary +--- + +# Overview + +Boundary provides auditing capabilities via session recording. +In Boundary, a session represents a set of connections between a user and a host from a target. +The session begins when an authorized user requests access to a target, and it ends when that access is terminated. + +When you enable session recording on a target, a worker records any sessions that access that target. +You can view the recordings later with a session player that runs in a web browser. + +To enable session recording you must first [create a storage bucket](/boundary/docs/configuration/session-recording/create-storage-bucket) and then [enable session recording on the target](/boundary/docs/configuration/session-recording/enable-session-recording). \ No newline at end of file diff --git a/website/content/docs/configuration/worker/index.mdx b/website/content/docs/configuration/worker/index.mdx index a317acc49f..f3aef922f4 100644 --- a/website/content/docs/configuration/worker/index.mdx +++ b/website/content/docs/configuration/worker/index.mdx @@ -100,8 +100,8 @@ configuration. There are no limits on the amount of workers allowed in a multi-hop session configuration. It helps to think of “upstream” and “downstream” nodes in the context of -multi-hope. If you view controllers as the “top” node of a multi-hop chain, any -worker connected to a node is a "downstream" of that node; the node that any +multi-hop. If you view controllers as the “top” node of a multi-hop chain, any +worker connected to a node is "downstream" of that node; the node that any particular worker connects to (whether another worker or a controller) is the "upstream" of that node. For example, in the diagram below, Worker 2’s upstream is Worker 1, and its downstream is Worker 3. diff --git a/website/content/docs/enterprise/automated-license-reporting.mdx b/website/content/docs/enterprise/automated-license-reporting.mdx new file mode 100644 index 0000000000..dad6de9bb4 --- /dev/null +++ b/website/content/docs/enterprise/automated-license-reporting.mdx @@ -0,0 +1,136 @@ +--- +layout: docs +page_title: Automated license utilization reporting +description: >- + Learn what data HashiCorp collects to meter Enterprise license utilization. Enable or disable reporting. Review sample payloads and logs. +--- + +# Automated License utilization reporting + +Automated license utilization reporting sends license utilization data to HashiCorp without requiring you to manually collect and report them. It also lets you review your license usage with the monitoring solution you already use (for example Splunk, Datadog, or others) so you can optimize and manage your deployments. Use these reports to understand how much more you can deploy under your current contract, protect against overutilization, and budget for predicted consumption. + +Automated reporting shares the minimum data required to validate license utilization as defined in our contracts. They consist of mostly computed metrics and will never contain Personal Identifiable Information (PII) or other sensitive information. Automated reporting shares the data with HashiCorp using a secure, unidirectional HTTPS API and makes an auditable record in the product logs each time it submits a report. + +## Enable automated reporting + +To enable automated reporting, you need to make sure that outbound network traffic is configured correctly and [upgrade](#2-upgrade) your enterprise product to a version that supports it. If your installation is air-gapped or network settings are not in place, automated reporting will not work. + +### 1. Allow outbound HTTPS traffic on port 443 + +Make sure that your network allows HTTPS egress on port 443 from https://reporting.hashicorp.services by allow-listing the following IP addresses: + +- 100.20.70.12 +- 35.166.5.222 +- 23.95.85.111 +- 44.215.244.1 + +### 2. Upgrade + +Upgrade to a release that supports license utilization reporting. These releases include: Release 0.13.0 and later. + +### 3. Check logs + +Automatic license utilization reporting will start sending data within 24 hours. Check the product logs for records that the data sent successfully. +The records are sent as system events. +You can use [`file sync`](/boundary/docs/configuration/events/file) to configure a file where Boundary logs events. + +```json +{ + "id": "ZWqRK7XlnN", + "source": "https://hashicorp.com/boundary/Test_InitSysEventer", + "specversion": "1.0", + "type": "system", + "data": { + "version": "v0.1", + "op": "census.(censusJob).Run", + "data": { + "msg": "the following snapshot has been generated {\"snapshot_version\":1,\"id\":{\"ULID\":\"0001J50MM0QGR5KN21FVGYJVP9\",\"Timestamp\":\"2023-05-02T00:00:00Z\"},\"schema_version\":\"1.0.0\",\"service\":\"boundary\",\"process_id\":\"01H2B2KY823KYPVAVC02V65TZV\",\"metrics\":{\"boundary.sessions\":{\"key\":\"boundary.sessions\",\"value\":2,\"kind\":\"counter\",\"mode\":\"write\",\"description\":\"Number of pending sessions from previous day\"}}}" + } + }, + "datacontentype": "application/cloudevents", + "time": "2023-06-07T10:01:53.158933-04:00" +} +``` + +If your installation is air-gapped or your network doesn’t allow the correct egress, logs will show an error. + +```json +{ + "id": "VQyF5VzbTT", + "source": "https://hashicorp.com/boundary/Test_InitSysEventer", + "specversion": "1.0", + "type": "error", + "data": { + "error": "census.(censusJob).Run: unable to export snapshot through agent: unknown: error #0", + "error_fields": { + "Code": 0, + "Msg": "unable to export snapshot through agent", + "Op": "census.(censusJob).Run", + "Wrapped": null + }, + "id": "e_BgPs9hUMxw", + "version": "v0.1", + "op": "census.(censusJob).Run" + }, + "datacontentype": "application/cloudevents", + "time": "2023-06-07T10:21:48.221494-04:00" +} +``` + +In this case, reconfigure your network to allow egress and check back in 24 hours. + +## Opt out + +If your installation is air-gapped or you want to manually collect and report on the same license utilization metrics, you can opt-out of automated reporting. + +Manually reporting these metrics can be time consuming. Opting out of automated reporting does not mean that you also opt out from sending license utilization metrics. Customers who opt out of automated reporting will still be required to manually collect and send license utilization metrics to HashiCorp. + +If you are considering opting out because you’re worried about the data, we strongly recommend that you review the [example payloads](#example-payloads) before opting out. If you have concerns with any of the automatically-reported data please bring them to your account manager. + +You have two options to opt out of automated reporting: +HCL configuration (recommended) +Environment variable (requires restart) + +Opting out in your product’s configuration file doesn’t require a system restart, and is the method we recommend. Add the following block to your `configuration.hcl` file. + +```hcl +reporting { + license { + enabled = false + } +} +``` + +If you need to, you can also opt out using an environment variable, which will provide a startup message confirming that you have disabled automated reporting. This option requires a system restart. + +Set the following environment variable. + +``` +$ export OPTOUT_LICENSE_REPORTING=true +``` + +Now restart your system. + +Check your product logs 24 hours after opting out to make sure that the system isn’t trying to send reports. + +If your configuration file and environment variable differ, the environment variable setting will take precedence. + +## Example payloads + +HashiCorp collects the following utilization data as JSON payloads: +`exporter_version` - The version of the licensing exporter + +```json +"metrics": { + "boundary.sessions": { + "key": "boundary.sessions", + "kind": "counter", + "mode": "write", + "value": 33 + } +} +``` + +Product payload description: + +- Sessions - Sessions is queried from the Boundary store, counts over the last X days \ No newline at end of file diff --git a/website/content/docs/enterprise/index.mdx b/website/content/docs/enterprise/index.mdx new file mode 100644 index 0000000000..417e19cf80 --- /dev/null +++ b/website/content/docs/enterprise/index.mdx @@ -0,0 +1,32 @@ +--- +layout: docs +page_title: Boundary Enterprise +description: |- + An overview of Boundary Enterprise +--- + +# Boundary Enterprise + +Boundary Enterprise has features that are not available in the open source version of the product, as well as support. +The Enterprise version is self-managed in your environment, making it the perfect choice for agencies that are not able to use SaaS products for compliance or regulatory reasons. +The [Install Boundary](/boundary/docs/install-boundary) section can help you build a self-managed production environment using Boundary Enterprise. + +You must obtain a [license](/boundary/docs/enterprise/licensing) to use Boundary Enterprise. + +You can enable or opt out of automated license reporting. +Refer to [Automated license utilization reporting](/boundary/docs/enterprise/automated-license-reporting) for more information. + +## Upgrade from Boundary OSS + +To upgrade from the open source version of Boundary to Boundary Enterprise, complete the following steps: + +1. [Contact sales](https://hashicorp.com/contact-sales) to procure a Boundary Enterprise license. +1. [Upgrade Boundary](/boundary/tutorials/self-managed-deployment/upgrade-version) using a Boundary Enterprise binary. +1. [Activate the license](/boundary/docs/enterprise/licensing). + +## Support + +The best way to get assistance is to open a ticket through our [support portal](https://support.hashicorp.com). +Sign in or create an account to create a ticket. + +For further assistance, scroll down the support page to find other resources including reference guides, deployment guides, tutorials, and a community forum. \ No newline at end of file diff --git a/website/content/docs/enterprise/licensing.mdx b/website/content/docs/enterprise/licensing.mdx new file mode 100644 index 0000000000..4cec6da668 --- /dev/null +++ b/website/content/docs/enterprise/licensing.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: License Boundary Enterprise +description: >- + How to license Boundary Enterprise. +--- + +# License Boundary Enterprise + +The Boundary Enterprise binaries require a license key to enforce entitlements and time restrictions according to your contractual agreement. +Once purchased, your HashiCorp account team send you a valid Boundary license for environment activation. +If you don't yet have an acccount team, but are interested in Boundary Enterprise, you can request access [here](https://www.hashicorp.com/contact-sales). + +Once you have received your valid Boundary license, there are two options for enabling Boundary Enterprise: + +1. You may set the enterprise license for Boundary using an environment variable. +Set the `BOUNDARY_LICENSE` environment variable to the license key value you received: + + `$ export BOUNDARY_LICENSE=02MV4UU43BK5...` + + or + + `$ BOUNDARY_LICENSE=file:///folder_path/license.hclic` + +1. You may specify the enterprise license key in the Boundary controller configuration using the `license` attribute in the `controller` block. +You can either specify the raw license key or the path to a file containing the license key. +Refer to the sample configurations below: + + **Sample #1** + + ```hcl + controller { + name = "controller" + description = "controller" + database { + url = "postgresql://boundary:PASSWORD@127.0.0.1:5432/boundary" + } + public_cluster_addr = "boundary.domain" + license = "file:///folder_path/license.hclic" + } + ``` + **Sample #2** + + ```hcl + controller { + name = "controller" + description = "controller" + database { + url = "postgresql://boundary:PASSWORD@127.0.0.1:5432/boundary" + } + public_cluster_addr = "boundary.domain" + license = "02MV4UU43BK5..." + } + ``` + + Refer to the [controller](/boundary/docs/configuration/controller) configuration documentation for more information. \ No newline at end of file diff --git a/website/content/docs/enterprise/supported-versions.mdx b/website/content/docs/enterprise/supported-versions.mdx new file mode 100644 index 0000000000..eda1766aa9 --- /dev/null +++ b/website/content/docs/enterprise/supported-versions.mdx @@ -0,0 +1,35 @@ +--- +layout: docs +page_title: Boundary Enterprise supported versions +description: >- + The supported versions policy for Boundary Enterprise. Includes information about support periods, control plane and worker compatibility, and Postgres database version support. +--- + +# Boundary Enterprise supported versions policy + +Self-managed Boundary Enterprise environments function optimally when workers and controllers are running the same version. +The following sections outline support periods, control plane & worker compatibility and Postgres DB version support. + +## Support periods + +Generally Available (GA) releases of Boundary Enterprise are consistent with [HashiCorp’s Support Period and End-of-Life (EOL) Policy](https://support.hashicorp.com/hc/en-us/articles/360021185113-Support-Period-and-End-of-Life-EOL-Policy). +Boundary Enterprise releases will be supported for up to two (2) years since release. +Eligible code-fixes and hot-fixes are provided via a new minor release (Z) on top of the latest “major release” branch, for up to two (2) releases from the most current major release. +A major release is identified by a change in the first (X) or second (Y) digit in the following versioning nomenclature: Version X.Y.Z. + +As a best practice, HashiCorp expects customers to stay current within two (2) releases from the latest major release in order to receive optimal support. +Release updates for Boundary Enterprise can be found at https://releases.hashicorp.com. + +## Control plane and worker availability + +Although major releases are supported as outlined within the support periods section above, within a Boundary Enterprise deployment API backwards compatibility is only supported between the control plane and workers from the prior “major release”. +All workers within an environment must be on the same version. + +For example, Boundary workers version 0.13.0 are compatible with Boundary control plane running Boundary 0.14.0. +However, they will not have compatibility once the control plane is updated to version 0.15.0 or above. +Customers are recommended to run the latest versions of Boundary in order to leverage the newest features and bug fixes. + +## PostgreSQL support policy + +Boundary Enterprise will only support PostgreSQL version 13 and above at launch. +On an ongoing basis, Boundary will end support for a PostgreSQL version one (1) year prior to its EOL as documented on PostgreSQL’s versioning policy website. diff --git a/website/content/docs/getting-started/index.mdx b/website/content/docs/getting-started/index.mdx index 53606363a7..ad302986c7 100644 --- a/website/content/docs/getting-started/index.mdx +++ b/website/content/docs/getting-started/index.mdx @@ -7,29 +7,33 @@ description: Getting started with Boundary # Getting Started This section walks through how to get started with Boundary. You’ll learn how -Boundary provides access to private endpoints securely. +Boundary provides secure access to private endpoints. -There are two options to get started with Boundary: +There are three options to get started with Boundary: - **HCP Boundary** is a managed offering of the Boundary product, and is the easiest way to get started. It streamlines deployment and operations, and is available as a freemium service. HCP Boundary allows users to run their own worker proxies, preventing exposure of your network to HashiCorp or clients. - Some enterprise features are only available with HCP Boundary. Review the [Get - started with HCP Boundary](/boundary/docs/getting-started/deploy-and-login) page to + HCP Boundary has features that are not available in the open source version of the product, as well as support. + It has full feature-parity with Boundary Enterprise. + Review the [Get + started with HCP Boundary](/boundary/docs/getting-started/deploy-and-login) section to learn more. +- **Boundary Enterprise** is a customer-hosted offering of Boundary with Enterprise support. +It has full feature-parity with HCP Boundary. +The Enterprise version is self-managed in your environment, making it the perfect choice for agencies that are not able to use SaaS products for compliance or regulatory reasons. +The [Install Boundary](/boundary/docs/install-boundary) section can help you build a self-managed production environment using Boundary Enterprise. - **Boundary OSS** is an open source distribution of Boundary that users can run - in their own environments. The [Getting Started with Boundary - OSS](/boundary/docs/oss/installing/dev-mode) page discusses running Boundary + in their own environments. The [Dev Mode quick start](/boundary/docs/oss/installing/dev-mode) section discusses running Boundary in Dev mode on your local machine, allowing you to get started with the OSS distribution quickly. We recommend you use the Boundary model that best meets your intended use case. If you’re not sure what’s best for you, we recommend reviewing the [Getting -started with HCP Boundary](/boundary/docs/getting-started/deploy-and-login) page. +started with HCP Boundary](/boundary/docs/getting-started/deploy-and-login) section. # Key Concepts Before getting started with Boundary, it's important to understand a few key concepts. Please consult our [Boundary concepts](/boundary/docs/concepts) page to familiarize yourself with Boundary's architecture and terminology. - diff --git a/website/content/docs/install-boundary/configure-controllers.mdx b/website/content/docs/install-boundary/configure-controllers.mdx new file mode 100644 index 0000000000..a1d4defa3b --- /dev/null +++ b/website/content/docs/install-boundary/configure-controllers.mdx @@ -0,0 +1,324 @@ +--- +layout: docs +page_title: Configure controllers +description: |- + Configure Boundary controllers +--- + +# Configure controllers + +Refer to the sections below to configure your Boundary controllers. + +## Prepare TLS certificates + +HashiCorp recommends that the Boundary controller nodes handle TLS via PKI for user connections. +Further, we strongly recommend that you use certificates that are generated and signed by an appropriate certificate authority (CA). + +To use TLS, you must have two files on each Boundary controller node. +You may have to create a new directory to store the certificate material at `/etc/boundary.d/tls`. +Place the files in the following paths: + +- `/etc/boundary.d/tls/boundary-cert.pem` + + In this path, place the Boundary TLS certificate with a Common Name (CN) and Subject Alternate Name (SAN) that matches your planned primary DNS record for accessing the Boundary controllers and any additional SANs as necessary. +- `/etc/boundary.d/tls/boundary-key.pem` + + In this path, place the Boundary TLS certificate's private key. + +If you do not generate unique TLS key material for each node, you should securely distribute the key material to each of the Boundary controller nodes. + +## Prepare KMS keys + +Boundary controllers require the two following different cryptographic keys: + +- **Root key**: The root KMS key acts as a KEK (Key Encrypting Key) for the scope-specific KEKs (also referred to as the scope's root key). +The scope's root KEK and the various DEKs (Data Encryption Keys) are created when a scope is created. +The DEKs are encrypted with the scope's root KEK, and this is in turn encrypted with the KMS key marked for the root purpose. +- **Recovery key**: The recovery KMS key is used for rescue or recovery operations that can be used by a client to authenticate almost any Boundary operation. +A nonce and creation time are included as an encrypted payload, formatted as a token, and sent to the controller. +The time and nonce are used to ensure that a value cannot be replayed by an adversary, and also to ensure that each operation must be individually authenticated by a client, so that revoking access to the KMS has an immediate result. + +The following key is optional: + +- **Worker-auth key (Optional)**: The worker-auth KMS key is shared by the controller and worker to authenticate a worker to the controller. +If a worker is used with PKI authentication, this is unnecessary. + +There are other optional KMS keys that you can configure for different encryption scenarios. +These scenarios include Boundary worker PKI auth encryption and Boundary worker or controller configuration encryption. +Refer to [Data security in Boundary](/boundary/docs/concepts/security/data-encryption) for more information. + + +There are two types of Boundary workers, distinguished by the method by which they authenticate with the Boundary controllers. +One worker uses a PKI exchange to authenticate with the controllers, and the other uses a KMS key that can be used for authentication by both the worker and the controller. +You use the Worker-auth key listed above to enable KMS worker authentication. + + +HashiCorp strongly recommends that you use either Vault Transit or your cloud provider's key management system. +Refer to the [Vault Transit](/vault/docs/secrets/transit) documentation or your cloud provider's key management documentation for more information. + +After you create the keys in Vault or the key management system of your choice, you can prepare the PostgreSQL database. + +## Prepare the database + +Boundary manages its state and configuration in a Relational Database Management System (RDBMS), PostgreSQL. +You should create, set up, and make the PostgreSQL database accessible to the Boundary controller nodes before you configure the nodes. + +Refer to the [Database recommendations](/boundary/docs/install-boundary/system-requirements#database-recommendations) documentation for examples of cloud managed PostgreSQL databases. + +## Create the controller configuration + +Once you have configured the following, you can create the controller configuration: + +- At least three virtual machines with Boundary installed on them +- At least one TLS certificate and key to distribute to the virtual machines for TLS communication +- KMS keys to use for at least root and recovery operations +- A PostgreSQL database to manage configuration and state + +You must complete the following controller configuration for each of the Boundary controller nodes. + +### Base controller configuration + +The core required values for a Boundary controller configuration include the following: + +- `listener` blocks for `api`, `cluster`, and `ops` +- A `kms` block +- `disable_mlock` +- A `controller` block + +When you install Boundary from the HashiCorp Linux Repository, it installs some example configuration files under `/etc/boundary.d/`. +Run the following commands to rename the example configuration files: + +1. `sudo mv boundary.hcl boundary.hcl.old` +1. `sudo mv controller.hcl controller.hcl.old` +1. `sudo mv worker.hcl worker.hcl.old` + +We recommend that you use either the `env://` or `file://` notation in the configuration files to securely provide secret configuration components to the Boundary controller binaries. +In the following controller configuration example, we use `env://` to declare the PostgreSQL connection string, as well as secure the AWS KMS configuration items. + +When you install the Boundary binary using a package manager, it includes a unit file that configures an environment file at `/etc/boundary.d/boundary.env`. +You can use this file to set the sensitive values that are used to configure the Boundary controllers and workers. +The following is an example of how this environment file could be configured: + + + +```shell-session +POSTGRESQL_CONNECTION_STRING=postgresql://boundary:boundary@postgres.yourdomain.com:5432/boundary +AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE +AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +``` + + + + +In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys. + + +Next, populate the `controller.hcl` file with any relevant configuration information. +The following example configuration file is a good starting point for a production Boundary controller installation. +It defines the three `listener` blocks, two unique `kms` blocks that are specific to AWS (as an example), the `disable_mlock` value, and the `controller` block. + + + +```hcl +# disable memory from being swapped to disk +disable_mlock = true + +# API listener configuration block +listener "tcp" { + # Should be the address of the NIC that the controller server will be reached on + # Use 0.0.0.0 to listen on all interfaces + address = "0.0.0.0:9200" + # The purpose of this listener block + purpose = "api" + + # TLS Configuration + tls_disable = false + tls_cert_file = "/etc/boundary.d/tls/boundary-cert.pem" + tls_key_file = "/etc/boundary.d/tls/boundary-key.pem" + + # Uncomment to enable CORS for the Admin UI. Be sure to set the allowed origin(s) + # to appropriate values. + #cors_enabled = true + #cors_allowed_origins = ["https://yourcorp.yourdomain.com", "serve://boundary"] +} + +# Data-plane listener configuration block (used for worker coordination) +listener "tcp" { + # Should be the IP of the NIC that the worker will connect on + address = "0.0.0.0:9201" + # The purpose of this listener + purpose = "cluster" +} + +# Ops listener for operations like health checks for load balancers +listener "tcp" { + # Should be the address of the interface where your external systems' + # (eg: Load-Balancer and metrics collectors) will connect on. + address = "0.0.0.0:9203" + # The purpose of this listener block + purpose = "ops" + + tls_disable = false + tls_cert_file = "/etc/boundary.d/tls/boundary-cert.pem" + tls_key_file = "/etc/boundary.d/tls/boundary-key.pem" +} + +# Controller configuration block +controller { + # This name attr must be unique across all controller instances if running in HA mode + name = "boundary-controller-1" + description = "Boundary controller number one" + + # This is the public hostname or IP where the workers can reach the + # controller. This should typically be a load balancer address + public_cluster_address = "example-cluster-lb.example.com" + + # Enterprise license file, can also be the raw value or env:// value + license = "file:///path/to/license/file.hclic" + + # After receiving a shutdown signal, Boundary will wait 10s before initiating the shutdown process. + graceful_shutdown_wait_duration = "10s" + + # Database URL for postgres. This is set in boundary.env and + #consumed via the “env://” notation. + database { + url = "env://POSTGRESQL_CONNECTION_STRING" + } +} + +# Events (logging) configuration. This +# configures logging for ALL events to both +# stderr and a file at /var/log/boundary/controller.log +events { + audit_enabled = true + sysevents_enabled = true + observations_enable = true + sink "stderr" { + name = "all-events" + description = "All events sent to stderr" + event_types = ["*"] + format = "cloudevents-json" + } + sink { + name = "file-sink" + description = "All events sent to a file" + event_types = ["*"] + format = "cloudevents-json" + file { + path = "/var/log/boundary" + file_name = "controller.log" + } + audit_config { + audit_filter_overrides { + sensitive = "redact" + secret = "redact" + } + } + } +} + +# Root KMS Key (managed by AWS KMS in this example) +# Keep in mind that sensitive values are provided via ENV VARS +# in this example, such as access_key and secret_key +kms "awskms" { + purpose = "root" + region = "us-east-1" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} + +# Recovery KMS Key +kms "awskms" { + purpose = "recovery" + region = "us-east-1" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey2" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} + +# Worker-Auth KMS Key (optional, only needed if using +# KMS authenticated workers) +kms "awskms" { + purpose = "worker-auth" + region = "us-east-1" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} +``` + + +Refer to the list below for explanations of the parameters used in the example above: + +- `disable mlcok (bool: false)` - Disables the server from executing the `mlock` syscall, which prevents memory from being swapped to the disk. +This is fine for local development and testing. +However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all. +Boundary only supports memory locking on UNIX-like systems that support `mlock()` syscall like Linux and FreeBSD. + + On Linux, to give the Boundary executable the ability to use `mlock` syscall without running the process as root, run the following command: + + `sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))` + + If you use a Linux distribution with a modern version of systemd, you can add the following directive to the **"[Service]"** configuration section: + + `LimitMEMLOCK=infinity` + +- `listener` - Configures the listeners on which Boundary serves traffic (API cluster and proxy). +- `controller` - Configures the controller. +If present, `boundary server` starts a controller subprocess. +- `events` - Configures event-specific parameters. + + The example events configuration above is exhaustive and writes all events to both `stderr` and a file. + This configuration may or may not work for your organization's logging solution. + +- `kms` - Configures KMS blocks for [various purposes](/boundary/docs/concepts/security/data-encryption). + + Refer to the links below for configuration information for the different cloud KMS blocks: + + - [AWS](/boundary/docs/configuration/kms/awskms) + - [Azure](/boundary/docs/configuration/kms/azurekeyvault) + - [GCP](/boundary/docs/configuration/kms/gcpckms) + - [OCI](/boundary/docs/configuration/kms/ocikms) + - [AliCloud](/boundary/docs/configuration/kms/alicloudkms) + - [Vault Transit](/boundary/docs/configuration/kms/transit) + +Refer to the documentation for additional [top-level configuration options](/boundary/docs/configuration) and additional [controller-specific options](/boundary/docs/configuration/controller). + +## Initialize the database + +Before you can start Boundary, you must initialize the database from one Boundary controller. +This operation is only required once; it will execute the required database migrations for the Boundary cluster to operate. + +The following command with the included flags creates initial resources in Boundary as an example. +For finer control over these resources, remvoe the flags. + +Run the following command to initialize the database: + +```hcl +boundary database init \ + -skip-auth-method-creation \ + -skip-host-resources-creation \ + -skip-scopes-creation \ + -skip-target-creation \ + -config /etc/boundary.d/controller.hcl +``` + +You can use the help output for the `init` command to view the flags available to skip the creation of any auto-generated resources: + +```hcl +boundary database init -h +``` + +## Start the Boundary service + +When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary controller nodes using `systemd`. +Run the following commands to start the service: + +1. `sudo systemctl enable boundary` +1. `sudo systemctl start boundary` + +## Authenticate and manage resources + +Upon logging in to Boundary for the first time, HashiCorp recommends creating an admin user for the global and project level scopes to manage Boundary. +This allows you to configure targets within those scopes and manage them. + +We recommend that you use the [KMS recovery workflow](/boundary/docs/install-boundary/no-gen-resources#recovery-kms-workflow) to log in to Boundary for the first time. +Refer to [Creating your first login account](/boundary/docs/install-boundary/no-gen-resources/#creating-your-first-login-account) to learn about setting up your first auth method, user, account, and role to log in to Boundary going forward without the reecovery KMS workflow. \ No newline at end of file diff --git a/website/content/docs/install-boundary/configure-workers.mdx b/website/content/docs/install-boundary/configure-workers.mdx new file mode 100644 index 0000000000..90fca169eb --- /dev/null +++ b/website/content/docs/install-boundary/configure-workers.mdx @@ -0,0 +1,406 @@ +--- +layout: docs +page_title: Configure workers +description: |- + Configure Boundary workers +--- + +# Configure workers + +In this topic, we present an opinionated deployment model to show Boundary Enterprise features such as multi-hop sessions. + +Before you configure workers, you should have completed the following steps: + +- Installed Boundary on at least three [controller nodes](/boundary/docs/install-boundary/configure-controllers). +- Prepared or have three existing network boundaries: + - Public/DMZ network + - Intermediary network + - Private network +- Prepared three virtual machines for Boundary workers, one in each network boundary with the Boundary binary installed on it. + +In the following configuration files, there are common configuration components as well as some unique components depending on the role the Boundary worker performs. +There are three files, one for each worker in a unique network boundary. +In a multi-hop configuration, the Boundary workers can serve one of three purposes: an ingress worker, an ingress/egress worker, or an egress worker. + +## Prepare the environment files + +HashiCorp recommends using either the `env://` or `file://` notation within the configuration files, to securely provide secret configuration components to the Boundary worker binaries. +The following configuration example uses `env://` to secure AWS KMS configuration items. + +When you install the Boundary binary using a package manager, it includes a unit file which configures an environment file at `/etc/boundar.d/boundary.env`. +You can use this file to set the sensitive values that are used to configure the Boundary workers. +The following file is an example of how this environment file could be configured: + + + +```shell-session +AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE +AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +``` + + + + +In the example above, the proper IAM roles and permissions for the given `AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` must be in place so that Boundary can use them to access the different KMS keys. + + +## Prepare the worker KMS keys + +The worker-auth storage KMS key is used by a PKI worker for the encrypted storage of authentication keys. +This is not recommended for PKI workers. +If it is not specified, the authentication keys are not encrypted on disk. +Optionally, if you deploy KMS authentication-driven Boundary workers, an additional KMS key must be generated to authenticate the Boundary worker with the controller. + +HashiCorp strongly recommends using the Key Management Ssytem (KMS) of the cloud provider where you deploy your Boundary workers. +Keep in mind that Boundary workers must have the correct level of permissions for interacting with the cloud provider's KMS. +Refer to your cloud provider's documentation, for more information. + +## Create the worker configurations + +After you create the requisite key or keys in the cloud provider of your choice, you can begin configuring the workers. + +The following configuration examples all employ the PKI method of authentication with a worker-led authorization flow. +For more information on configuring KMS authentication for Boundary workers, refer to the [KMS worker configuration documenation](/boundary/docs/configuration/worker/kms-worker). + +### Ingress worker configuration + +Create the `ingress-worker.hcl` file with the relevant configuration information: + + + +```hcl +# disable memory from being swapped to disk +disable_mlock = true + +# listener denoting this is a worker proxy +listener "tcp" { + address = "0.0.0.0:9201" + purpose = "proxy" +} + +# worker block for configuring the specifics of the +# worker service +worker { + public_addr = "" + initial_upstreams = [":9201"] + auth_storage_path = "/etc/boundary.d/auth_storage/" + tags { + type = ["worker1", "upstream"] + } +} + +# Events (logging) configuration. This +# configures logging for ALL events to both +# stderr and a file at /var/log/boundary/.log +events { + audit_enabled = true + sysevents_enabled = true + observations_enable = true + sink "stderr" { + name = "all-events" + description = "All events sent to stderr" + event_types = ["*"] + format = "cloudevents-json" + } + sink { + name = "file-sink" + description = "All events sent to a file" + event_types = ["*"] + format = "cloudevents-json" + file { + path = "/var/log/boundary" + file_name = "ingress-worker.log" + } + audit_config { + audit_filter_overrides { + sensitive = "redact" + secret = "redact" + } + } + } +} + +# kms block for encrypting the authentication PKI material +kms "awskms" { + purpose = "worker-auth-storage" + region = "us-east-1" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} +``` + + + +### Intermediate worker configuration + +Create the `intermediate-worker.hcl` file with the relevant configuration information: + + + +```hcl +# disable memory from being swapped to disk +disable_mlock = true + +# listener denoting this is a worker proxy +listener "tcp" { + address = "0.0.0.0:9201" + purpose = "proxy" +} + +# worker block for configuring the specifics of the +# worker service +worker { + public_addr = "" + initial_upstreams = [":9201"] + auth_storage_path = "/etc/boundary.d/auth_storage/" + tags { + type = ["worker2", "intermediate"] + } +} + +# Events (logging) configuration. This +# configures logging for ALL events to both +# stderr and a file at /var/log/boundary/.log +events { + audit_enabled = true + sysevents_enabled = true + observations_enable = true + sink "stderr" { + name = "all-events" + description = "All events sent to stderr" + event_types = ["*"] + format = "cloudevents-json" + } + sink { + name = "file-sink" + description = "All events sent to a file" + event_types = ["*"] + format = "cloudevents-json" + file { + path = "/var/log/boundary" + file_name = "intermediate-worker.log" + } + audit_config { + audit_filter_overrides { + sensitive = "redact" + secret = "redact" + } + } + } +} + +# kms block for encrypting the authentication PKI material +kms "awskms" { + purpose = "worker-auth-storage" + region = "us-east-1" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey4" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} +``` + + + +### Egress worker configuration + +Create the `egress-worker.hcl` file with the relevant configuration information: + + + +```hcl +# disable memory from being swapped to disk +disable_mlock = true + +# listener denoting this is a worker proxy +listener "tcp" { + address = "0.0.0.0:9201" + purpose = "proxy" +} + +# worker block for configuring the specifics of the +# worker service +worker { + public_addr = "" + initial_upstreams = [":9201"] + auth_storage_path = "/etc/boundary.d/auth_storage/" + tags { + type = ["worker3", "egress"] + } +} + +# Events (logging) configuration. This +# configures logging for ALL events to both +# stderr and a file at /var/log/boundary/.log +events { + audit_enabled = true + sysevents_enabled = true + observations_enable = true + sink "stderr" { + name = "all-events" + description = "All events sent to stderr" + event_types = ["*"] + format = "cloudevents-json" + } + sink { + name = "file-sink" + description = "All events sent to a file" + event_types = ["*"] + format = "cloudevents-json" + file { + path = "/var/log/boundary" + file_name = "egress-worker.log" + } + audit_config { + audit_filter_overrides { + sensitive = "redact" + secret = "redact" + } + } + } +} + +# kms block for encrypting the authentication PKI material +kms "awskms" { + purpose = "worker-auth-storage" + region = "us-east-1" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey5" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} +``` + + + +Refer to the list below for explanations of the parameters used in the example above: + +- `disable mlcok (bool: false)` - Disables the server from executing the `mlock` syscall, which prevents memory from being swapped to the disk. +This is fine for local development and testing. +However, it is not recommended for production unless the systems running Boundary use only encrypted swap or do not use swap at all. +Boundary only supports memory locking on UNIX-like systems that support `mlock()` syscall like Linux and FreeBSD. + + On Linux, to give the Boundary executable the ability to use `mlock` syscall without running the process as root, run the following command: + + `sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))` + + If you use a Linux distribution with a modern version of systemd, you can add the following directive to the **"[Service]"** configuration section: + + `LimitMEMLOCK=infinity` + +- `listener` - Configures the listeners on which Boundary serves traffic (API cluster and proxy). +- `controller` - Configures the controller. +If present, `boundary server` starts a controller subprocess. +- `events` - Configures event-specific parameters. + + The example events configuration above is exhaustive and writes all events to both `stderr` and a file. + This configuration may or may not work for your organization's logging solution. + +- `kms` - Configures KMS blocks for [various purposes](/boundary/docs/concepts/security/data-encryption). + + Refer to the links below for configuration information for the different cloud KMS blocks: + + - [AWS](/boundary/docs/configuration/kms/awskms) + - [Azure](/boundary/docs/configuration/kms/azurekeyvault) + - [GCP](/boundary/docs/configuration/kms/gcpckms) + - [OCI](/boundary/docs/configuration/kms/ocikms) + - [AliCloud](/boundary/docs/configuration/kms/alicloudkms) + - [Vault Transit](/boundary/docs/configuration/kms/transit) + +Refer to the documentation for additional [top-level configuration options](/boundary/docs/configuration) and additional [controller-specific options](/boundary/docs/configuration/controller). + +## Start the Boundary service + +When the configuration files are in place on each Boundary controller, you can proceed to enable and start the binary on each of the Boundary worker nodes using `systemd`. +Run the following commands to start the service: + +1. `sudo systemctl enable boundary` +1. `sudo systemctl start boundary` + +## Adopt the PKI workers (optional) + +If you use the PKI workers as outlined above, you must adopt the Boundary PKI workers. +Complete the following steps to adopt the workers: + + + + + +Complete the following steps to adopt the worker using the UI: + +1. Log in to Boundary as the admin user. + +1. Select **Workers** in the navigation pane. +Note that only KMS workers are listed. + +1. Click **New**. + +1. (Optional) You can use the new PKI workers page to construct the contents of the `pki-worker.hcl` file, if you did not [create the configuration file](/boundary/docs/install-boundary/configure-workers#create-the-worker-configurations) as part of the installation process above. +Provide the following details, and Boundary constructs the worker configuration file for you: + - Boundary Cluster ID + - Worker Public Address + - Config file path + - Worker Tags + +1. Scroll to the bottom of the **New PKI Worker** page, and paste the **Worker Auth Registration Request** key. +Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker. +You can also locate this value in the `auth_request_token` file. + +1. Click **Register Worker**. + +1. Click **Done**. + + The new worker appears on the **Workers** page. + + + + + +Complete the following steps to adopt the worker using the CLI: + +1. Use the following command to ensure that the `BOUNDARY_ADDR` is set as an environment variable: + + ```hcl + $ export BOUNDARY_ADDR="https://c3a7a20a-f663-40f3-a8e3-1b2f69b36254.boundary.hashicorp.cloud" + ``` + +1. Log into the CLI as the admin user, providing the Auth Method ID, admin login +name, and admin password when prompted. + + ```hcl + $ boundary authenticate password \ + -auth-method-id=ampw_KfLAjMS2CG \ + -login-name=admin + ``` + + Example: + + + + ```hcl + $ boundary authenticate password \ + -auth-method-id=ampw_KfLAjMS2CG \ + -login-name=admin + Please enter the password (it will be hidden): + + Authentication information: + Account ID: acctpw_r6crEm0FgM + Auth Method ID: ampw_KfLAjMS2CG + Expiration Time: Mon, 27 Jun 2022 22:03:28 MDT + User ID: u_ysJd0LXX9T + + The token was successfully stored in the chosen keyring and is not displayed here. + ``` + + + +1. Next, use the following command to export the **Worker Auth Request Token** value as an environment variable: + + ```shell-session + $ export WORKER_TOKEN= + ``` + + Boundary provides you with the **Worker Auth Registration Request** key in the CLI output when you start the worker. + You can also locate this value in the `auth_request_token` file. + + The token is used to issue a create worker request that will authorize the worker to Boundary and make it available. + Currently worker creation is only supported for PKI workers with an authorization token. + + + \ No newline at end of file diff --git a/website/content/docs/install-boundary/fault-tolerance.mdx b/website/content/docs/install-boundary/fault-tolerance.mdx new file mode 100644 index 0000000000..b7aef8a779 --- /dev/null +++ b/website/content/docs/install-boundary/fault-tolerance.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: Fault tolerance recommendations +description: |- + Boundary fault tolerance characteristics +--- + +# Fault tolerance recommendations + +Review the following fault tolerance recommendations to ensure increased availability and reduced risk. + +## Node failure + +Boundary controllers store all state and configuration within a PostgreSQL database that must not be deployed on the controller nodes. +When a controller node fails, users are still able to interact with other Boundary controllers, assuming the presence of additional nodes behind a load balancer. + +Boundary workers are used as either proxies or reverse proxies. +Boundary workers routinely communicate with Boundary controllers to report their health. +In the event of a Boundary worker node failure, it is a best practice to have at least three Boundary workers per network boundary, per type (ingress and egress). +Therefore, the controller assigns a user's proxy session to an active Boundary worker node. + +## Availability zone failure + +By deploying Boundary controllers in the recommended architecture across three availability zones with load balancing in front of them, the Boundary control plane can survive outages in up to two availability zones. + +The best practice for deploying Boundary workers is to have at least one worker deployed per availability zone. +In the case of an availability zone outage, if the networking service is still up, users will have their attempted session connection proxied through a worker in a different availability zone and then onto the target, granted the proper security rules are in place to allow for cross subnet/availability zone communication. + +## Regional failures + +Generally speaking, when there is a failure in an entire cloud region, the resources running in that region are most likely inaccessible, especially if the networking service is affected. + +To continue to serve Boundary controller requests in the event of a regional outage, there must be a deployment like the one outlined in this guide in a different region. +The nodes in the secondary region must be able to communicate with the PostgreSQL database, which can be accomplished with multi-regional database technologies from the various cloud providers (for example AWS RDS Read Replicas, where a read replica can be promoted to a primary in the event the primary resides in a failed region). + +Another point of consideration is how to handle load balancing Boundary controller requests to regions that are not in a failed state. +Services like AWS Global Accelerator for AWS, Cross-Region Load Balancer for Azure, and GCP Cloud Load Balancer for GCP all provide this level of functionality with some configuration. + +Refer to your cloud provider's documentation for additional information regarding multi-region disaster recovery strategies for PostgreSQL. + +In the case of a regional outage, if a Boundary worker cannot reach its upstream worker, cannot reach a controller, a user cannot reach the worker, or any combination of the above, the user is not able to establish a proxied session to the target. diff --git a/website/content/docs/install-boundary/index.mdx b/website/content/docs/install-boundary/index.mdx index edfa87db9d..0d54f5a2de 100644 --- a/website/content/docs/install-boundary/index.mdx +++ b/website/content/docs/install-boundary/index.mdx @@ -1,14 +1,14 @@ --- layout: docs -page_title: Installing Boundary +page_title: Overview description: |- - How to install boundary. + Deploying a self-managed version of Boundary --- # Overview -This section covers installing Boundary for different modes of operation and across different environments +This section details installing Boundary in a self-managed environment. +You can use the topics in this section to install the open source version or the Enterprise version of Boundary. +The section also includes reference architecture, system requirement recommendations, and best practices. -For community-supported reference architectures, please see [Reference Architectures](/boundary/docs/oss/installing/reference-architectures). - -![Boundary Architecture](/img/architecture-overview.png) \ No newline at end of file +To deploy HCP Boundary instead, refer to the [HCP Boundary Get Started section](/hcp/docs/get-started/deploy-and-login). \ No newline at end of file diff --git a/website/content/docs/install-boundary/install.mdx b/website/content/docs/install-boundary/install.mdx new file mode 100644 index 0000000000..400e489031 --- /dev/null +++ b/website/content/docs/install-boundary/install.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: Install Boundary +description: |- + Install a self-managed version of Boundary +--- + +# Install Boundary + +This guide outlines the required steps to manually install and configure a single HashiCorp Boundary cluster as defined in the [Recommended architecture](/boundary/docs/install-boundary/recommended-architecture) topic. +It assumes you install Boundary on virtual machines (VMs) or bare-metal servers running a Debian or Red Hat-based Linux distribution. + +This document includes general guidance as well as specific recommendations for popular cloud infrastructure platforms. +These recommendations have also been encoded into official Terraform reference architectures for [AWS](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/aws), [Azure](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/azure), and [GCP](https://github.com/hashicorp/boundary-reference-architecture/tree/main/deployment/gcp). + +Pre-built Boundary packages are available from the [HashiCorp Linux Repository](https://www.hashicorp.com/blog/announcing-the-hashicorp-linux-repository). +In addition to installing the Boundary binary, the official package also provides a systemd service unit, and a local `boundary` user account under which the service runs. + +You must complete the following steps for each Boundary controller and worker node that you want to deploy. +The binary operates as either a worker or controller, depending on the subsequent configuration that you generate for the Boundary binary. + +The steps vary by Linux distribution. +Select your distribution, and complete the steps to install Boundary. + + + + +1. Use the following command to add the HashiCorp GPC key as a trusted package-signing key: + + ```shell-session + $ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add - + ``` +1. Add the official HashiCorp Linux repository: + + ```shell-session + $ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main" + ``` + +1. Update the package index: + + ```shell-session + $ sudo apt update + ``` + +1. Install Boundary: + + ```shell-session + $ sudo apt install boundary + ``` + + + + +1. Use the following command to install `yum-config-manager` to manage your repositories: + + ```shell-session + $ sudo yum install -y yum-utils + ``` + +2. Add the official HashiCorp Linux repository: + + ```shell-session + $ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo + ``` + +3. Install Boundary: + + ```shell-session + $ sudo yum -y install boundary-enterprise + ``` + + + \ No newline at end of file diff --git a/website/content/docs/install-boundary/postgres.mdx b/website/content/docs/install-boundary/postgres.mdx deleted file mode 100644 index 662def1203..0000000000 --- a/website/content/docs/install-boundary/postgres.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: docs -page_title: Postgres Installation -description: |- - Postgres configuration for Boundary ---- - -# Postgres Configuration - -This section covers Postgres-specific installation requirements. - -## Version - -Boundary has only been tested on Postgres 11 or greater. - -## Network - -Boundary controllers must be able to reach Postgres. -In non-HA configurations, this means Boundary servers; -if you're running in [high availability](/boundary/docs/oss/installing/high-availability), -then the controllers need access to the Postgres server infrastructure. -Worker nodes never need access to the database. - -## Users/Roles - -After the database has been initialized, -the database user for a Boundary controller -only requires permissions for [Data Manipulation](https://www.postgresql.org/docs/current/dml.html) -(select, insert, update, and delete) operations. - -Database initialization requires elevated privileges. -When initializing the database with the `boundary database init` command, -the boundary database user -requires the `superuser` role plus `all privileges` on the boundary database. - -## Required Postgres Modules - -Boundary has a dependency on the Postgres -[pgcrypto](https://www.postgresql.org/docs/11/pgcrypto.html) module -which is one of the standard modules supplied with Postgres. -Please see the -[Additional Supplied Modules](https://www.postgresql.org/docs/11/contrib.html) -page in the Postgres documentation for more information. diff --git a/website/content/docs/install-boundary/recommended-architecture.mdx b/website/content/docs/install-boundary/recommended-architecture.mdx new file mode 100644 index 0000000000..138c5c41b6 --- /dev/null +++ b/website/content/docs/install-boundary/recommended-architecture.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: Recommended architecture +description: |- + Boundary architecture recommendations +--- + +# Recommended architecture + +Boundary has two main user workflows to consider when you deploy it to production. + +## Administrative workflow + +The first is the Boundary administration workflow, where an administrator uses either the Boundary CI or GUI to configure Boundary. +In this scenario, the administrator interfaces solely with the Boundary controllers, and a load balancer can be used to balance requests across multiple controllers. +The Boundary controllers do not directly communicate with one another, all configuration and state is managed through an RDBMS, in this case PostgreSQL. + +The following diagram shows the recommended architecture for deploying Boundary controller nodes within a single region: + +![Single region deployment](/img/single-region.png) + +Boundary controllers are stateless and do not operate using consensus protocols such as Raft. +They are therefore able to withstand failure scenarios where only one node is accessible. + +If deploying Boundary to three availability zones is not possible, you can use the same architecture across one or two availability zones, at the expense of reliability risk in case of an availability zone outage. + +## Connect to a target workflow + +The second workflow is a user connecting to a Boundary target. +In this scenario, the user initiates a session connecting to a target they have been granted access to using either the Boundary CLI or desktop application. + +1. If the user is not authenticated, they must first authenticate by communicating with the Boundary controllers and any relied-upon OIDC IdP, if necessary. +1. Once authenticated, the user's session can be initiated and a tunnel is built from their client to an ingress worker. +If there are multiple layers of network boundaries, a tunnel is built from the ingress worker to an egress worker. +1. The last step is traffic being proxied through the egress worker to the target. + +It is ideal to have multiple ingress and egress workers with the same configurations within each network boundary to provide high availability. +Load balancing the Boundary workers is not recommended, as the Boundary control plane handles session scaling and balancing when users start sessions. + +The following diagram shows the recommended architecture for deploying Boundary workers: + +![Worker deployment](/img/worker-deployment.png) + +The Boundary controllers also depend on a PostgreSQL database. +This database should be deployed in a fashion where it is reachable by all Boundary controller nodes. + +## Community reference architectures + +A number of community-supported reference architectures for non-dev deployments can be found in Boundary's dedicated [reference architecture repo](https://github.com/hashicorp/boundary-reference-architecture). + +While some initial reference deployments have been seeded by the Boundary team, the seeded examples are for demonstration purposes only and are intended convey how to get Boundary up and running on popular cloud and container platforms. + +We highly encourage organizations who use Boundary in production environments to contribute configurations to the repo so that the community may benefit from them. diff --git a/website/content/docs/install-boundary/reference-architectures.mdx b/website/content/docs/install-boundary/reference-architectures.mdx deleted file mode 100644 index 5a68b3c232..0000000000 --- a/website/content/docs/install-boundary/reference-architectures.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: docs -page_title: Reference Architectures -description: |- - Boundary reference architectures ---- - -# Reference Architectures -A number of community-supported reference architectures for non-dev deployments can be found in Boundary's dedicated [reference architecture repo](https://github.com/hashicorp/boundary-reference-architecture). - - -While some of the initial reference deployments have been seeded by the Boundary team, the seeded examples are for demonstration purposes only and intended convey how to get Boundary up and running on popular cloud and container platforms. - -For those exploring Boundary in non-dev mode, we highly encourage contributing configurations to the repo such that others may benefit from them. diff --git a/website/content/docs/install-boundary/system-requirements.mdx b/website/content/docs/install-boundary/system-requirements.mdx new file mode 100644 index 0000000000..5633c0d4cf --- /dev/null +++ b/website/content/docs/install-boundary/system-requirements.mdx @@ -0,0 +1,172 @@ +--- +layout: docs +page_title: System requirements +description: |- + Boundary system requirements +--- + +# System requirements + +This topic contains specific recommendations for system requirements. +Since every hosting environment is different, and every customer's Boundary usage profile is different, the following recommendations should only serve as a starting point from which your operations staff may observe and adjust to meet the unique needs of each deployment. + +To match your requirements and maximize the stability of your Boundary controller and worker instances, it's important to ensure that you perform load tests and continue to monitor resource usage as well as all reported matrices from Boundary's telemetry. + +Refer to [Maintaining and operating Boundary](/boundary/docs/operations) for more information. + + +All specifications outlined in this topic are minimum recommendations without any reservations towards vertical scaling, redundancy, or other site reliability needs, and without an understanding of your user volumes or their use cases in all scenarios. +All resource requirements are directly proportional to the operations being performed by the Boundary cluster, as well as the end users' level of usage. + + +## Hardware sizing for Boundary servers + +Refer to the tables below for sizing recommendations for controller nodes and worker nodes, as well as small and large use cases based on expected usage. + +Controller nodes + +| Size | CPU | Memory | Disk capacity | Network throughput | +|---|---|---|---|---| +| Small | 2 - 4 core | 8 - 16 GB RAM | 50+ GB | Minimum 5 Gbps | +| Large | 4 - 8 core | 32 - 64 GB RAM | 100+ GB | Minimum 10 Gbps | + +Worker nodes + +| Size | CPU | Memory | Disk capacity | Network throughput | +|---|---|---|---|---| +| Small | 2 - 4 core | 8 - 16 GB RAM | 50+ GB | Minimum 10 Gbps | +| Large | 4 - 8 core | 32 - 64 GB RAM | 100+ GB | Minimum 10 Gbps | + +For each cluster size, the following table gives recommended hardware specifications for each major cloud infrastructure provider. + +| Provider | Size | Instance/VM types | +|---|---|---| +| AWS | Small | m5.large , m5.xlarge | +| AWS | Large | m5.2xlarge , m5.4xlarge | +| Azure | Small | Standard_D2s_v3 , Standard_D4s_v3 | +| Azure | Large | Standard_D8s_v3 , Standard_D16s_v3 | +| GCP | Small | n2-standard-2 , n2-standard-4 | +| GCP | Large | n2-standard-8 , n2-standard-16 | + +To help ensure predictable performance on cloud providers, we recommend that you avoid "burstable" CPU and storage options (such as AWS `t2` and `t3` instance types) whose performance may degrade rapidly under continuous load. + +## Hardware considerations + +The Boundary controller and worker nodes perform two very different tasks. +The Boundary controller nodes handle requests for authentication and configuration, among other tasks. +The Boundary worker nodes are used to proxy client connections to Boundary targets and thus may require additional resources. + +Depending on the number of clients connecting to Boundary targets at any given time, Boundary workers could become memory or file descriptor constrained. +As new sessions are created on the Boundary worker node, additional sockets and ultimately file descriptors are created. +It is imperative to monitor both the file descriptor usage and the memory consumption of each Boundary worker node. + +## Network considerations + +The amount of network bandwidth used by the Boundary controllers and workers depends on your specific usage patterns. +With regards to Boundary controllers, even a high request volume does not necessarily translate to a large amount of network bandwidth consumption. +However, Boundary worker nodes proxy client sessions to Boundary targets, so the bandwidth consumption is highly dependent on the amount of potential clients, the number of sessions being created, and the amount of data being transferred in either direction to and from the Boundary targets. + +It is also important to consider bandwidth requirements to other external systems such as monitoring and logging collectors. +It is imperative to monitor the networking metrics of the Boundary workers, to avoid situations where the Boundary workers can no longer initiate session connections. + +It may be necessary to increase the size of the virtual machine to take advantage of additional throughput in certain circumstances. + +Refer to the following pages for provider-specific virtual machine networking limitations: + +- [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html) +- [Azure](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-machine-network-throughput/) +- [GCP](https://cloud.google.com/compute/docs/network-bandwidth/) + +## Network connectivity + +The following table outlines the default ingress network connectivity requirements for Boundary cluster nodes. +If general network egress is restricted, you must pay particular attention to granting outgoing access from: + +- The Boundary controllers to any external integration providers (for example, OIDC authentication providers) as well as external log handlers, metrics collection, and security and configuration management providers. +- The Boundary workers to controllers and any upstream workers. + + + +If any of the default port mappings below do not meet your organization's requirements, you can update the default listening ports using the resource's [listener](/boundary/docs/configuration/listener) stanza. + + + + ![Boundary network](/img/boundary-network.png) + +| Source | Destination | Default destination port | protocol | Purpose | +| --------------- | --------------------------- | ------------------------ | --------- | -------------------------------------- | +| Client machines | Controller load balancer | 443 | tcp | Request distribution | +| Load balancer | Controller servers | 9200 | tcp | Boundary API | +| Load balancer | Controller servers | 9203 | tcp | Health checks | +| Worker servers | Controller load balancer | 9201 | tcp | Session authorization, credentials, etc | +| Controllers | Postgres | 5432 | tcp | Storing system state | +| Client machines | Worker servers \* | 9202 | tcp | Session proxing | +| Worker servers | Boundary targets\* | various | tcp | Session proxing | +| Client machines | Ingress worker servers \*\* | 9202 | tcp | Multi-hop session proxing | +| Egress workers | Ingress worker servers \*\* | 9202 | tcp | Multi-hop session proxing | +| Egress workers | Boundary targets \*\* | various | tcp | Multi-hop session proxing | + +\* In this scenario, the client connects directly to one worker, which then proxies the connection to the Boundary target. + +** In this scenario, the client connects to an ingress worker, then the ingress worker connects to a downstream egress worker, then the downstream egress worker connects to the Boundary target. +Ingress and egress workers can be chained together further to provide multiple layers of session proxying. + +## Network traffic encryption + +You should encrypt connections to the Boundary control plane at the controller nodes using standard PKI HTTPS TLS. +This also means that you can use a simple layer 4 load balancer to pass through traffic to the Boundary controllers, or a layer 7 load balancer with no configured TLS termination. + +## Database recommendations + +Boundary clusters depend on a PostgreSQL database for managing state and configuration. +Boundary has only been tested on PostgreSQL 11 or greater. + +Each major cloud provider offers a managed PostgreSQL database service: + +| Cloud provider | Managed database service | +|---|---| +| AWS | [Amazon RDS for PostgreSQL](https://aws.amazon.com/rds/postgresql/) | +| Azure | [Azure database for PostgreSQL](https://azure.microsoft.com/en-us/products/postgresql/) | +| GCP | [Cloud SQL for PostgreSQL](https://cloud.google.com/sql/postgresql) | + +### Database network requirements + +Boundary controllers must be able to reach the PostgreSQL database. +If you use a [high availability](/boundary/docs/install-boundary/high-availability) (HA) configuration, then the controllers must have access to the PostgreSQL server infrastructure. +In non-HA configurations, the Boundary servers must have access. +Worker nodes never need access to the database. + +### Database users and roles + +After the database has been initialized, the database user for a Boundary controller requires only permissions for [data manipulation](https://www.postgresql.org/docs/current/dml.html) operations (select, insert, update, and delete). + +Database initialization requires elevated privileges. +When you initialize the database with the `boundary database init` command, the Boundary database user requires the `superuser` role plus `all privileges` on the Boundary database. + +### Required PostgreSQL modules + +Boundary has a dependency on the PostgreSQL [pgcrypto](https://www.postgresql.org/docs/11/pgcrypto.html) module, which is one of the standard modules that is supplied with PostgreSQL. +Refer to the PostgreSQL documentation for more information. + +## Load balancer recommendations + +For the highest levels of reliability and stability, we recommend that you use some load balancing technology to distribute requests to your Boundary controller nodes. +Each major cloud platform provides good options for managed load balancer services. +There are also a number of self-hosted options, as well as service discovery systems like Consul. + +To monitor the health of Boundary controller nodes, you should configure the load balancer to poll the `/health` API endpoint to detect the status of the node and direct traffic accordingly. + +Refer to the [listener stanza documentation](/boundary/docs/configuration/listener/) for more information. + +Each major cloud provider offers one or more managed load balancing services: + +| Cloud | Layer | Managing load balancing service | +|---|---|---| +| AWS | Network | 4 | [Network load balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) | +| AWS | Application | 7 | [Application load balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) | +| Azure | Network | 4 | [Azure load balancer](https://learn.microsoft.com/en-us/azure/load-balancer/) | +| Azure | Application | 7 | [Azure application gateway](https://learn.microsoft.com/en-us/azure/application-gateway/) | +| GCP | Network/Application | 4/7 | [Cloud load balancing](https://cloud.google.com/load-balancing/docs/load-balancing-overview) | + +Boundary workers do not require any load balancing. +Load balancing for the Boundary workers is handled by the Boundary controllers when clients initiate sessions to Boundary targets. \ No newline at end of file diff --git a/website/content/docs/operations/manage-recorded-sessions.mdx b/website/content/docs/operations/manage-recorded-sessions.mdx new file mode 100644 index 0000000000..7770527a34 --- /dev/null +++ b/website/content/docs/operations/manage-recorded-sessions.mdx @@ -0,0 +1,80 @@ +--- +layout: docs +page_title: Manage recorded sessions +description: |- + How to download, view, and validate Boundary's recorded sessions +--- + +# Manage recorded sessions + +Boundary provides [auditing](/boundary/docs/concepts/auditing) capabilities via [session recording](/boundary/docs/configuration/session-recording). +In Boundary, a session represents a set of connections between a user and a host from a target. +The session begins when an authorized user requests access to a target, and it ends when that access is terminated. +When you enable session recording on a target, any user session that connects to the target is automatically recorded. +An administrator can later view the recordings to investigate security issues, review system activity, or perform regular assessments of security policies and procedures. + +## Find recorded sessions + +Recorded sessions are stored in an external storage bucket that you create. +Storing session recordings in a system external to Boundary means those recordings can be accessed, modified, deleted, and even restored independently of Boundary. +You can view any sessions that Boundary recorded in your storage provider or via the CLI. + +You can view a list of all recorded sessions, or if you know the ID of a specific recorded session, you can find any channels associated with that recording. + +### Find all recorded sessions + +Complete the following steps to find all recorded sessions using the CLI. + +1. Authenticate to Boundary in the CLI. +1. Type the following command to view a list of all recorded sessions: + + ```bash + boundary session-recordings list -recursive + ``` + + Boundary displays a list of all recorded sessions by scope. + +### Find a specific recorded session by ID + +If you have the ID of a recorded session, you can use the following command to list the connections and channels associated with a session recording. + +```bash +boundary session-recordings read -id +``` + +## View recorded sessions + +You can view recorded sessions in the UI, if you have the proper permissions. + +1. Log in to Boundary. +1. Select **Orgs** in the navigation pane. +1. Select the org that contains the target from the recorded session you want to view. +1. Select **Session Recordings** in the navigation pane. + + The **Session Recordings** page displays the time, user, target, and duration of the recording. +1. Select **View** next to the recording you want to view. +1. Select **Play** next to the channel recording you want to view. + + The recorded session appears in the media plyaer. + You can click the **Play** button to watch the recording. + +## Download recorded session channels + +You can download a recording of SSH shell or exec sessions for a channel from a recorded session. +The channel ID is required for the download. + +If you have the ID of a recorded session, you can use the following command to list the connections and channels associated with a session recording. + +```bash +boundary session-recordings read -id +``` + +Complete the following steps to download a recorded session channel: + +1. Authenticate to Boundary in the CLI. +1. Type the following command to download a recorded session channel. +Substitute the ID of the channel for **chr_1234567890**: + + ```bash + boundary session-recordings download -id chr_1234567890 + ``` diff --git a/website/content/docs/overview/use-cases.mdx b/website/content/docs/overview/use-cases.mdx index 08898a0c41..c85a6b925d 100644 --- a/website/content/docs/overview/use-cases.mdx +++ b/website/content/docs/overview/use-cases.mdx @@ -4,25 +4,29 @@ page_title: Use Cases description: A list of Boundary use cases --- -# Use Cases +# Use cases Before understanding use cases, it's useful to know [what Boundary is](/boundary/docs/overview/what-is-boundary). This page lists some concrete use cases for Boundary, but the possible use cases are much broader than what we cover. -## Zero Trust access +## Zero trust access Boundary’s access-on-demand workflow securely connects trusted identities to infrastructure services based on granular, admin-defined permission grants. Boundary removes the need to create or store credentials when accessing services. In this way, Boundary can be used to extend or replace many traditional access solutions like VPNs. Traditional access solutions do not employ the Zero-Trust philosophy - meaning they fail to authenticate and authorize users’ access and actions continuously, and often lack granular access controls. -## Multi-Cloud Access +## Multi-cloud access Having different access workflows for various infrastructure and identity providers doesn’t scale well for administrators or users. Multi-cloud organizations have a growing need to standardize access through a single workflow. Boundary creates a centralized layer of identity-based authentication and authorization to manage access to the infrastructure, regardless of the platform on which it resides. -## Single Sign-on with Integrated Secrets Management +## Single sign-on with integrated secrets management Boundary enables a single sign-on access model with authentication from trusted identity providers, such as Azure Active Directory, Auth0, and Okta. Once authenticated, users may create sessions with integrated credential management from HashiCorp Vault without the need to re-authenticate. -## Session Monitoring +## Session monitoring Boundary provides session monitoring capabilities that give security administrators visibility into user access. Sessions are logged and consumable via the Boundary administrator UI as well as business intelligence (BI) and security information and event management (SIEM) tools. + +Further, administrators can enable session recording on targets. +When you enable session recording on a target, a worker records any sessions that access that target from the time the user requests access to when that access is terminated. +Administrators can view the recordings later using a session player that runs in a browser. \ No newline at end of file diff --git a/website/content/docs/overview/what-is-boundary.mdx b/website/content/docs/overview/what-is-boundary.mdx index 6eef75d94b..239d7f08f6 100644 --- a/website/content/docs/overview/what-is-boundary.mdx +++ b/website/content/docs/overview/what-is-boundary.mdx @@ -25,7 +25,16 @@ Boundary's foundation is based on the following important concepts. ## How does Boundary work? -Boundary provides secure access to hosts and critical systems without distributing and managing credentials, configuring firewalls, or exposing the organization's private network. Traditionally, for users to access their resources, it's required that organizations establish and maintain SSH bastion hosts and VPNs. The illustration below displays Boundary's core workflow. +Boundary provides secure access to hosts and critical systems without distributing and managing credentials, configuring firewalls, or exposing the organization's private network. Traditionally, for users to access their resources, it's required that organizations establish and maintain SSH bastion hosts and VPNs. + +The video below provides an overview of the Boundary architecture, components, and deployment models. +It also gives a brief walkthrough of the end user's experience. + + + +The illustration below displays Boundary's core workflow. ![Boundary core workflow](/img/boundary-core-workflow.png) @@ -48,7 +57,7 @@ role-based access for dynamic infrastructure. The key features and concepts of Boundary include: -### Identity & Permission Management +### Identity & permission management Identity is a core concept in Boundary. Identity is represented by two types of resources, mapping to common security principals: @@ -62,7 +71,7 @@ resources, mapping to common security principals: [grants](/boundary/docs/concepts/security/permissions), which provides the ability to perform actions within the system. -### Resource Management +### Resource management Boundary enables flexible management of the hosts and services to broker access. Boundary administrators define [host @@ -74,6 +83,15 @@ together host sets with connection information. Access to a resource is granted via [roles](/boundary/docs/concepts/domain-model/roles) that provide authorization to create sessions against these targets. +### Auditing + +A fundamental challenge of securing access to sensitive computing resources is creating a system of record around users' access and actions over remote sessions. +Boundary provides [auditing](/boundary/docs/concepts/auditing) features via [session recording](/boundary/docs/configuration/session-recording) to help organizations address compliance and threat management needs. + +When [session recording](/boundary/docs/configuration/session-recording) is enabled on a target, any sessions established to that target are recorded. +Recorded sessions are stored in an admin-specified storage backend. +Administrators can access recorded sessions at a later time using a session player that runs in a browser. + ### Filtering Parts of Boundary support filters for various purposes. For a description @@ -85,7 +103,13 @@ supported for the specific inputs and examples with those inputs. ## What is HCP Boundary? -Boundary offers two types of deployment options. A first option is an *OSS self-managed* deployment solution as discussed above. A self-managed approach enables organizations to proxy all session data through their own network while still providing the convenience of a managed service. A second option is an *HCP-managed* deployment solution where both the control plan and worker nodes are managed by HashiCorp. With this managed solution, an option of private workers is offered. **HCP Boundary** is a fully-managed, cloud-based workflow that enables secure connections to remote hosts and critical systems across cloud and on-premise environments. Refer to the [HCP Boundary](/hcp/docs/boundary) documentation to learn more. +Boundary offers three types of deployment options. +The first two options are self-managed deployments. +A self-managed approach enables organizations to proxy all session data through their own networks, while still providing the convenience of a managed service. +HashiCorp offers Boundary in both open source (OSS) and enterprise self-managed versions. +The Enterprise version contains commercial-only features, and comes with support. + +The third option is an *HCP-managed* deployment solution where both the control plane and worker nodes are managed by HashiCorp. With this managed solution, an option of private workers is offered. **HCP Boundary** is a fully-managed, cloud-based workflow that enables secure connections to remote hosts and critical systems across cloud and on-premise environments. Refer to the [HCP Boundary](/hcp/docs/boundary) documentation to learn more. -> **Hands On:** Try the [Create a Boundary Instance on HCP](/boundary/tutorials/hcp-getting-started/hcp-getting-started-create) tutorial to deploy an HCP Boundary instance. diff --git a/website/content/docs/release-notes/v0_12_0.mdx b/website/content/docs/release-notes/v0_12_0.mdx index f0264e9692..423f6faf9e 100644 --- a/website/content/docs/release-notes/v0_12_0.mdx +++ b/website/content/docs/release-notes/v0_12_0.mdx @@ -13,13 +13,6 @@ To learn about what Boundary consists of, we highly recommend you review the [Ge For instructions on how to upgrade an existing Boundary deployment to v0.12.0, refer to Boundary's [general upgrade guide](/boundary/tutorials/oss-configuration/upgrade-version). - - - Boundary OSS v0.12.0 will be available to customers before HCP Boundary is. - HCP Boundary v0.12.0 specific features will be available shortly. - - - ## Boundary v0.12.0 highlights The 0.12.0 release adds major new functionality to Boundary. diff --git a/website/content/docs/release-notes/v0_13_0.mdx b/website/content/docs/release-notes/v0_13_0.mdx new file mode 100644 index 0000000000..a9cf455085 --- /dev/null +++ b/website/content/docs/release-notes/v0_13_0.mdx @@ -0,0 +1,131 @@ +--- +layout: docs +page_title: v0.13.0 +description: |- + Boundary release notes for v0.13.0 +--- + +# Boundary v0.13.0 + +The release notes below contain information about new functionality available in the Boundary v0.13.0 release. +To see a granular record of when each item was merged into the Boundary project, please refer to the [Changelog](https://github.com/hashicorp/boundary/blob/main/CHANGELOG.md). +To learn about what Boundary consists of, we highly recommend you review the [Getting Started Page](/boundary/docs/getting-started). + +For instructions on how to upgrade an existing Boundary deployment to v0.13.0, refer to Boundary's [general upgrade guide](/boundary/tutorials/oss-configuration/upgrade-version). + +## Boundary v0.13.0 highlights + +The 0.13.0 release adds major new functionality to Boundary. +Highlights include: + +- Boundary Enterprise version +- SSH session recording +- LDAP authentication method (beta) +- HCP Boundary maintenance window +- OIDC authentication improvements +- Shared KMS workers +- Static ports for targets +- Dynamic host catalog external name + +## New features + +**Boundary Enterprise**: Organizations are now able to deploy Boundary Enterprise within their self-managed infrastructure to let their teams securely access hosts and services consistently across any environment. +The introduction of Boundary Enterprise allows organizations in highly regulated industries who are prohibited from adopting cloud based solutions to leverage Boundary's secure remote access functionalities. +Boundary Enterprise has the same feature set as HCP Boundary and seamless migrations from OSS deployments are supported as well. + +For more information, refer to [Boundary Enterprise](/boundary/docs/enterprise). + +**SSH session recording HCP/ENT**: A fundamental challenge of securing access to sensitive computing resources is creating a system of record around users' access and actions over remote sessions. +This release introduces session recording to help you address your compliance and threat management needs. + +When you enable session recording for a target, any sessions in which a user requests access to that target are recorded. +Recorded sessions are stored in an external data store so that you can access and manage them outside of Boundary for long-lasting data retention. +You can view recorded sessions using a session player that runs in a browser. + +For more information, refer to [Auditing](/boundary/docs/concepts/auditing). +To configure session recording for targets, refer to the session recording [overview](/boundary/docs/configuration/session-recording). + +**LDAP authentication method Beta**: This release introduces a new Lightweight Directory Access Protocol (LDAP) authentication method as a preview feature. +LDAP is an open, vendor-neutral application protocol for accessing and maintaining directory information. + +You can now configure Boundary to delegate authentication to an LDAP directory. +The first time a user successfully authenticates using an LDAP auth method, a new LDAP account is created. +LDAP-managed groups let you assign roles in Boundary based on the LDAP account's group memberships. + +Create, read, update, and delete (CRUD) support for the new LDAP features is available through the CLI, API, and SDK, as well as HashiCorp Terraform. +You can use LDAP to log in through any of the Boundary clients, including the CLI, Boundary Desktop, and the Boundary admin UI. +Support for LDAP CRUD operations via the Boundary admin UI is planned for an upcoming release. + +For more information, refer to the LDAP domain model documentation: + +- [Accounts](/boundary/docs/concepts/domain-model/accounts#ldap-account-attributes-beta) +- [Auth methods](/boundary/docs/concepts/domain-model/auth-methods#ldap-auth-method-attributes-beta) +- [Managed groups](/boundary/docs/concepts/domain-model/managed-groups#ldap-managed-group-information-and-attributes-beta) + +**HCP Boundary maintenance window HCP only**: HCP Boundary automatically updates your environment when a new version of Boundary is released. +You can now schedule when that maintenance occurs to ensure that it does not interrupt peak work hours. +When you schedule a maintenance window, HCP Boundary waits util the day and time window you selected to apply any patch or major version updates. + +For more information, refer to [Maintenance windows](/hcp/docs/boundary/maintenance-window). + +**OIDC authentication improvements**: The Boundary CLI now supports user authentication against an OIDC source in locked down environments where a browser may not be available to complete the auth flow. +During authentication, the CLI will output the auth URL which can be used to complete the flow on another device and the resulting token is automatically passed to the CLI. + +**Shared KMS workers**: KMS workers now have feature parity with PKI workers. +You can use more than one KMS for registering downstreams across different networks. + +For more information, refer to the [worker configuration](/boundary/docs/configuration/worker) documentation. + +**Static ports for targets**: Administrators can now configure a default, static port for clients when connecting to targets using the optional `default_client_port` attribute. +Any workers that connect to a target will use the default port, if one is specified, unless overidden by the client attribute `-listen-port`. + +**Dynamic host catalog external name**: You can now view the AWS or Azure host name when listing hosts in CLI, admin console, and desktop client. + +## Deprecations and changes + +Boundary version 0.13.0 has the following deprecations and changes: + +- Due to the update to KMS workers, the previous KMS worker registration method is deprecated. +You must opt in to use it. +You should only use the deprecated behavior if compatibility with workers running a version less than 0.13.0 is required. +To opt in, add `use_deprecated_kms_auth_method = true` to the `worker` configuration block. + + Note that when a worker using KMS and running version 0.13.0 or later connects to a controller using KMS and running version 0.13.0 or later, they transition to the new method automatically. + To revert to the previous method after that, you must delete the worker and recreate it with the `use_deprecated_kms_auth_method` field specified. + +- Boundary now performs additional validity checking when you add grants to roles. +The checks are designed to reject grants that are not properly configured. +Previously, these would have been accepted without error, but the permissions would not be granted. +An error message is provided now, with hints for resolution. + +- `WithAutomaticVersioning` for auth tokens from the Go SDK was incorrectly being generated for auth token resources, which do not support versioning. +It has now been removed. + +- With the introduction of new plugin services, the Azure and AWS Host plugin repositories have been renamed to drop the word `host`: + + - The https://github.com/hashicorp/boundary-plugin-host-aws repository was renamed to https://github.com/hashicorp/boundary-plugin-aws. + + - The https://github.com/hashicorp/boundary-plugin-host-azure repository was renamed to https://github.com/hashicorp/boundary-plugin-azure. + +- PostgreSQL 12 or greater is now required. +PostgreSQL 11 is no longer supported. + +## Known issues + +**Rotation of AWS access and secret keys during a session results in stale recordings**: In Boundary version 0.13.0, when you rotate a storage bucket's secrets, any new sessions use the new credentials. +However, previously established sessions continue to use the old credentials. + +As a best practice, administrators should rotate credentials in a phased manner, ensuring that all previously established sessions are completed before revoking the stale credentials. +Otherwise, you may end up with recordings that aren't stored in the remote storage bucket and are unable to be played back. + +**Unsupported recovery workflow during worker failure**: If a worker fails during a recording, there is no way to recover the recording. +This could happen due to a network connectivity issue or because a worker is scaled down, for example. +There are a number of currently unsupported failure cases, including when the worker: + +- Crashes and restarts while servicing connections and channels for session to an SSH target +- Crashes and restarts while closing a channel, before all files are synced to remote storage +- Crashes and restarts while closing a connection recorder, before all files are synced to remote storage +- Crashes and restarts while closing a session recorder, before all files are synced to remote storage +- Crashes and never restarts or is seen again while closing a channel/connection recorer/session recorder +- Loses its connection to the controller and cancels sessions, it must resend the information when communication resumes +- Crashes during recovery \ No newline at end of file diff --git a/website/content/docs/troubleshoot/troubleshoot-recorded-sessions.mdx b/website/content/docs/troubleshoot/troubleshoot-recorded-sessions.mdx new file mode 100644 index 0000000000..45e57066c6 --- /dev/null +++ b/website/content/docs/troubleshoot/troubleshoot-recorded-sessions.mdx @@ -0,0 +1,24 @@ +--- +layout: docs +page_title: Manage recorded sessions +description: |- + How to troubleshoot issues with Boundary's recorded sessions +--- + +# Troubleshoot session recordings + +Refer to the following for information about how to troubleshoot recorded sessions. + +## Known bugs + +**Rotation of AWS access and secret keys during a session results in stale recordings** + +In Boundary version 0.13.0, when you rotate a storage bucket's secrets, any new sessions use the new credentials. +However, previously established sessions continue to use the old credentials. + +As a best practice, administrators should rotate credentials in a phased manner, ensuring that all previously established sessions are completed before revoking the stale credentials. +Otherwise, you may end up with recordings that aren't stored in the remote storage bucket and are unable to be played back. + +## Tips + +When you create or update a storage bucket, the actions `GetBucketAcl` and `GetEncryptionConfiguration` can be helpful in debugging access issues. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 3d2a0a703a..9058c7a25f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -53,18 +53,18 @@ "path": "getting-started" }, { - "title": "Self-managed Boundary quick start", + "title": "Self-Managed Boundary Quick Start", "href": "https://developer.hashicorp.com/boundary/tutorials/oss-getting-started/" }, { - "title": "HCP Boundary quick start", + "title": "HCP Boundary Quick Start", "href": "https://developer.hashicorp.com/boundary/tutorials/hcp-getting-started/" }, { - "title": "Dev Mode quick start", + "title": "Dev Mode Quick Start", "routes": [ { - "title": "What is Dev Mode", + "title": "Overview", "path": "getting-started/dev-mode/dev-mode" }, { @@ -86,25 +86,42 @@ "title": "Overview", "path": "install-boundary" }, + { + "title": "Recommended Architecture", + "path": "install-boundary/recommended-architecture" + }, + { + "title": "System Requirements", + "path": "install-boundary/system-requirements" + }, + { + "title": "Fault Tolerance Recommendations", + "path": "install-boundary/fault-tolerance" + }, + { + "title": "Install Boundary", + "path": "install-boundary/install" + }, + { + "title": "Configure Controllers", + "path": "install-boundary/configure-controllers" + }, + { + "title": "Configure Workers", + "path": "install-boundary/configure-workers" + }, { "title": "Non-Dev Environments", "path": "install-boundary/no-gen-resources" }, { "title": "Systemd Install", + "hidden": true, "path": "install-boundary/systemd" }, { - "title": "Postgres Install", - "path": "install-boundary/postgres" - }, - { - "title": "High Availability Install", + "title": "Configure High Availability", "path": "install-boundary/high-availability" - }, - { - "title": "Reference Architectures", - "path": "install-boundary/reference-architectures" } ] }, @@ -127,6 +144,10 @@ "title": "Credential Management", "path": "concepts/credential-management" }, + { + "title": "Auditing", + "path": "concepts/auditing" + }, { "title": "Security", "routes": [ @@ -142,12 +163,12 @@ "path": "concepts/security/permissions" }, { - "title": "Grant Strings", - "path": "concepts/security/permissions/grants" + "title": "Assignable Permissions", + "path": "concepts/security/permissions/assignable-permissions" }, { - "title": "Advanced Concepts", - "path": "concepts/security/permissions/advanced" + "title": "Permission Grant Formats", + "path": "concepts/security/permissions/permission-grant-formats" }, { "title": "Resource Table", @@ -224,6 +245,14 @@ "title": "Session Connections", "path": "concepts/domain-model/session-connections" }, + { + "title": "Session Recordings", + "path": "concepts/domain-model/session-recordings" + }, + { + "title": "Storage Buckets", + "path": "concepts/domain-model/storage-buckets" + }, { "title": "Targets", "path": "concepts/domain-model/targets" @@ -273,7 +302,7 @@ "path": "configuration" }, { - "title": "worker", + "title": "Worker", "routes": [ { "title": "Overview", @@ -290,7 +319,7 @@ ] }, { - "title": "listener", + "title": "Listener", "routes": [ { "title": "Overview", @@ -344,7 +373,24 @@ ] }, { - "title": "events", + "title": "Session Recordings", + "routes": [ + { + "title": "Overview", + "path": "configuration/session-recording" + }, + { + "title": "Create Storage Buckets", + "path": "configuration/session-recording/create-storage-bucket" + }, + { + "title": "Enable Session Recording", + "path": "configuration/session-recording/enable-session-recording" + } + ] + }, + { + "title": "Events", "routes": [ { "title": "Overview", @@ -365,22 +411,12 @@ ] }, { - "title": "controller", - "path": "configuration/controller", - "badge": { - "text": "OSS Only", - "type": "outlined", - "color": "neutral" - } + "title": "Controller", + "path": "configuration/controller" }, { - "title": "plugins", - "path": "configuration/plugins", - "badge": { - "text": "OSS Only", - "type": "outlined", - "color": "neutral" - } + "title": "Plugins", + "path": "configuration/plugins" } ] }, @@ -398,6 +434,10 @@ { "title": "Health Endpoint", "path": "operations/health" + }, + { + "title": "Session Recordings", + "path": "operations/manage-recorded-sessions" } ] }, @@ -411,6 +451,10 @@ { "title": "FAQ", "path": "troubleshoot/faq" + }, + { + "title": "Recorded Sessions", + "path": "troubleshoot/troubleshoot-recorded-sessions" } ] }, @@ -537,6 +581,30 @@ { "divider": true }, + { + "title": "Boundary Enterprise", + "routes": [ + { + "title": "Overview", + "path": "enterprise" + }, + { + "title": "Licensing", + "path": "enterprise/licensing" + }, + { + "title": "Automated License Reporting", + "path": "enterprise/automated-license-reporting" + }, + { + "title": "Supported Versions Policy", + "path": "enterprise/supported-versions" + } + ] + }, + { + "divider": true + }, { "title": "Release Notes", "routes": [ @@ -544,6 +612,10 @@ "title": "Overview", "path": "release-notes" }, + { + "title": "v0.13.0", + "path": "release-notes/v0_13_0" + }, { "title": "v0.12.0", "path": "release-notes/v0_12_0" diff --git a/website/public/img/boundary-network.png b/website/public/img/boundary-network.png new file mode 100644 index 0000000000..0695eae68d Binary files /dev/null and b/website/public/img/boundary-network.png differ diff --git a/website/public/img/enable-session-recording.png b/website/public/img/enable-session-recording.png new file mode 100644 index 0000000000..37f3f2ad93 Binary files /dev/null and b/website/public/img/enable-session-recording.png differ diff --git a/website/public/img/inject-creds.png b/website/public/img/inject-creds.png new file mode 100644 index 0000000000..17242da2b4 Binary files /dev/null and b/website/public/img/inject-creds.png differ diff --git a/website/public/img/single-region.png b/website/public/img/single-region.png new file mode 100644 index 0000000000..c5452873c2 Binary files /dev/null and b/website/public/img/single-region.png differ diff --git a/website/public/img/worker-deployment.png b/website/public/img/worker-deployment.png new file mode 100644 index 0000000000..68d890f62b Binary files /dev/null and b/website/public/img/worker-deployment.png differ diff --git a/website/redirects.js b/website/redirects.js index b32feb2878..58478db7b9 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -27,11 +27,6 @@ module.exports = [ destination: 'boundary/docs/overview/what-is-boundary', permanent: true, }, - { - source: '/boundary/docs/concepts/security/permissions/permission-grant-formats', - destination: '/boundary/docs/concepts/security/permissions/', - permanent: true, - }, { source: '/boundary/docs/getting-started/connect-to-target', destination: '/boundary/docs/hcp/get-started/connect-to-target', @@ -115,12 +110,17 @@ module.exports = [ }, { source: '/boundary/docs/oss/installing/postgres', - destination: '/boundary/docs/install-boundary/postgres', + destination: '/boundary/docs/install-boundary/system-requirements', + permanent: true, + }, + { + source: '/boundary/docs/install-boundary/postgres', + destination: '/boundary/docs/install-boundary/system-requirements', permanent: true, }, { source: '/boundary/docs/oss/installing/reference-architectures', - destination: '/boundary/docs/install-boundary/reference-architectures', + destination: '/boundary/docs/install-boundary/recommended-architecture', permanent: true, }, {