90 lines
3.8 KiB
Plaintext
90 lines
3.8 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Permissions index
|
|
description: |-
|
|
Boundary's permissions model
|
|
---
|
|
|
|
# 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](/boundary/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:
|
|
|
|
`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.
|