Manage access with 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. Scopes are logical groupings of resources. They allow you to partition resources and then assign ownership of those resources to principals.

You can assign roles to multiple scopes to grant permissions to users who need access to resources across multiple scopes. Child scopes can 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.

Once you create a role, you add principals and grants to it. The principals inherit the grants. You can optionally add grant scopes to the role to configure inheritance across multiple scopes.

Create a role

Roles let you map grant strings or permissions to principals, which are users, groups, and managed groups.

Complete the following steps to create a role:

Log in to Boundary.
Navigate to an org, and then select Roles on the navigation pane.
Click New or New Role.
Complete the following fields:
- Name: (Optional) Enter an optional name for the role for identification purposes.
- Description: (Optional) Enter an optional description of the role for identification purposes.
Click Save.
Boundary creates the role and takes you to the role's Settings page.

To view a cheat sheet to help you create roles, refer to Example roles.

Log in to Boundary.
Use the following command to create a role:
```
$ boundary roles create -scope-id o_1234567890 \
    -description 'An example role' \
    -name 'Example role'
```
You can use any of the following attributes when you create a role:
- -description=<string> - The description to assign to the role.
- -name=<string> - The name to assign to the role.
- -scope-id=<string> - The scope in which you want to create the role. The default is global. You can also specify the scope using the BOUNDARY_SCOPE_ID environment variable.

To view a cheat sheet to help you create roles, refer to Example roles.

Before you create a role, ensure that the principals you want to assign to the role exist. Refer to Terraform patterns for users and auth methods for more information.

You create the role using the boundary_role resource.

The following example adds the "listonly" role to the boundary_scope org scope.

resource "boundary_role" "listonly" {
  name          = "listonly"
  description   = "A list only role"
  scope_id      = boundary_scope.org.id
}

To view a cheat sheet to help you create roles, refer to Example roles.

Assign principals to a role

You can grant users, groups, and managed groups permissions to perform actions by assigning them to a role.

Complete the following steps to assign principals to a role:

Log in to Boundary.
Select Roles in the navigation pane, and then select the role you want to assign principals to.
Click the Principals tab.
Click the Add Principals button, or select it from the Manage dropdown.
Select one or more users, groups, or managed groups to associate with the role.
Click Add Principals.
Boundary adds the principals to the role. The role's Principals page should now show the principals you selected.

Log in to Boundary.
Use the following command to assign principals to a role:
```
$ boundary roles add-principals -id r_22sVJoKZj3 \
    -principal g_qu2V5QMGQD
```
You can use any of the following attributes when you assign principals a role:
- -id=<string> - The ID of the role you want to add principals to.
- -principal=<string> - The principals you want to add to the role. Principals can be users or groups. You can optionally specify multiple principals per role.
- -version=<int> The version of the role to add principals to. If you do not specify a version, the command performs a check-and-set automatically.

You can assign principals with the principal_ids attribute.

The following example adds the boundary_user.foo and boundary_group.bar principals to the role.

resource "boundary_role" "listonly" {
  name          = "listonly"
  description   = "A list only role"
  principal_ids = [boundary_user.foo.id,boundary_group.bar.id]
  scope_id      = boundary_scope.org.id
}

Assign grants to a role

Grants describe the actions that the principals are allowed to perform. You can add grants to a role either by manually defining grant strings or by using the UI to select from pre-defined templates.

Complete the following steps to assign grants to a role:

Log in to Boundary.
In the navigation pane, select Roles, and then select the role you want to assign grants to.
On the role's Settings page, click the Grants tab.
Choose how you want to add grants:
- To manually add or modify grants:
  1. Click Edit Grants.
  2. Enter or modify grant strings in the editor. Enter each grant string on a different line.
- To add pre-defined grant templates:
  1. Click Add Grant Templates.
  2. In the template list, select the grant strings to add.
  3. Click Add Grant Templates.
Click Save to apply your changes.

To view common use cases for grants based on job function, refer to Common use cases.

Log in to Boundary.
Use the following command to assign grants to a role:
```
$ boundary roles add-grants -id r_22sVJoKZj3 \
    -grant 'ids=*;type=*;actions=no-op,list'
```
You can use any of the following attributes when you assign grants a role:
- -grant=<string> - The grants you want to add. You can specify grants in compact string format or JSON. If you use JSON, be sure to escape it properly. You can optionally specify multiple grants.
- -ids=<string> - The IDs of the roles you want to add grants to. You can specify one or more IDs. If you specify multiple IDs using text, use commas to separate the IDs. If you specify multiple IDs using JSON, use an array.
- -version=<int> The version of the role to add grants to. If you do not specify a version, the command performs a check-and-set automatically.

To view common use cases for grants based on job function, refer to Common use cases.

You assign grants using the grant_strings attribute.

resource "boundary_role" "listonly" {
  name          = "listonly"
  description   = "A list only role"
  principal_ids = [boundary_user.foo.id,boundary_group.bar.id]
  grant_strings = ["ids=*;type=*;actions=no-op,list"]
  scope_id      = boundary_scope.org.id
}

To view common use cases for grants based on job function, refer to Common use cases.

Add grant scopes

You can assign roles to multiple scopes to configure role inheritance. Roles can have a combination of the following grant scopes:

this (this scope)
children (all direct children of the assigned scope, global and org scopes only)
descendants (all descendants of a scope, global only)
ID (such as o_v2MpV4vBHN or p_0vfvaQPwhD. Roles accept multiple grant scope IDs)

Boundary automatically assigns grants the this scope, when you create them.

Complete the following steps to add grant scopes to a role:

Log in to Boundary.
Select Roles in the navigation pane, and then select the role you want to add grant scopes to.
Click the Scopes tab.
From the Manage dropdown, select Manage Scopes.
Select from the following:
- Add this scope: Adds the current scope to the grant.
- Add all children: Adds all direct children of the current scope and can only be used with global and org scopes.
- Add all descendants: Adds all descendants of the current scope and can only be used with the global scope.
To add additional scopes:
1. Click Manage custom scopes.
2. Select any additional scopes that you want to assign to the grant.
3. Click Save.
Click Save.
Boundary assigns the grant scopes to the role.

Log in to Boundary.
Use the following command to add grant scopes:
```
$ boundary roles add-grant-scopes -id r_22sVJoKZj3 \
    -grant-scope-id "children"
```
You can use any of the following attributes when you add grant scopes:
- -grant-scope-id=<string> - The scope IDs that inherit grants set on the role. You can specify the following values:
  - this - Applies to the current scope.
  - children - Applies to all direct children of the scope and can only be used with global and org scopes.
  - descendants - Applies to all descendants of the scope and can only be used with the global scope.
  Boundary does not allow you to create redundant grant scopes. For example, if an org scope inherits a grant from the global scope, you cannot apply the same grant directly to the org scope.
- -id=<string> - The ID of the role you want to add grant scopes to.
- -version=<int> The version of the role to add grant scopes to. If you do not specify a version, the command performs a check-and-set automatically.

You can declare scope inheritance with the grant_scope_ids attribute.

The following example adds the assigned scope's ID with this, the ID of a project scope, and the direct children of the role's scope to the role. This includes projects within org_one in this example.

resource "boundary_role" "listonly" {
  name            = "listonly"
  description     = "A list only role"
  principal_ids   = [boundary_user.foo.id,boundary_group.bar.id]
  grant_strings   = ["ids=*;type=*;actions=no-op,list"]
  scope_id        = boundary_scope.org.id
  grant_scope_ids = ["this","children"]
}

Next steps

To manage access to resources dynamically, refer to Manage principals and Filter managed groups.

More information

To better understand Boundary's permissions model, refer to Permissions in Boundary.
For more specific information about the roles resource, refer to the Roles domain model topic.
To learn more about creating or managing roles, refer to the CLI roles topic or the API Role service topic.
To view a cheat sheet to help you create roles, refer to Example roles.
To view common use cases for grants based on job function, refer to Common use cases.

Tutorials

For hands on practice creating partition boundaries to assign ownership over resources, refer to the following tutorials: