Manage Roles and Permissions

Roles in Boundary manage the permissions given to principals (Users/Groups). Roles can be defined at the global, org, or project scopes.

In this example, we're going to show you how to create a role in Boundary, assign that roles grants, and assign principals to the role.

Note that all resource IDs in this example are illustration only - IDs are uniquely generated for every resource upon creation with the exception being generated resources in dev mode. Please make sure to use the resource IDs that are generated when running this example. For example, if you run boundary roles create, use the resource ID of the role seen in 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 will create a role in the generated org scope in dev mode.

$ boundary roles create -scope-id o_1234567890 -name my_role -description "My first role"

Role information:
  Created Time:        Fri, 09 Oct 2020 14:19:22 PDT
  Description:         My first role
  Grant Scope ID:      o_1234567890
  ID:                  r_kHY8tQteXr
  Name:                my_role
  Updated Time:        Fri, 09 Oct 2020 14:19:22 PDT
  Version:             1

  Scope:
    ID:                o_1234567890
    Name:              Generated org scope
    Parent Scope ID:   global
    Type:              org

Assign Principals to a Role

Users and groups are granted permissions to perform actions by assigning them to a role.

boundary roles add-principals -id $role_id -principal $principal_id

Role information:
  Created Time:        Fri, 09 Oct 2020 14:45:47 PDT
  Description:         My first role
  Grant Scope ID:      o_1234567890
  ID:                  r_CqEl81Io1C
  Name:                test
  Updated Time:        Fri, 09 Oct 2020 16:31:39 PDT
  Version:             2

  Scope:
    ID:                o_1234567890
    Name:              Generated org scope
    Parent Scope ID:   global
    Type:              org

  Principals:
    ID:             u_gAv6YgVtVs
      Type:         user
      Scope ID:     o_1234567890

resource "boundary_scope" "role" {
  name        = "my_role"
  description = "My first role!"
  scope_id    = o_1234567890 // sets the role's scope as the default generated org. To change the role's scope provide a different scope id.
  principals  = u_1234567890 // assigns the default generated admin user to the role. To assign a different principal provide a different principal id.
}

Assign Grants to a Role

Grants describe the actions that the principals should be allowed to perform. For more information on how to format grants see Permission Grant Formats. In this example we give a role read and list permissions to all resources.

boundary roles add-grants -id $role_id -grant 'ids=*;type=*;actions=no-op,list'

Role information:
  Created Time:        Fri, 09 Oct 2020 14:45:47 PDT
  Description:         My first role
  Grant Scope ID:      o_1234567890
  ID:                  r_CqEl81Io1C
  Name:                test
  Updated Time:        Fri, 09 Oct 2020 17:15:47 PDT
  Version:             3

  Scope:
    ID:                o_1234567890
    Name:              Generated org scope
    Parent Scope ID:   global
    Type:              org

  Principals:
    ID:             u_gAv6YgVtVs
      Type:         user
      Scope ID:     o_1234567890

  Canonical Grants:
    id=*;type=*;actions=list,no-op

resource "boundary_scope" "role" {
  name        = "my_role"
  description = "My first role!"
  scope_id    = o_1234567890
  principals  = u_1234567890
  grants      = ["ids=*;type=*;action=read,list"]
}