From 19ff4b91aec7dbaeb3396e6d56a2be69785a1a7f Mon Sep 17 00:00:00 2001 From: Pete Pacent Date: Mon, 12 Oct 2020 19:31:23 +0000 Subject: [PATCH] Adding manage roles page to docs (#603) * Adding manage roles page to docs * Adding instructions for assigning principals and grants to a role * adding terraform to assign principles example and assign grants example * docs: add role clickthroughs and step-by-step instructions * Removing old manage role screenshots for admin workflow Co-authored-by: Pete Pacent Co-authored-by: Randall Morey --- .../docs/common-workflows/manage-roles.mdx | 216 ++++++++++++++++++ website/data/docs-navigation.js | 1 + 2 files changed, 217 insertions(+) create mode 100644 website/content/docs/common-workflows/manage-roles.mdx diff --git a/website/content/docs/common-workflows/manage-roles.mdx b/website/content/docs/common-workflows/manage-roles.mdx new file mode 100644 index 0000000000..fc56e8c340 --- /dev/null +++ b/website/content/docs/common-workflows/manage-roles.mdx @@ -0,0 +1,216 @@ +--- +layout: docs +page_title: Manage Roles and Permissions +sidebar_title: Manage Roles +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. Roles can be defined at the global, organization, or project scope. + +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 ID's in this example are illustration only - ID's are uniquely generated for every resource upon creation with the exception being +generated resources in `dev mode`. Please make sure to use the resource ID's 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, organization, or project scope. In this example we will create a role in the generated org scope in dev mode. + + + + + +```bash +$ boundary roles create -scope-id $your_scope_id -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 project scope + Parent Scope ID: global + Type: project +``` + + + + + +1. Navigate to an organization, then to roles. +1. Choose the **New** button. +1. Fill the role details. +1. Choose **Save** and view the role edit form page. + + + + + + + +```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. + grants = ["id=*;type=*;action=read,list"] // assigns grants for read and list actions on all resources to the role +} +``` + + + + + +# Assign Principals to a Role + +Users and groups are given permissions to perform actions by assigning them to a role. + + + + + +```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 +``` + + + + + +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. + + + + + + + +```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. + grants = ["id=*;type=*;action=read,list"] // assigns grants for read and list actions on all resources to the role +} +``` + + + + + +# Assign Grants to a Role + +Grants give roles permission to perform actions. For more information on how to format grants see [Permission Grant Formats](https://boundaryproject.io/docs/concepts/security/permissions-model#permission-grant-formats). +In this example we give a role read and list permissions to all resources. + + + + + +```bash +boundary roles add-grants -id $role_id -grant 'id=*;type=*;actions=read,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=read + +``` + + + + + +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. + + + + + + + + + +```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. + grants = ["id=*;type=*;action=read,list"] // assigns grants for read and list actions on all resources to the role +} +``` + + + + diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 3d97b8d58b..c40ec81e4f 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -86,6 +86,7 @@ export default [ 'manage-scopes', 'manage-targets', 'manage-identities', + 'manage-roles', 'manage-sessions', ], },