threshold/website/content/docs/concepts/permissions.mdx

---
layout: docs
page_title: Permissions
sidebar_title: Permissions
description: |-
  Boundary's permissions model
---

# Overview

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.

Each grant is a mapping that describes a resource or set of resources and the actions that should be allowed on them. Thus, each grant contains one or more of:

* 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
* An `actions` field indicating which actions to provide the resources matched by `id` and `type`

Grant strings can be supplied via JSON or a CLI/UI friendly, easily-composable string syntax.

Roles are composable; a user's final set of grants will be composed of various
roles that each contribute grants to a set of principals that include that user
or groups of which that user is a member.

## Applicable Resource Types

Boundary's [domain model](/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, however, 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 methods will support a `change-password`
action), but the permissions model still defines these at the abstract level.
This helps keep the overall system relatively simple and predictable.

## Scopes are Permission Boundaries

Every role assigns grants within a specific scope: either the scope in which the
role exists, or a scope that is a child of the scope in which the role exists.
This is controlled by the role's "grant scope ID".

When a request is made, the scope in which to discover grants is either provided
by the client (if against specific collection types) or is looked 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, controls which roles are fetched 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

## Permission Grant Formats

Because of the aforementioned properties of the permissions model, grants are
relatively simple. All grants take one of four forms. These examples use the
canonical string syntax; the JSON equivalents are simply an object with a string
`id` value, a string `type` value, and a string array `actions` value.

### ID Only

This is the simplest form: for a given specific resource, allow these actions.
Example:

`id=hsst_1234567890;actions=read,update`

This grants `read` and `update` actions to that single resource.

### Type Only

For a given type, allow these actions. Because type specifies only a collection
as opposed to specific resources within that collection, only colletion actions
are allowed in this format. Currently, this is `create` and `list`. Example:

`type=host-catalog;actions=create,list`

There is one additional restriction: this is only valid against "top-level"
resource types, which currently are:

* Auth Methods
* Auth Tokens
* Groups
* Host Catalogs
* Roles
* Scopes
* Sessions
* Targets
* Users

The reason for this is that other types of resources are contained within one of
these resource types; for instance, accounts are instantiated within an auth
method. To specify actions against those, you must also specify to which
specific containing resource you want the grants to apply. This can be done with
one of the formats shown below.

### Wildcard ID

In this form, the ID of the grant string is a wildcard `*` character. Depending on `type` and `actions` this results in one of a few behaviors.

#### Wildcard ID

When just the ID is `*`, it matches all IDs of the given type. This can be used
with both top-level resource types and not. Example:

`id=*;type=host-set;actions=create,read,update,set-hosts`

#### Wildcard ID and Type

`type` can also be a wildcard, which essentially turns it into a catch-all that
will match any resource of any type within the scope:

`id=*;type=*;actions=read,list`

#### Wildcard ID, Type, and Actions

`actions` can also be a wildcard:

`id=*;type=*;actions=*`

Such a grant is essentially a full administrator grant for a scope.

### Pinned ID

The final form "pins" actions to a non-top-level type within a specific ID. It's
easiest to explain with an example:

`id=hcst_1234567890;type=host-set;actions=create,read,update`

In this example, the user is able to create, read, or update host sets within
the scope, but *only the host sets belonging to host catalog hcst_1234567890*.
Pinning is essentially a way to use top-level resources to create mini
permission boundaries for their subordinate resources.

In this format, `type` can be a wildcard:

`id=hcst_1234567890;type=*;actions=create,read,update`

This would allow `create`, `read`, and `update` actions for all types of
subordinate resources (in this case host sets and hosts) underneath the host
catalog with ID `hcst_1234567890`.

## Resource Table

The following table works as a quick cheat-sheet to help you manage your
permissions. Note that it's not exhaustive; wildcards can provide additional
ways to specify grants. Instead this table indicates the most scoped-down ways
that access to an action can be granted, while helping to portray the concepts
around ID, type, and pin.

<table>
<thead>
  <tr>
    <th>Resource Type</th>
    <th>Available Scopes</th>
    <th>API Endpoint</th>
    <th>Parameters into Permissions Engine</th>
    <th>Available Actions/Grant Examples</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td rowspan="2">Auth Method</td>
    <td rowspan="2">
      <ul>
        <li>Global</li>
        <li>Organization</li>
      </ul>
    </td>
    <td><code>/auth-methods</code></td>
    <td>
      <ul>
        <li>Type</li>
          <ul>
            <li><code>auth-method</code></li>
          </ul>
      </ul>
    </td>
    <td>
      <ul>
        <li><code>create</code>: Create an auth method</li>
          <ul>
            <li><code>type=auth-method;actions=create</code></li>
          </ul>
          <li><code>list</code>: List auth methods</li>
          <ul>
            <li><code>type=auth-method;actions=list</code></li>
          </ul>
      </ul>
    </td>
  </tr>
  <tr>
    <td><code>/auth-methods/[id]</code></td>
     <td>
      <ul>
        <li>ID</li>
          <ul>
            <li><code>[id]</code></li>
          </ul>
        <li>Type</li>
          <ul>
            <li><code>auth-method</code></li>
          </ul>
      </ul>
    </td>
    <td>
      <ul>
        <li><code>read</code>: Read an auth method's configuration</li>
          <ul>
            <li><code>id=[id];actions=read</code></li>
          </ul>
          <li><code>update</code>: Update an auth method's configuration</li>
          <ul>
            <li><code>id=[id];actions=update</code></li>
          </ul>
          <li><code>delete</code>: Delete an auth method</li>
          <ul>
            <li><code>id=[id];actions=delete</code></li>
          </ul>
      </ul>
    </td>
  </tr>
</tbody>
</table>