threshold/website/content/docs/common-workflows/manage-roles.mdx

---
layout: docs
page_title: Manage Roles and Permissions
description: How to manage Roles and Permissions
---

# Manage Roles and Permissions

[Roles](/docs/concepts/domain-model/roles) in Boundary manage the permissions given to principals ([Users](/docs/concepts/domain-model/users)/[Groups](/docs/concepts/domain-model/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.

<Tabs>
<Tab heading="CLI">

```bash
$ 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
```

</Tab>
<Tab heading="Admin Console">

1. Navigate to an org, then to roles.
1. Choose the **New** button.
1. Fill the role details.
1. Choose **Save** and view the role edit form page.

<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
  <source
    type="video/mp4"
    src="https://www.datocms-assets.com/2885/1602516687-boundary-clickthrough-role-create.mp4"
  />
</video>

</Tab>
<Tab heading="Terraform">

```hcl
resource "boundary_scope" "role" {
  name        = "my_role"
  description = "My first role!"
  scope_id    = o_1234567890
}
```

</Tab>
</Tabs>

# Assign Principals to a Role

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

<Tabs>
<Tab heading="CLI">

```bash
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
```

</Tab>
<Tab heading="Admin Console">

1. From the role edit form, navigate to the **Principals** tab.
1. Choose **Add Principals** from the **Manage** dropdown.
1. Select one or more users and groups to associate with the role.
1. Choose the **Add Principals** button and view the principals list.

<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
  <source
    type="video/mp4"
    src="https://www.datocms-assets.com/2885/1602516684-boundary-clickthrough-role-add-principal.mp4"
  />
</video>

</Tab>
<Tab heading="Terraform">

```hcl
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.
}
```

</Tab>
</Tabs>

# 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](https://boundaryproject.io/docs/concepts/security/permissions#permission-grant-formats).
In this example we give a role read and list permissions to all resources.

<Tabs>
<Tab heading="CLI">

```bash
boundary roles add-grants -id $role_id -grant 'id=*;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

```

</Tab>
<Tab heading="Admin Console">

1. From the role edit form, navigate to the **Grants** tab.
1. Fill a new grant string.
1. Choose **Add**.
1. Choose **Save** to commit your grant changes.

<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
  <source
    type="video/mp4"
    src="https://www.datocms-assets.com/2885/1602516681-boundary-clickthrough-role-add-grant.mp4"
  />
</video>

1. From the role edit form, navigate to the **Grant Scope** section.
1. Select a scope.
1. Choose **Save** to commit your grant changes.

<video muted playsInline autoPlay loop class="boundary-clickthrough-video">
  <source
    type="video/mp4"
    src="https://www.datocms-assets.com/2885/1605554373-boundary-clickthrough-manage-roles-role-assign-grant-scope-v0-1-2.mp4"
  />
</video>

</Tab>

<Tab heading="Terraform">

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

</Tab>
</Tabs>