Dan Heath
3f4cd53d16
* docs: Update headings for new style rule * docs: Fix headings - Get started * docs: Fix headings - Install * docs: Fix headings - Concepts * docs: Fix typos * docs: Fix headings - Configuration * docs: Fix headings - Operations * docs: Fix headings - Troubleshoot * docs: Fix headings - Clients and Develop * docs: Fix headings - HCP and ENT * docs: Fix headings - Release notes * docs: Fix typos * docs: Fix capitalization in TOC
137 lines
6.5 KiB
Plaintext
137 lines
6.5 KiB
Plaintext
---
|
|
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
|
|
|
|
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 and listing visibility
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
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!) |