Manage roles and permissions

Roles in Boundary manage the permissions assigned to principals:

You can define a role in the global, org, or project scopes.

In this topic, we show how to create a role in Boundary, assign that role a permission set using grants, and assign principals to the role.

Note

All resource IDs in this guide are examples. Boundary generates unique IDs for every resource, with the exception of the resources that are created when you use Boundary's dev mode. Make sure you substitute your own resource IDs when you follow this example. For example, if you execute boundary roles create, use the resource ID of the role in your stdout, not the ID in the example command.

Create a role

Roles can live in the global, org, or project scopes. In this example, we create a role in the generated org scope in Boundary's dev mode.

$ boundary roles create -scope-id o_1234567890 -name list_all_resources -description "List all resources"Role information:  Created Time:        Thu, 25 Jul 2024 17:21:22 MDT  Description:         List all resources  Grant Scope ID:      this  ID:                  r_22sVJoKZj3  Name:                list_all_resources  Updated Time:        Thu, 25 Jul 2024 17:21:22 MDT  Version:             2  Scope:    ID:                o_1234567890    Name:              Generated org scope    Parent Scope ID:   global    Type:              org  Authorized Actions:    add-principals    set-grants    remove-grants    no-op    remove-principals    set-grant-scopes    read    update    add-grant-scopes    delete    add-grants    set-principals    remove-grant-scopes  Grant Scope IDs:    ID:             this

Before you create a role, ensure that the principals you want to assign to the role exist.

For example, to create an org, project, user, and a group in an org scope, use the following resources:

resource "boundary_scope" "org" {  name                     = "org_one"  description              = "My org scope"  scope_id                 = "global"  auto_create_admin_role   = true  auto_create_default_role = true}resource "boundary_scope" "project" {  name                   = "project_one"  description            = "My project scope"  scope_id               = boundary_scope.org.id  auto_create_admin_role = true}resource "boundary_user" "foo" {  name     = "Foo user"  scope_id = boundary_scope.org.id}resource "boundary_group" "bar" {  name     = "Bar group"  scope_id = boundary_scope.org.id}

Next, add the boundary_role resource, adding the org scope for scope_id:

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

Assign principals to a role

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

Examples of principal IDs include:

User: u_tfRrCUIpGH
Group: g_qu2V5QMGQD
Managed group: mgldap_98UNHEqtmD

The following example adds a group as a role principal.

$ boundary roles add-principals -id r_22sVJoKZj3 -principal g_qu2V5QMGQDRole information:  Created Time:        Thu, 25 Jul 2024 17:21:22 MDT  Description:         List all resources  Grant Scope ID:      this  ID:                  r_22sVJoKZj3  Name:                list_all_resources  Updated Time:        Thu, 25 Jul 2024 17:33:33 MDT  Version:             3  Scope:    ID:                o_1234567890    Name:              Generated org scope    Parent Scope ID:   global    Type:              org  Authorized Actions:    set-grant-scopes    no-op    read    update    set-principals    add-principals    set-grants    remove-principals    remove-grant-scopes    delete    add-grants    add-grant-scopes    remove-grants  Principals:    ID:             g_qu2V5QMGQD      Type:         group      Scope ID:     global  Grant Scope IDs:    ID:             this

Log in to Boundary.
Select Roles in the navigation pane, and then select the role you want to assign principals to.
From the role's Setting page, click on 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 the Add Principals button. The role's Principals page should now show the principals you selected before.

The Principals tab lets you assign principals to a role.

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. For more information on how to format grants, refer to Permission grant formats.

In this example, we give a role read and list permissions for all resources. The grant we apply for the role is:

ids=*;type=*;actions=no-op,list

The no-op action enables users that don't have any other assigned permissions, like read or update, the ability to list resources they cannot take any actions on.

$ boundary roles add-grants -id r_22sVJoKZj3 -grant 'ids=*;type=*;actions=no-op,list'Role information:  Created Time:        Thu, 25 Jul 2024 17:21:22 MDT  Description:         List all resources  Grant Scope ID:      this  ID:                  r_22sVJoKZj3  Name:                list_all_resources  Updated Time:        Thu, 25 Jul 2024 17:42:46 MDT  Version:             4  Scope:    ID:                o_1234567890    Name:              Generated org scope    Parent Scope ID:   global    Type:              org  Authorized Actions:    remove-grant-scopes    add-grants    add-grant-scopes    delete    add-principals    set-grant-scopes    set-principals    remove-principals    set-grants    remove-grants    no-op    read    update  Principals:    ID:             g_qu2V5QMGQD      Type:         group      Scope ID:     global  Canonical Grants:    ids=*;type=*;actions=list,no-op  Grant Scope IDs:    ID:             this

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}

Add grant scopes

You can assign roles to multiple scopes and configure role inheritance.

Role can have a combination of the following grant scope IDs:

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.

The following command adds the IDs of a project scope and the direct children of the role's scope to the role. This includes projects within o_1234567890 in this example.

$ boundary roles add-grant-scopes -id r_22sVJoKZj3 -grant-scope-id "p_1234567890" -grant-scope-id "children"Role information:  Created Time:        Thu, 25 Jul 2024 17:21:22 MDT  Description:         List all resources  ID:                  r_22sVJoKZj3  Name:                list_all_resources  Updated Time:        Thu, 25 Jul 2024 18:06:08 MDT  Version:             6  Scope:    ID:                o_1234567890    Name:              Generated org scope    Parent Scope ID:   global    Type:              org  Authorized Actions:    remove-principals    set-grants    remove-grants    delete    add-principals    add-grants    set-grant-scopes    set-principals    add-grant-scopes    no-op    read    update    remove-grant-scopes  Principals:    ID:             g_qu2V5QMGQD      Type:         group      Scope ID:     global  Canonical Grants:    ids=*;type=*;actions=list,no-op  Grant Scope IDs:    ID:             children    ID:             p_1234567890    ID:             this

Log in to Boundary.
Select Roles in the navigation pane, and then select the role.
Click on the Scopes tab. The this scope will already be applied to the grant.
From the Manage dropdown, click Manage Scopes.
Click Manage custom scopes.
Select any additional scopes that you want to assign this grant, such as p_1234567890 in Boundary's dev mode.
The settings you define for the role's children or descendants will apply to any scope you assign to this role.
Click Apply changes to org.
Toggle the switch beside Add all children.
Click Save. The selected scope IDs and children are listed under the Scopes tab.

The Manage Scopes dialog lets you customize which scopes are associated with a role.

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",boundary_scope.project.id,"children"]}

More information

Refer to Assignable permissions for more information about the permissions you can assign to Boundary principals.
Refer to Permission grant formats for more information about grant strings and example formats.
Refer to the Resource table for a cheat sheet to help you manage your permissions.