HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Boundary
Boundary Home

You are viewing documentation for version v0.8.x. View latest version.

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.