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 <stellarsquall@protonmail.ch>

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
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ boundary roles add-grant-scopes [options] [args]
+```
+
+</CodeBlockConfig>
+
+### Command options
+
+- `-grant-scope-id=<string>` - 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=<string>` - The ID of the role you want to add grant scopes to.
+- `-version=<int>` 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'

website/content/docs/commands/roles/index.mdx

@@ -27,14 +27,17 @@ $ boundary roles create -name prodops -description "For ProdOps usage"
 Usage: boundary roles <subcommand> [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)

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
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ boundary roles remove-grant-scopes [options] [args]
+```
+
+</CodeBlockConfig>
+
+### Command options
+
+- `-grant-scope-id=<string>` - 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=<string>` - The ID of the role you want to remove grant scopes from.
+- `-version=<int>` 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'

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
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ boundary roles set-grants [options] [args]
+```
+
+</CodeBlockConfig>
+
+### Command options
+
+- `-grant-scope-id=<string>` - 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=<string>` - The ID of the role you want to set grant scopes on.
+- `-version=<int>` 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'

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.
 
-<Tip>
-Roles can only be applied to a single scope at a time in Boundary, meaning each scope requires its own role.
-</Tip>
-
 ## 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.
 

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"