mirror of https://github.com/hashicorp/boundary
docs(permissions): break permissions into sections (#1893)
* docs(permissions): break permissions into sections * fixup! docs(permissions): break permissions into sectionspull/1906/head
Irena Rindos
4 years ago
committed by
GitHub
parent
82b121c9ec
commit
bc6689fb16
@ -0,0 +1,135 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Assignable Permissions
|
||||
description: |-
|
||||
Assignable Permissions
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
#### Subactions
|
||||
|
||||
Starting in Boundary 0.1.6, some subactions are supported. These actions have a
|
||||
format `top_level_action:subaction`, such as `read:self`. Being granted the top
|
||||
level action infers being granted all subactions. Thus, if a grant conveys
|
||||
`read`, it also matches the API actions `read` and `read:self`. However, if a
|
||||
grant conveys `read:self`, it will match the API action `read:self` but will not
|
||||
match `read`.
|
||||
|
||||
#### The `no-op` Action
|
||||
|
||||
Starting in Boundary 0.2.1 there is an action that can be granted called
|
||||
`no-op`. As might be apparent, `no-op` is not used for any real action in
|
||||
Boundary; the purpose of this action is for listing visibility. Boundary only
|
||||
shows resources in the output of a `list` action for which a user has at least
|
||||
one granted action. Thus, without `no-op`, in order for a resource to be visible
|
||||
in a `list` action, a different action such as `read` would have to be granted
|
||||
to a user. This could result in exposing more information than desired,
|
||||
especially in the case of listing scopes and authentication methods so that
|
||||
users can perform initial authentication to 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
|
||||
|
||||
Starting in Boundary 0.2.1, grant strings can contain an `output_fields` field.
|
||||
This allows fine-grained control over visibility of data returned to users.
|
||||
|
||||
In many cases, `output_fields` will not need to be set directly. However, an
|
||||
example in the form of some history helps provide some context as to when this
|
||||
might be useful.
|
||||
|
||||
In Boundary 0.2.0, we restricted the set of fields returned for some `list`
|
||||
calls (those on the `scopes` and `auth-methods` collections) to a small set if
|
||||
the user was the anonymous user `u_anon`. Although default behavior in Boundary
|
||||
was to display all resource fields when listing, because the default was also to
|
||||
allow anonymous access to perform `list` on scopes and auth methods (in order to
|
||||
discover auth methods and then authenticate to them), returning all
|
||||
configuration information for all scopes and auth methods felt like it was
|
||||
publicly disclosing more information to users than might be desired.
|
||||
|
||||
At the same time, this was not an ideal solution for two reasons:
|
||||
|
||||
1. There is no one-size-fits-all security policy, and what we thought were
|
||||
reasonable defaults may not work in all situations
|
||||
|
||||
2. It made the scopes and auth methods listing behavior work differently from
|
||||
any other `list` action, which is not ideal
|
||||
|
||||
As a result, we decided to approach this problem the same way we normally try to
|
||||
within Boundary: set resonable defaults, but give the administrator ultimate
|
||||
control.
|
||||
|
||||
The resulting behavior is as follows: `output_fields` references the field names
|
||||
of the JSON object response, composes just like other parts of the RBAC model,
|
||||
and are action-specific. That is, a grant like:
|
||||
|
||||
`id=*;type=auth-methods;actions=list,no-op;output_fields=scope_id,name,description`
|
||||
|
||||
will, if all by itself, result in those three identified output fields applying
|
||||
to `list` (and `no-op`) actions for all auth methods in the scope. Thus when
|
||||
performing a `list`, each item returned will have only those three fields
|
||||
populated. Any other actions (like `read` or `update`) are unaffected and will
|
||||
use defaults.
|
||||
|
||||
A grant like:
|
||||
|
||||
`id=*;type=auth-methods;output_fields=id`
|
||||
|
||||
will, if all by itself, result in _any_ action against auth methods in the scope
|
||||
having only `id` returned.
|
||||
|
||||
However, if both of the above grants are included, since grants are composable
|
||||
the final set of output fields will be `id,scope_id,name,description` for `list`
|
||||
(and `no-op`) actions, and `id` for all other actions.
|
||||
|
||||
If, after the grants are composed for a given request, none of the grants
|
||||
applicable to the resource/action contain `output_fields` definitions, the
|
||||
defaults are used. These defaults are implemented using internal values for
|
||||
`output_fields` and vary based on whether the user is the anonymous user:
|
||||
|
||||
- If the user is the anonymous user, a useful but restricted set of fields is
|
||||
returned. This includes `id`, `scope_id`, `scope`, `name`, `description`, and a
|
||||
few more.
|
||||
|
||||
- If the user is any authenticated user, the full set of fields is returned
|
||||
|
||||
To think about it a different way, empty `output_fields`, after grant
|
||||
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!)
|
||||
|
||||
#### Output Fields and Monitoring
|
||||
|
||||
As another example, it's possible to get creative and use `output_fields` to
|
||||
allow services to keep tabs on various aspects of the system for monitoring
|
||||
purposes without needing to provision Boundary tokens to those services. For
|
||||
instance, by allowing access to list users to `u_anon` but restrict the set of
|
||||
fields to `id` only, a monitoring system could watch and alert if more users
|
||||
than expected are showing up in the system, while the IDs themselves are not
|
||||
really meaningful to any other caller that accesses the same endpoint.
|
||||
|
||||
This will be especially useful once we introduce the ability to have CIDR
|
||||
restrictions against roles and/or grants, which are planned but not currently
|
||||
scheduled, as you can only have these grants apply to specific internal
|
||||
services, along with restricting the data that is returned for those services
|
||||
that do match.
|
||||
@ -0,0 +1,91 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Permissions Index
|
||||
description: |-
|
||||
Boundary's permissions model
|
||||
---
|
||||
|
||||
# Permissions in Boundary
|
||||
|
||||
## 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.
|
||||
|
||||
Boundary's [domain model](/docs/concepts/domain-model) is based on resource
|
||||
types. These can be implemented directly, such as with targets, or they can be
|
||||
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=<id>;type=<type>;actions=<action list>;output_fields=<fields list>`
|
||||
|
||||
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:
|
||||
|
||||
- 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
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- The user's ID is contained in the principal IDs set on the role
|
||||
|
||||
- A group the user belongs to is contained in the principal IDs set on the role
|
||||
|
||||
- The user is logged in and the `u_auth` user is contained in the principal IDs
|
||||
set on the role
|
||||
|
||||
- The role contains the `u_anon` user in the in the principal IDs set on the
|
||||
role
|
||||
|
||||
Roles are composable; a user's final set of grants will be composed of grants
|
||||
that originate from all matching roles.
|
||||
@ -0,0 +1,122 @@
|
||||
---
|
||||
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.
|
||||
|
||||
- `{{user.id}}`: The substituted value is the user ID associated with the token
|
||||
used to perform the action.
|
||||
@ -1,340 +1,10 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Permissions
|
||||
page_title: Resource Table
|
||||
description: |-
|
||||
Boundary's permissions model
|
||||
Resource Table
|
||||
---
|
||||
|
||||
# Permissions in Boundary
|
||||
|
||||
## 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.
|
||||
|
||||
Boundary's [domain model](/docs/concepts/domain-model) is based on resource
|
||||
types. These can be implemented directly, such as with targets, or they can be
|
||||
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=<id>;type=<type>;actions=<action list>;output_fields=<fields list>`
|
||||
|
||||
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:
|
||||
|
||||
- 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
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- The user's ID is contained in the principal IDs set on the role
|
||||
|
||||
- A group the user belongs to is contained in the principal IDs set on the role
|
||||
|
||||
- The user is logged in and the `u_auth` user is contained in the principal IDs
|
||||
set on the role
|
||||
|
||||
- The role contains the `u_anon` user in the in the principal IDs set on the
|
||||
role
|
||||
|
||||
Roles are composable; a user's final set of grants will be composed of grants
|
||||
that originate from all matching roles.a
|
||||
|
||||
## 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.
|
||||
|
||||
#### Subactions
|
||||
|
||||
Starting in Boundary 0.1.6, some subactions are supported. These actions have a
|
||||
format `top_level_action:subaction`, such as `read:self`. Being granted the top
|
||||
level action infers being granted all subactions. Thus, if a grant conveys
|
||||
`read`, it also matches the API actions `read` and `read:self`. However, if a
|
||||
grant conveys `read:self`, it will match the API action `read:self` but will not
|
||||
match `read`.
|
||||
|
||||
#### The `no-op` Action
|
||||
|
||||
Starting in Boundary 0.2.1 there is an action that can be granted called
|
||||
`no-op`. As might be apparent, `no-op` is not used for any real action in
|
||||
Boundary; the purpose of this action is for listing visibility. Boundary only
|
||||
shows resources in the output of a `list` action for which a user has at least
|
||||
one granted action. Thus, without `no-op`, in order for a resource to be visible
|
||||
in a `list` action, a different action such as `read` would have to be granted
|
||||
to a user. This could result in exposing more information than desired,
|
||||
especially in the case of listing scopes and authentication methods so that
|
||||
users can perform initial authentication to 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
|
||||
|
||||
Starting in Boundary 0.2.1, grant strings can contain an `output_fields` field.
|
||||
This allows fine-grained control over visibility of data returned to users.
|
||||
|
||||
In many cases, `output_fields` will not need to be set directly. However, an
|
||||
example in the form of some history helps provide some context as to when this
|
||||
might be useful.
|
||||
|
||||
In Boundary 0.2.0, we restricted the set of fields returned for some `list`
|
||||
calls (those on the `scopes` and `auth-methods` collections) to a small set if
|
||||
the user was the anonymous user `u_anon`. Although default behavior in Boundary
|
||||
was to display all resource fields when listing, because the default was also to
|
||||
allow anonymous access to perform `list` on scopes and auth methods (in order to
|
||||
discover auth methods and then authenticate to them), returning all
|
||||
configuration information for all scopes and auth methods felt like it was
|
||||
publicly disclosing more information to users than might be desired.
|
||||
|
||||
At the same time, this was not an ideal solution for two reasons:
|
||||
|
||||
1. There is no one-size-fits-all security policy, and what we thought were
|
||||
reasonable defaults may not work in all situations
|
||||
|
||||
2. It made the scopes and auth methods listing behavior work differently from
|
||||
any other `list` action, which is not ideal
|
||||
|
||||
As a result, we decided to approach this problem the same way we normally try to
|
||||
within Boundary: set resonable defaults, but give the administrator ultimate
|
||||
control.
|
||||
|
||||
The resulting behavior is as follows: `output_fields` references the field names
|
||||
of the JSON object response, composes just like other parts of the RBAC model,
|
||||
and are action-specific. That is, a grant like:
|
||||
|
||||
`id=*;type=auth-methods;actions=list,no-op;output_fields=scope_id,name,description`
|
||||
|
||||
will, if all by itself, result in those three identified output fields applying
|
||||
to `list` (and `no-op`) actions for all auth methods in the scope. Thus when
|
||||
performing a `list`, each item returned will have only those three fields
|
||||
populated. Any other actions (like `read` or `update`) are unaffected and will
|
||||
use defaults.
|
||||
|
||||
A grant like:
|
||||
|
||||
`id=*;type=auth-methods;output_fields=id`
|
||||
|
||||
will, if all by itself, result in _any_ action against auth methods in the scope
|
||||
having only `id` returned.
|
||||
|
||||
However, if both of the above grants are included, since grants are composable
|
||||
the final set of output fields will be `id,scope_id,name,description` for `list`
|
||||
(and `no-op`) actions, and `id` for all other actions.
|
||||
|
||||
If, after the grants are composed for a given request, none of the grants
|
||||
applicable to the resource/action contain `output_fields` definitions, the
|
||||
defaults are used. These defaults are implemented using internal values for
|
||||
`output_fields` and vary based on whether the user is the anonymous user:
|
||||
|
||||
- If the user is the anonymous user, a useful but restricted set of fields is
|
||||
returned. This includes `id`, `scope_id`, `scope`, `name`, `description`, and a
|
||||
few more.
|
||||
|
||||
- If the user is any authenticated user, the full set of fields is returned
|
||||
|
||||
To think about it a different way, empty `output_fields`, after grant
|
||||
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!)
|
||||
|
||||
#### Output Fields and Monitoring
|
||||
|
||||
As another example, it's possible to get creative and use `output_fields` to
|
||||
allow services to keep tabs on various aspects of the system for monitoring
|
||||
purposes without needing to provision Boundary tokens to those services. For
|
||||
instance, by allowing access to list users to `u_anon` but restrict the set of
|
||||
fields to `id` only, a monitoring system could watch and alert if more users
|
||||
than expected are showing up in the system, while the IDs themselves are not
|
||||
really meaningful to any other caller that accesses the same endpoint.
|
||||
|
||||
This will be especially useful once we introduce the ability to have CIDR
|
||||
restrictions against roles and/or grants, which are planned but not currently
|
||||
scheduled, as you can only have these grants apply to specific internal
|
||||
services, along with restricting the data that is returned for those services
|
||||
that do match.
|
||||
|
||||
## 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.
|
||||
|
||||
- `{{user.id}}`: The substituted value is the user ID associated with the token
|
||||
used to perform the action.
|
||||
|
||||
## Resource Table
|
||||
|
||||
The following table works as a quick cheat-sheet to help you manage your
|
||||
Loading…
Reference in new issue