diff --git a/website/content/docs/concepts/security/permissions/assignable-permissions.mdx b/website/content/docs/concepts/security/permissions/advanced.mdx similarity index 64% rename from website/content/docs/concepts/security/permissions/assignable-permissions.mdx rename to website/content/docs/concepts/security/permissions/advanced.mdx index b1f65df4d..6ed3bab7f 100644 --- a/website/content/docs/concepts/security/permissions/assignable-permissions.mdx +++ b/website/content/docs/concepts/security/permissions/advanced.mdx @@ -1,26 +1,20 @@ --- layout: docs -page_title: Assignable Permissions +page_title: Advanced Concepts description: |- - Assignable Permissions + Advanced permissions concepts --- +# 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`). 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. +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. #### Subactions @@ -45,27 +39,7 @@ 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. -### 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 +### Output fields Grant strings can contain an `output_fields` field. This allows fine-grained control over visibility of data returned to users. @@ -134,4 +108,84 @@ 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!) \ No newline at end of file +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. + diff --git a/website/content/docs/concepts/security/permissions/grants.mdx b/website/content/docs/concepts/security/permissions/grants.mdx new file mode 100644 index 000000000..7114be18f --- /dev/null +++ b/website/content/docs/concepts/security/permissions/grants.mdx @@ -0,0 +1,182 @@ +--- +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 efa5a187f..63e8cc454 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 Index +page_title: Permissions Overview description: |- Boundary's permissions model --- @@ -10,10 +10,9 @@ description: |- ## Overview Boundary's permissions model is a composable, RBAC, allow-only model that -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. +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. 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 @@ -21,58 +20,33 @@ 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: +## Grant strings -`id=;type=;actions=;output_fields=` +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 -Each grant string is a mapping that describes a resource or set of resources and -the permissions that should be granted on them. +To learn about writing grant strings with examples, see [Grant Strings](/boundary/docs/concepts/security/permissions/grants). -There are currently two types of selectors: +## Roles -- 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; this might also be used to grant permissions on collections of resources - -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.) - -Additionally, there are two types of assigned permissions: - -- 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 +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 exists, or a scope that is a child of the scope in which the role exists, -controlled by the role's "grant scope ID" value +as determined by the role's "grant scope ID" value. -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. +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. 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: @@ -88,4 +62,6 @@ 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. \ No newline at end of file +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 diff --git a/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx b/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx deleted file mode 100644 index 938301792..000000000 --- a/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -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 43d1a8da2..c87a36746 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/data/docs-nav-data.json b/website/data/docs-nav-data.json index da2f461a8..dd3ef3622 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -138,12 +138,12 @@ "path": "concepts/security/permissions" }, { - "title": "Assignable Permissions", - "path": "concepts/security/permissions/assignable-permissions" + "title": "Grant Strings", + "path": "concepts/security/permissions/grants" }, { - "title": "Permission Grant Formats", - "path": "concepts/security/permissions/permission-grant-formats" + "title": "Advanced Concepts", + "path": "concepts/security/permissions/advanced" }, { "title": "Resource Table", diff --git a/website/redirects.js b/website/redirects.js index 2b3b99e97..b32feb287 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -27,6 +27,11 @@ 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',