threshold/website/content/docs/concepts/security/permissions/assignable-permissions.mdx

---
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.