Permissions in Boundary

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

ids=<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, which are users, groups, and managed groups. Every role assigns grants within a scope, as determined by the role's grant scope IDs.

You can assign roles to multiple scopes to grant permissions to users who need access to resources across multiple scopes. You can also configure child scopes to inherit roles from parents. For example, the global scope could have multiple child scopes called "orgs". When you create a role in the global scope, you can configure it to apply to those children org scopes.

When a user makes a request, the client may provide the scope or Boundary may look it 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, control which roles Boundary fetches 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.