From c3e49fa337c2700d814915811ceb0b022b44d77e Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Wed, 31 Jan 2024 12:34:22 -0500 Subject: [PATCH] docs: Add multiple grant scopes commands (#4317) * docs: Add multiple grant scopes commands * fixes example role ID * removes statements about each scope requiring its own role --------- Co-authored-by: stellarsquall --- .../docs/commands/roles/add-grant-scopes.mdx | 44 ++++++++++++++++++ website/content/docs/commands/roles/index.mdx | 6 +++ .../commands/roles/remove-grant-scopes.mdx | 45 +++++++++++++++++++ .../docs/commands/roles/set-grant-scopes.mdx | 44 ++++++++++++++++++ website/content/docs/concepts/iam.mdx | 7 +-- website/data/docs-nav-data.json | 12 +++++ 6 files changed, 152 insertions(+), 6 deletions(-) create mode 100644 website/content/docs/commands/roles/add-grant-scopes.mdx create mode 100644 website/content/docs/commands/roles/remove-grant-scopes.mdx create mode 100644 website/content/docs/commands/roles/set-grant-scopes.mdx diff --git a/website/content/docs/commands/roles/add-grant-scopes.mdx b/website/content/docs/commands/roles/add-grant-scopes.mdx new file mode 100644 index 0000000000..0face6fded --- /dev/null +++ b/website/content/docs/commands/roles/add-grant-scopes.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: roles add-grant-scopes - Command +description: |- + The "roles add-grant-scopes" command lets you add grant scopes to a role. +--- + +# roles add-grant-scopes + +Command: `roles add-grant-scopes` + +The `roles add-grant-scopes` command lets you add grant scopes to a role. +You can specify multiple grant scopes per role. + +## Example + +This example adds a grant to a role with the ID `o_1234567890` in the current scope and any children scopes: + +```shell-session +$ boundary roles add-grant-scopes -id r_1234567890 -grant-scope-id "this" -grant-scope-id "children" +``` + +## Usage + + + +```shell-session +$ boundary roles add-grant-scopes [options] [args] +``` + + + +### Command options + +- `-grant-scope-id=` - 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. +- `-id=` - The ID of the role you want to add grant scopes to. +- `-version=` 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. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/index.mdx b/website/content/docs/commands/roles/index.mdx index b5b878d547..4071014ed3 100644 --- a/website/content/docs/commands/roles/index.mdx +++ b/website/content/docs/commands/roles/index.mdx @@ -27,14 +27,17 @@ $ boundary roles create -name prodops -description "For ProdOps usage" Usage: boundary roles [options] [args] # ... Subcommands: + add-grant-scopes Add grant scopes to a role add-grants Add grants to a role add-principals Add principals (users, groups) to a role create Create a role delete Delete a role list List a role read Read a role + remove-grant-scopes Remove grant scopes from a role remove-grants Remove grants from a role remove-principals Remove principals (users, groups) from a role + set-grant-scopes Set the full contents of grant scopes on a role set-grants Set the full contents of the grants on a role set-principals Set the full contents of the principals (users, groups) on a role update Update a role @@ -45,14 +48,17 @@ Subcommands: For more information, examples, and usage, click on the name of the subcommand in the sidebar or one of the links below: +- [add-grant-scopes](/boundary/docs/commands/roles/add-grant-scopes) - [add-grants](/boundary/docs/commands/roles/add-grants) - [add-principals](/boundary/docs/commands/roles/add-principals) - [create](/boundary/docs/commands/roles/create) - [delete](/boundary/docs/commands/roles/delete) - [list](/boundary/docs/commands/roles/list) - [read](/boundary/docs/commands/roles/read) +- [remove-grant-scopes](/boundary/docs/commands/roles/remove-grant-scopes) - [remove-grants](/boundary/docs/commands/roles/remove-grants) - [remove-principals](/boundary/docs/commands/roles/remove-principals) +- [set-grant-scopes](/boundary/docs/commands/roles/set-grant-scopes) - [set-grants](/boundary/docs/commands/roles/set-grants) - [set-principals](/boundary/docs/commands/roles/set-principals) - [update](/boundary/docs/commands/roles/update) diff --git a/website/content/docs/commands/roles/remove-grant-scopes.mdx b/website/content/docs/commands/roles/remove-grant-scopes.mdx new file mode 100644 index 0000000000..de320b6337 --- /dev/null +++ b/website/content/docs/commands/roles/remove-grant-scopes.mdx @@ -0,0 +1,45 @@ +--- +layout: docs +page_title: roles remove-grant-scopes - Command +description: |- + The "roles remove-grant-scopes" command lets you remove grant scopes from a role. +--- + +# roles remove-grant-scopes + +Command: `roles remove-grant-scopes` + +The `roles remove-grant-scopes` command lets you remove grant scopes from a role. +You can specify multiple grant scopes per role. + +## Example + +This example removes a grant from a role with the ID `r_1234567890` in the current scope and any children scopes: + +```shell-session +$ boundary roles remove-grant-scopes -id r_1234567890 -grant-scope-id "this" -grant-scope-id "children" +``` + + +## Usage + + + +```shell-session +$ boundary roles remove-grant-scopes [options] [args] +``` + + + +### Command options + +- `-grant-scope-id=` - The scope IDs that inherit grants removed from 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. +- `-id=` - The ID of the role you want to remove grant scopes from. +- `-version=` The version of the role to remove grant scopes from. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/set-grant-scopes.mdx b/website/content/docs/commands/roles/set-grant-scopes.mdx new file mode 100644 index 0000000000..2894d7c301 --- /dev/null +++ b/website/content/docs/commands/roles/set-grant-scopes.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: roles set-grant-scopes - Command +description: |- + The "roles set-grant-scopes" command lets you set the complete set of grant scopes on a role. +--- + +# roles set-grant-scopes + +Command: `roles set-grant-scopes` + +The `roles set-grant-scopes` command lets you set the complete set of grant scopes on a role. +You can specify multiple grant scopes per role. + +## Example + +This example sets the complete set of grant scopes on a role with the ID `r_1234567890` in the current scope and any children scopes: + +```shell-session +$ boundary roles add-grant-scopes -id r_1234567890 -grant-scope-id "this" -grant-scope-id "children" +``` + +## Usage + + + +```shell-session +$ boundary roles set-grants [options] [args] +``` + + + +### Command options + +- `-grant-scope-id=` - 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. +- `-id=` - The ID of the role you want to set grant scopes on. +- `-version=` The version of the role to set grant scopes on. +If you do not specify a version, the command performs a check-and-set automatically. + +@include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/concepts/iam.mdx b/website/content/docs/concepts/iam.mdx index 01c09e3eb8..70be63f35f 100644 --- a/website/content/docs/concepts/iam.mdx +++ b/website/content/docs/concepts/iam.mdx @@ -41,10 +41,6 @@ method's identity provider to provide up-to-date information. [permissions](/boundary/docs/concepts/security/permissions) which are granted to any principal (user or group) from any scope. Roles can be contained by any scope, and the permissions can be applied to the same scope or any child scope. - -Roles can only be applied to a single scope at a time in Boundary, meaning each scope requires its own role. - - ## Access management ### Configure users - username/password @@ -59,8 +55,7 @@ as the auth method. The accounts and users are only created once the user authen The same applies to OIDC/LDAP [managed groups](/boundary/tutorials/identity-management/oidc-idp-groups). ### Grant permissions -When setting up access controls for a user, it is important to first consider which scope(s) the user needs access to. **Each scope requires its own set of roles**, -giving users permission to perform actions through grants strings. +When setting up access controls for a user, it is important to first consider which scope(s) the user needs access to. Roles give users permission to perform actions through grants strings. It is recommended to add the user to a group, and then add the group to the role(s), instead of adding the user directly to the role(s). This way, you can manage multiple users at the same time, and it is easier to change the permissions of the user by adding/removing them from groups. You can manage OIDC/LDAP users and managed groups the same way, directly in the provider. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 4aa8d806ff..3cba14ec97 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1118,6 +1118,10 @@ "title": "Overview", "path": "commands/roles" }, + { + "title": "add-grant-scopes", + "path": "commands/roles/add-grant-scopes" + }, { "title": "add-grants", "path": "commands/roles/add-grants" @@ -1142,6 +1146,10 @@ "title": "read", "path": "commands/roles/read" }, + { + "title": "remove-grant-scopes", + "path": "commands/roles/remove-grant-scopes" + }, { "title": "remove-grants", "path": "commands/roles/remove-grants" @@ -1150,6 +1158,10 @@ "title": "remove-principals", "path": "commands/roles/remove-principals" }, + { + "title": "set-grant-scopes", + "path": "commands/roles/set-grant-scopes" + }, { "title": "set-grants", "path": "commands/roles/set-grants"