diff --git a/internal/website/permstable/permstable.go b/internal/website/permstable/permstable.go
index bfd2dbaf0..70d58eb07 100644
--- a/internal/website/permstable/permstable.go
+++ b/internal/website/permstable/permstable.go
@@ -17,7 +17,7 @@ import (
"github.com/hashicorp/boundary/internal/types/resource"
)
-const permsFile = "website/content/docs/concepts/security/permissions/resource-table.mdx"
+const permsFile = "website/content/docs/configuration/identity-access-management/resource-table.mdx"
var (
iamScopes = []string{"Global", "Org"}
@@ -393,7 +393,7 @@ var resources = map[resource.Type]info{
},
},
resource.Alias: {
- scopes: append(iamScopes, infraScope...),
+ scopes: []string{"Global"},
},
resource.AuthMethod: {
scopes: iamScopes,
diff --git a/website/content/docs/common-workflows/manage-roles.mdx b/website/content/docs/common-workflows/manage-roles.mdx
index 7b81e86a8..0c0781928 100644
--- a/website/content/docs/common-workflows/manage-roles.mdx
+++ b/website/content/docs/common-workflows/manage-roles.mdx
@@ -1,91 +1,44 @@
---
layout: docs
-page_title: Manage Roles and Permissions
-description: How to manage Roles and Permissions
+page_title: Manage roles and permissions
+description: How to manage roles, permissions, and grants.
---
-# Manage Roles and Permissions
+# Manage roles and permissions
-[Roles](/boundary/docs/concepts/domain-model/roles) in Boundary manage the permissions given to principals ([Users](/boundary/docs/concepts/domain-model/users)/[Groups](/boundary/docs/concepts/domain-model/groups)). Roles can be defined at the global, org, or project scopes.
+[Roles](/boundary/docs/concepts/domain-model/roles) in Boundary manage the permissions assigned to principals:
-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.
+- [Users](/boundary/docs/concepts/domain-model/users)
+- [Groups](/boundary/docs/concepts/domain-model/groups)
+- [Managed Groups](/boundary/docs/concepts/domain-model/managed-groups)
-~> 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.
+You can define a role in the global, org, or project scopes.
-# Create a Role
+In this topic, we show how to create a role in Boundary, assign that role a permission set using grants, and assign principals to the 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.
+
+
+All resource IDs in this guide are examples. Boundary generates unique IDs for every resource, with the exception of the resources that are created when you use Boundary's `dev` mode. Make sure you substitute your own resource IDs when you follow this example. For example, if you execute `boundary roles create`, use the resource ID of the role in your 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 create a role in the generated org scope in [Boundary's `dev` mode](/boundary/docs/getting-started/dev-mode/dev-mode).
-
+
-```bash
-$ boundary roles create -scope-id o_1234567890 -name my_role -description "My first role"
+```shell-session
+$ boundary roles create -scope-id o_1234567890 -name list_all_resources -description "List all resources"
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
-```
-
-
-
-
-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.
-
-
-
-
-
-
-```hcl
-resource "boundary_scope" "role" {
- name = "my_role"
- description = "My first role!"
- scope_id = o_1234567890
-}
-```
-
-
-
-
-# Assign Principals to a Role
-
-Users and groups are granted 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
+ Created Time: Thu, 25 Jul 2024 17:21:22 MDT
+ Description: List all resources
+ Grant Scope ID: this
+ ID: r_22sVJoKZj3
+ Name: list_all_resources
+ Updated Time: Thu, 25 Jul 2024 17:21:22 MDT
Version: 2
Scope:
@@ -94,60 +47,111 @@ Role information:
Parent Scope ID: global
Type: org
- Principals:
- ID: u_gAv6YgVtVs
- Type: user
- Scope ID: o_1234567890
+ Authorized Actions:
+ add-principals
+ set-grants
+ remove-grants
+ no-op
+ remove-principals
+ set-grant-scopes
+ read
+ update
+ add-grant-scopes
+ delete
+ add-grants
+ set-principals
+ remove-grant-scopes
+
+ Grant Scope IDs:
+ ID: this
```
-
+
-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.
+Complete the following steps in the Boundary Admin UI.
-
+1. Log in to Boundary.
+1. Navigate to an org, then select **Roles** on the navigation pane.
+1. Click the **New** button.
+1. Fill in the role details, including the name `List all resources`.
+1. Click **Save**. You are then directed to the role's **Settings** page.
+
+
+
-
+
+
+Before you create a role, ensure that the principals you want to assign to the role exist.
+
+For example, to create an org, project, user, and a group in an org scope, use the following resources:
```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.
+resource "boundary_scope" "org" {
+ name = "org_one"
+ description = "My org scope"
+ scope_id = "global"
+ auto_create_admin_role = true
+ auto_create_default_role = true
+}
+
+resource "boundary_scope" "project" {
+ name = "project_one"
+ description = "My project scope"
+ scope_id = boundary_scope.org.id
+ auto_create_admin_role = true
+}
+
+resource "boundary_user" "foo" {
+ name = "Foo user"
+ scope_id = boundary_scope.org.id
+}
+
+resource "boundary_group" "bar" {
+ name = "Bar group"
+ scope_id = boundary_scope.org.id
+}
+```
+
+Next, add the `boundary_role` resource, adding the org scope for `scope_id`:
+
+```hcl
+resource "boundary_role" "listonly" {
+ name = "listonly"
+ description = "A list only role"
+ scope_id = boundary_scope.org.id
}
```
-# Assign Grants to a Role
+## Assign principals 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](/boundary/docs/concepts/security/permissions#permission-grant-formats).
-In this example we give a role read and list permissions to all resources.
+You can grant users, groups, and managed groups permissions to perform actions by assigning them as a role principal.
-
+
-```bash
-boundary roles add-grants -id $role_id -grant 'ids=*;type=*;actions=no-op,list'
+Examples of principal IDs include:
+
+- User: `u_tfRrCUIpGH`
+- Group: `g_qu2V5QMGQD`
+- Managed group: `mgldap_98UNHEqtmD`
+
+The following example adds a group as a role principal.
+
+```shell-session
+$ boundary roles add-principals -id r_22sVJoKZj3 -principal g_qu2V5QMGQD
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
+ Created Time: Thu, 25 Jul 2024 17:21:22 MDT
+ Description: List all resources
+ Grant Scope ID: this
+ ID: r_22sVJoKZj3
+ Name: list_all_resources
+ Updated Time: Thu, 25 Jul 2024 17:33:33 MDT
Version: 3
Scope:
@@ -156,55 +160,259 @@ Role information:
Parent Scope ID: global
Type: org
+ Authorized Actions:
+ set-grant-scopes
+ no-op
+ read
+ update
+ set-principals
+ add-principals
+ set-grants
+ remove-principals
+ remove-grant-scopes
+ delete
+ add-grants
+ add-grant-scopes
+ remove-grants
+
Principals:
- ID: u_gAv6YgVtVs
- Type: user
- Scope ID: o_1234567890
-
- Canonical Grants:
- id=*;type=*;actions=list,no-op
+ ID: g_qu2V5QMGQD
+ Type: group
+ Scope ID: global
+ Grant Scope IDs:
+ ID: this
```
-
+
-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.
+1. Log in to Boundary.
+1. Select **Roles** in the navigation pane, and then select the role you want to assign principals to.
+1. From the role's **Setting** page, click on the **Principals** tab.
+1. Click the **Add Principals** button, or select it from the **Manage** dropdown.
+1. Select one or more users, groups, or managed groups to associate with the role.
+1. Click the **Add Principals** button. The role's **Principals** page should now show the principals you selected before.
-
-
-1. From the role edit form, navigate to the **Grant Scope** section.
-1. Select a scope.
-1. Choose **Save** to commit your grant changes.
-
-
+
+
+
-
+You can assign principals with the `principal_ids` attribute.
+
+The following example adds the `boundary_user.foo` and `boundary_group.bar` principals to the role.
```hcl
-resource "boundary_scope" "role" {
- name = "my_role"
- description = "My first role!"
- scope_id = o_1234567890
- principals = u_1234567890
- grants = ["ids=*;type=*;action=read,list"]
+resource "boundary_role" "listonly" {
+ name = "listonly"
+ description = "A list only role"
+ principal_ids = [boundary_user.foo.id,boundary_group.bar.id]
+ scope_id = boundary_scope.org.id
}
```
+
+## Assign grants to a role
+
+Grants describe the actions that the principals are allowed to perform. For more information on how to format grants, refer to [Permission grant formats](/boundary/docs/configuration/identity-access-management/permission-grant-formats).
+
+In this example, we give a role read and list permissions for all resources. The grant we apply for the role is:
+
+```text
+ids=*;type=*;actions=no-op,list
+```
+
+The `no-op` action enables users that don't have any other assigned permissions, like read or update, the ability to list resources they cannot take any actions on.
+
+
+
+
+```shell-session
+$ boundary roles add-grants -id r_22sVJoKZj3 -grant 'ids=*;type=*;actions=no-op,list'
+
+Role information:
+ Created Time: Thu, 25 Jul 2024 17:21:22 MDT
+ Description: List all resources
+ Grant Scope ID: this
+ ID: r_22sVJoKZj3
+ Name: list_all_resources
+ Updated Time: Thu, 25 Jul 2024 17:42:46 MDT
+ Version: 4
+
+ Scope:
+ ID: o_1234567890
+ Name: Generated org scope
+ Parent Scope ID: global
+ Type: org
+
+ Authorized Actions:
+ remove-grant-scopes
+ add-grants
+ add-grant-scopes
+ delete
+ add-principals
+ set-grant-scopes
+ set-principals
+ remove-principals
+ set-grants
+ remove-grants
+ no-op
+ read
+ update
+
+ Principals:
+ ID: g_qu2V5QMGQD
+ Type: group
+ Scope ID: global
+
+ Canonical Grants:
+ ids=*;type=*;actions=list,no-op
+
+ Grant Scope IDs:
+ ID: this
+```
+
+
+
+
+1. Log in to Boundary.
+1. Select **Roles** in the navigation pane, and the select the role you want to assign grants to.
+1. From the role's **Settings** page, click on the **Grants** tab.
+1. In the **New Grant** field, paste in the example grant: `ids=*;type=*;actions=no-op,list`
+1. Click **Add**.
+1. Click **Save** to commit your grant changes.
+
+
+
+
+
+
+
+You assign grants using the `grant_strings` attribute.
+
+```hcl
+resource "boundary_role" "listonly" {
+ name = "listonly"
+ description = "A list only role"
+ principal_ids = [boundary_user.foo.id,boundary_group.bar.id]
+ grant_strings = ["ids=*;type=*;actions=no-op,list"]
+ scope_id = boundary_scope.org.id
+}
+```
+
+
+
+
+## Add grant scopes
+
+You can assign roles to multiple scopes and configure role inheritance.
+
+Role can have a combination of the following grant scope IDs:
+
+- `this` (this scope)
+- `children` (all direct children of the assigned scope, `global` and org scopes only)
+- `descendants` (all descendants of a scope, `global only`)
+- ID (such as `o_v2MpV4vBHN` or `p_0vfvaQPwhD`. Roles accept multiple grant scope IDs)
+
+Boundary automatically assigns grants the `this` scope, when you create them.
+
+
+
+
+The following command adds the IDs of a project scope and the direct children of the role's scope to the role. This includes projects within `o_1234567890` in this example.
+
+```shell-session
+$ boundary roles add-grant-scopes -id r_22sVJoKZj3 -grant-scope-id "p_1234567890" -grant-scope-id "children"
+
+Role information:
+ Created Time: Thu, 25 Jul 2024 17:21:22 MDT
+ Description: List all resources
+ ID: r_22sVJoKZj3
+ Name: list_all_resources
+ Updated Time: Thu, 25 Jul 2024 18:06:08 MDT
+ Version: 6
+
+ Scope:
+ ID: o_1234567890
+ Name: Generated org scope
+ Parent Scope ID: global
+ Type: org
+
+ Authorized Actions:
+ remove-principals
+ set-grants
+ remove-grants
+ delete
+ add-principals
+ add-grants
+ set-grant-scopes
+ set-principals
+ add-grant-scopes
+ no-op
+ read
+ update
+ remove-grant-scopes
+
+ Principals:
+ ID: g_qu2V5QMGQD
+ Type: group
+ Scope ID: global
+
+ Canonical Grants:
+ ids=*;type=*;actions=list,no-op
+
+ Grant Scope IDs:
+ ID: children
+ ID: p_1234567890
+ ID: this
+```
+
+
+
+
+1. Log in to Boundary.
+1. Select **Roles** in the navigation pane, and then select the role.
+1. Click on the **Scopes** tab. The `this` scope will already be applied to the grant.
+1. From the **Manage** dropdown, click **Manage Scopes**.
+1. Click **Manage custom scopes**.
+1. Select any additional scopes that you want to assign this grant, such as `p_1234567890` in Boundary's `dev` mode.
+
+ The settings you define for the role's children or descendants will apply to any scope you assign to this role.
+
+1. Click **Apply changes to org**.
+1. Toggle the switch beside **Add all children**.
+1. Click **Save**. The selected scope IDs and `children` are listed under the **Scopes** tab.
+
+
+
+
+
+
+
+You can declare scope inheritance with the `grant_scope_ids` attribute.
+
+The following example adds the assigned scope's ID with `this`, the ID of a project scope, and the direct children of the role's scope to the role. This includes projects within `org_one` in this example.
+
+```hcl
+resource "boundary_role" "listonly" {
+ name = "listonly"
+ description = "A list only role"
+ principal_ids = [boundary_user.foo.id,boundary_group.bar.id]
+ grant_strings = ["ids=*;type=*;actions=no-op,list"]
+ scope_id = boundary_scope.org.id
+ grant_scope_ids = ["this",boundary_scope.project.id,"children"]
+}
+```
+
+
+
+
+## More information
+
+1. Refer to [Assignable permissions](/boundary/docs/configuration/identity-access-management/assignable-permissions) for more information about the permissions you can assign to Boundary principals.
+1. Refer to [Permission grant formats](/boundary/docs/configuration/identity-access-management/permission-grant-formats) for more information about grant strings and example formats.
+1. Refer to the [Resource table](/boundary/docs/configuration/identity-access-management/resource-table) for a cheat sheet to help you manage your permissions.
diff --git a/website/content/docs/concepts/security/permissions/assignable-permissions.mdx b/website/content/docs/concepts/security/permissions/assignable-permissions.mdx
deleted file mode 100644
index b735dc4bc..000000000
--- a/website/content/docs/concepts/security/permissions/assignable-permissions.mdx
+++ /dev/null
@@ -1,137 +0,0 @@
----
-layout: docs
-page_title: Assignable permissions
-description: |-
- Assignable permissions
----
-
-# Assignable permissions
-
-Resources identified by the ID/Type selectors have permissions granted to the
-user in the form of actions and visibility (via `output_fields`). Each of these
-is detailed in the subsections below.
-
-## Actions
-
-Actions convey the ability to perform some action against a resource or
-collection. Many of these are common CRUD actions (`create`, `read`, `update`,
-`delete`) but many resources also specify actions specific to their type; for
-instance, a `target` has an `authorize-session` action to allow you to request
-making a connection to that target, and `auth-method` resources have an
-`authenticate` action to allow you to authenticate to Boundary. For the most
-part these are straightforward, however there are a couple of special cases to
-know.
-
-### Subactions
-
-Some subactions are supported. These actions have a format
-`top_level_action:subaction`, such as `read:self`. Being granted the top level
-action infers being granted all subactions. Thus, if a grant conveys `read`, it
-also matches the API actions `read` and `read:self`. However, if a grant conveys
-`read:self`, it will match the API action `read:self` but will not match `read`.
-
-### The `no-op` action and listing visibility
-
-There is an action that can be granted called `no-op`. As might be apparent,
-`no-op` is not used for any real action in Boundary; the purpose of this action
-is for listing visibility. Boundary only shows resources in the output of a
-`list` action for which a user has at least one granted action. Thus, without
-`no-op`, in order for a resource to be visible in a `list` action, a different
-action such as `read` would have to be granted to a user. This could result in
-exposing more information than desired, especially in the case of listing scopes
-and authentication methods so that users can perform initial authentication to
-Boundary (that is, granting access to `u_anon`).
-
-By granting the `no-op` action to users, they can see the resources in the
-output of a list command without needing other capability grants as well.
-
-## Anonymous user restrictions
-
-Starting in Boundary 0.9.0, there are severe limits placed on the actions
-allowed to be assigned to the anonymous user `u_anon`. This is meant to avoid
-situations where an operator accidentally or mistakenly adds the anonymous user
-to a role that provides more privileges than might be intended for
-unauthenticated users.
-
-The set of actions is currently restricted to listing scopes and auth methods
-and authentication to auth methods (plus `no-op` actions for listing
-visibility). If further use-cases arise from user feedback this list can be
-expanded.
-
-Note: there is no special error message returned when access is denied due to it
-being disallowed to the anonymous user. It is still possible to assign grants to
-a role on which the anonymous user is a principal that can never match the
-anonymous user. In the future this may change, but trying to limit this
-introduces other restrictions on reasonable administrative workflows so an
-acceptable set of tradeoffs would need to be figured out.
-
-## Output fields
-
-Grant strings can contain an `output_fields` field. This allows fine-grained
-control over visibility of data returned to users.
-
-In many cases, `output_fields` will not need to be set directly. However, an
-example in the form of some history helps provide some context as to when this
-might be useful.
-
-In Boundary 0.2.0, we restricted the set of fields returned for some `list`
-calls (those on the `scopes` and `auth-methods` collections) to a small set if
-the user was the anonymous user `u_anon`. Although default behavior in Boundary
-was to display all resource fields when listing, because the default was also to
-allow anonymous access to perform `list` on scopes and auth methods (in order to
-discover auth methods and then authenticate to them), returning all
-configuration information for all scopes and auth methods felt like it was
-publicly disclosing more information to users than might be desired.
-
-At the same time, this was not an ideal solution for two reasons:
-
-1. There is no one-size-fits-all security policy, and what we thought were
- reasonable defaults may not work in all situations
-
-2. It made the scopes and auth methods listing behavior work differently from
- any other `list` action, which is not ideal
-
-As a result, we decided to approach this problem the same way we normally try to
-within Boundary: set resonable defaults, but give the administrator ultimate
-control.
-
-The resulting behavior is as follows: `output_fields` references the field names
-of the JSON object response, composes just like other parts of the RBAC model,
-and are action-specific. That is, a grant like:
-
-`ids=*;type=auth-methods;actions=list,no-op;output_fields=scope_id,name,description`
-
-will, if all by itself, result in those three identified output fields applying
-to `list` (and `no-op`) actions for all auth methods in the scope. Thus when
-performing a `list`, each item returned will have only those three fields
-populated. Any other actions (like `read` or `update`) are unaffected and will
-use defaults.
-
-A grant like:
-
-`ids=*;type=auth-methods;output_fields=id`
-
-will, if all by itself, result in _any_ action against auth methods in the scope
-having only `id` returned.
-
-However, if both of the above grants are included, since grants are composable
-the final set of output fields will be `id,scope_id,name,description` for `list`
-(and `no-op`) actions, and `id` for all other actions.
-
-If, after the grants are composed for a given request, none of the grants
-applicable to the resource/action contain `output_fields` definitions, the
-defaults are used. These defaults are implemented using internal values for
-`output_fields` and vary based on whether the user is the anonymous user:
-
-- If the user is the anonymous user, a useful but restricted set of fields is
- returned. This includes `id`, `scope_id`, `scope`, `name`, `description`, and a
- few more.
-
-- If the user is any authenticated user, the full set of fields is returned
-
-To think about it a different way, empty `output_fields`, after grant
-composition, is equivalent to using Boundary's default; however the moment that
-grants start specifying output fields, it is composed from an empty set and thus
-nothing is contained unless explicitly specified. (An actual empty set is not
-currently supported, as we don't perform validation on the values given.
-However, this means setting `output_fields=none` is functionally equivalent!)
diff --git a/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx b/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx
deleted file mode 100644
index fb3c9247b..000000000
--- a/website/content/docs/concepts/security/permissions/permission-grant-formats.mdx
+++ /dev/null
@@ -1,130 +0,0 @@
----
-layout: docs
-page_title: Permission grant formats
-description: |-
- Permission grant formats
----
-
-# Permission grant formats
-
-Because of the aforementioned properties of the permissions model, grants are
-relatively simple. All grants take one of four forms. These examples use the
-canonical string syntax; the JSON equivalents are simply an object with a string
-`id` value, a string `type` value, a string array `actions` value, and a string
-array `output_fields` value.
-
-~> `output_fields` is omitted in most example below for brevity but are valid
-in all of them. It is also valid in each case to omit `actions` and specify
-_only_ `output_fields`.
-
-## ID only
-
-This is the simplest form: for a given specific resource, allow these actions.
-Example:
-
-`ids=hsst_1234567890;actions=read,update`
-
-This grants `read` and `update` actions to that single resource. It is invalid
-to specify `create` or `list` as actions in this format, as this format
-explicitly identifies a resource, whereas those actions operate exclusively on
-collections.
-
-## Type only
-
-For a given type, allow these actions. Example:
-
-`type=host-catalog;actions=create,list`
-
-Because type specifies only a collection as opposed to specific resources within
-that collection, only collection actions are allowed in this format. Currently,
-this is `create` and `list`.
-
-There is one additional restriction: this is only valid against "top-level"
-resource types, which currently are:
-
-- Auth Methods
-- Auth Tokens
-- Groups
-- Host Catalogs
-- Roles
-- Scopes
-- Sessions
-- Targets
-- Users
-
-The reason for this is that other types of resources are contained within one of
-these resource types; for instance, accounts are instantiated within an auth
-method. To specify actions against those, you must also specify to which
-specific containing resource you want the grants to apply. This can be done with
-the pinned format shown below.
-
-## Pinned ID
-
-This form "pins" actions to a non-top-level type within a specific ID. It's
-easiest to explain with an example:
-
-`ids=hcst_1234567890;type=host-set;actions=create,read,update`
-
-In this example, the user is able to create, read, or update host sets within
-the scope, but _only the host sets belonging to host catalog hcst_1234567890_.
-Pinning is essentially a way to use top-level resources to create mini
-permission boundaries for their subordinate resources.
-
-## Wildcards
-
-Various wildcard possibilities are allowed:
-
-### Wildcard ID
-
-When just the ID is `*`, it matches all IDs of the given type. This can be used
-with both top-level resource types and not. Example:
-
-`ids=*;type=host-set;actions=create,read,update,set-hosts`
-
-### Wildcard type
-
-For non-top-level resources with pinned IDs, the `type` can be a wildcard:
-
-`ids=hcst_1234567890;type=*;actions=create,read,update`
-
-This would allow `create`, `read`, and `update` actions for all types of
-subordinate resources (in this case host sets and hosts) underneath the host
-catalog with ID `hcst_1234567890`.
-
-### Wildcard ID and type
-
-If ID and type are both a wildcard, the grant is essentially a catch-all that
-will match any resource of any type within the scope and allow the given
-actions.
-
-`ids=*;type=*;actions=read,list`
-
-### Wildcard ID, type, and actions
-
-Finally, ID, type, and actions can all be wildcards:
-
-`ids=*;type=*;actions=*`
-
-Such a grant is essentially a full administrator grant for a scope.
-
-## Templates
-
-A few template possibilities exist, which will at grant evaluation time
-substitute the given value into the ID field of the grant string:
-
-- `{{.Account.Id}}`: The substituted value is the account ID associated with the
- token used to perform the action. As an example,
- `ids={{.Account.Id}};actions=read,change-password"` is one of Boundary's
- default grants to allow users that have authenticated with the Password auth
- method to change their own password.
- - **NOTE**: Prior to Boundary 0.11.1, `{{account.id}}` must be used instead.
- Boundary 0.11.1+ changes this for consistency with other places within
- Boundary that are gaining templating support, but supports both formats for
- backwards compatibility.
-
-- `{{.User.Id}}`: The substituted value is the user ID associated with the token
- used to perform the action.
- - **NOTE**: Prior to Boundary 0.11.1, `{{user.id}}` must be used instead.
- Boundary 0.11.1+ changes this for consistency with other places within
- Boundary that are gaining templating support, but supports both formats for
- backwards compatibility.
diff --git a/website/content/docs/configuration/identity-access-management/assignable-permissions.mdx b/website/content/docs/configuration/identity-access-management/assignable-permissions.mdx
new file mode 100644
index 000000000..a7100acc2
--- /dev/null
+++ b/website/content/docs/configuration/identity-access-management/assignable-permissions.mdx
@@ -0,0 +1,104 @@
+---
+layout: docs
+page_title: Assignable permissions
+description: |-
+ Assignable permissions
+---
+
+# Assignable permissions
+
+You can grant users permissions to any Boundary resources that are identified by ID or Type selectors.
+There are two types of assigned permissions:
+
+- An `actions` field indicating which actions to allow the client to perform on
+ the resources matched by `id` and `type`
+- An `output_fields` field indicating which top-level fields to return in the
+ response.
+
+## Actions
+
+Actions convey the ability to perform some operation against a resource or
+collection.
+They include common CRUD operations (`create`, `read`, `update`,
+`delete`), but some resources also have actions that are specific to their type.
+
+For example, a `target` has an `authorize-session` action that allows you to request
+making a connection to that target.
+The `auth-method` resources have an `authenticate` action that allows you to authenticate to Boundary.
+Most actions represent common operations, however there are some special cases to note.
+
+### Subactions
+
+Some subactions are also supported. Subactions have a format
+`top_level_action:subaction`, such as `read:self`.
+When you grant a top level action to a principal, they also inherit all subactions.
+
+For example, if a grant conveys `read`, it also matches the API actions `read` and `read:self`.
+However, if a grant conveys `read:self`, it does not grant the top-level action `read`.
+
+### The `no-op` action and listing visibility
+
+Boundary contains a `no-op` action that is not used for any real operations.
+However, you can use the `no-op` action for listing visibility.
+
+When a user runs a `list` operation, Boundary only shows the resources for which a user has been granted at least one action.
+Without the `no-op` action, you would have to grant the user another action such as `read` to ensure they could view the resource.
+Granting additional actions to users could result in exposing more information to the user than intended.
+This is especially true for listing scopes and authentication methods, such as when users perform the initial authentication to Boundary.
+
+Instead, you can grant the `no-op` action to users to ensure that they can view the output of a list command, without granting them other unnecessary actions.
+
+### Anonymous user restrictions
+
+There are limits to the actions that you can assign to the anonymous user `u_anon`.
+The limitations are meant to prevent you from accidentally adding the anonymous user to a role that provides more privileges than you would intend to grant to an unauthenticated user.
+
+For anonymous users, actions are restricted to listing scopes and auth methods,
+and authentication to auth methods.
+You can also grant the `no-op` action for listing visibility.
+
+Boundary does not return a special error message when access is denied to an action because it is not allowed for an anonymous user.
+You can still assign grants to a role on which the anonymous user is a principal, but they can never match the anonymous user.
+
+## Output fields
+
+Grant strings can contain an `output_fields` value. This setting gives you fine-grained
+control over the visibility of data returned to users.
+
+The `output_fields` reference the field names of the JSON object reponse.
+They are composed just like other parts of the RBAC model, and are action-specific.
+For example, the following grant:
+
+`ids=*;type=auth-methods;actions=list,no-op;output_fields=scope_id,name,description`
+
+results in the three identified output fields (scope ID, name, and description) applying to any `list` and `no-op` actions for all auth methods in the scope.
+If a user performed a `list` operation under this example grant, each item returned would only have the three fields populated: `scope_id`, `name`, and `description`.
+Any other actions, such as `read` or `update`, would be unaffected and would return the default information.
+
+This grant:
+
+`ids=*;type=auth-methods;output_fields=id`
+
+means that only the `id` will be returned for any action performed against auth methods in this scope.
+
+Grants are composable.
+Therefore, if both of the example grants above are added, the final set of output fields would be `id`, `scope_id`, `name`, and `description` for the `list` and `no-op` actions.
+For all other actions, the output field would be `id`.
+
+### Default output fields
+
+If none of the grants applicable to the resource or action for a given request contain `output_fields` definitions, Boundary uses the default settings.
+The default settings vary based on whether the user is anonymous:
+
+- If the user is anonymous, Boundary returns a restricted set of fields.
+They include `id`, `scope_id`, `scope`, `name`, and `description`.
+- If the user is authenticated, Boundary returns the full set of fields.
+
+## More information
+
+1. Refer to [Permission grant formats](/boundary/docs/configuration/identity-access-management/permission-grant-formats) for more information about grant strings and example formats.
+1. Refer to the [Resource table](/boundary/docs/configuration/identity-access-management/resource-table) for a cheat sheet to help you manage your permissions.
+
+## Next steps
+
+Refer to [Manage roles and permissions](/boundary/docs/common-workflows/manage-roles) for instructions to configure roles and grant scopes for principals.
diff --git a/website/content/docs/concepts/security/permissions/index.mdx b/website/content/docs/configuration/identity-access-management/index.mdx
similarity index 57%
rename from website/content/docs/concepts/security/permissions/index.mdx
rename to website/content/docs/configuration/identity-access-management/index.mdx
index 063f1e122..db15d7abe 100644
--- a/website/content/docs/concepts/security/permissions/index.mdx
+++ b/website/content/docs/configuration/identity-access-management/index.mdx
@@ -8,56 +8,48 @@ description: |-
# Permissions in Boundary
Boundary's permissions model is a composable, RBAC, allow-only model that
-attempts to marry flexibility with usability. This page discusses the permission
-model's fundamental concepts, provides examples of the specific forms of allowed
-grants, and contains a table that acts as an easy cheat sheet to help those new
-to its grant syntax with crafting roles.
+attempts to marry flexibility with usability.
+The following pages discuss the permission model's fundamental concepts, provide examples of the specific forms of allowed grants, and contain a table that acts as a cheat sheet to help you craft roles.
Boundary's [domain model](/boundary/docs/concepts/domain-model) is based on resource
-types. These can be implemented directly, such as with targets, or they can be
-abstract types that are implemented by concrete types within the system. As an
-example of the latter, a host catalog is an abstract type and a Static host
+types. You can implement resource types directly, such as with targets, or they can be
+abstract types that you implement using concrete types within the system. As an
+example of the latter, a host catalog is an abstract type and a static host
catalog is a concrete type.
From a permissions standpoint, all actions take place against directly
implemented or abstract types. There may be actions that are only implemented by
-some concrete types (e.g., not all `auth-method` implementations will support a
-`change-password` action), but the permissions model still defines these
-capabilities at the abstract type level. This helps keep the overall system
-relatively simple and predictable.
+some concrete types, for example, not all `auth-method` implementations support a
+`change-password` action. But the permissions model still defines these
+capabilities at the abstract type level.
At a very high level, permissions within Boundary are declared via grant strings
and mapped to users via roles.
## Grant strings
+Each grant string is a mapping that describes a resource or set of resources and
+the permissions that should be granted on them.
+
A grant string has a form similar to:
`ids=;type=;actions=;output_fields=`
-Each grant string is a mapping that describes a resource or set of resources and
-the permissions that should be granted on them.
+Selectors are used to indicate the resources on which the grant should apply,
+using specific IDs or wildcard IDs and type selectors.
-There are currently two types of selectors:
+You can supply grant strings using a human-friendly string syntax or using JSON.
-- An `id` field that indicates a specific resource or a wildcard to match all
+### Assigned permissions
-- A `type` field that indicates a specific resource type or a wildcard to match
- all; this might also be used to grant permissions on collections of resources
-
-Selectors are used to indicate which resources on which the grant should apply,
-using specific IDs or wildcard IDs and type selectors. (The acceptable grant
-string formats are detailed later on this page.)
-
-Additionally, there are two types of assigned permissions:
+You can grant users permissions to any Boundary resources that are identified by ID or Type selectors.
+There are two types of assigned permissions:
- An `actions` field indicating which actions to allow the client to perform on
the resources matched by `id` and `type`
- An `output_fields` field indicating which top-level fields to return in the
- response (0.2.1+)
-
-Grant strings can be supplied via a human-friendly string syntax or via JSON.
+ response.
## Roles
@@ -65,7 +57,7 @@ Roles map grant strings to principals, which are users, groups, and managed grou
Every role assigns grants within a scope, as determined by the role's grant scope IDs.
You can assign roles to multiple scopes to grant permissions to users who need access to resources across multiple scopes.
-You can also configure child scopes to inherit roles from parents.
+Child scopes can inherit roles from parents.
For example, the global scope could have multiple child scopes called "orgs".
When you create a role in the global scope, you can configure it to apply to those children org scopes.
@@ -76,14 +68,18 @@ A role provides grants for a request if the grant scope ID matches the request's
scope ID and one or more of the following are true:
- The user's ID is contained in the principal IDs set on the role
-
- A group the user belongs to is contained in the principal IDs set on the role
-
- The user is logged in and the `u_auth` user is contained in the principal IDs
set on the role
-
- The role contains the `u_anon` user in the in the principal IDs set on the
role
Roles are composable; a user's final set of grants will be composed of grants
that originate from all matching roles.
+
+## Next steps
+
+1. Refer to [Assignable permissions](/boundary/docs/configuration/identity-access-management/assignable-permissions) for more information about the permissions you can assign to Boundary principals.
+1. Refer to [Permission grant formats](/boundary/docs/configuration/identity-access-management/permission-grant-formats) for more information about grant strings and example formats.
+1. Refer to [Manage roles and permissions](/boundary/docs/common-workflows/manage-roles) for instructions to configure roles and grant scopes for principals.
+1. Refer to the [Resource table](/boundary/docs/configuration/identity-access-management/resource-table) for a cheat sheet to help you manage your permissions.
\ No newline at end of file
diff --git a/website/content/docs/configuration/identity-access-management/permission-grant-formats.mdx b/website/content/docs/configuration/identity-access-management/permission-grant-formats.mdx
new file mode 100644
index 000000000..d7ad3599f
--- /dev/null
+++ b/website/content/docs/configuration/identity-access-management/permission-grant-formats.mdx
@@ -0,0 +1,151 @@
+---
+layout: docs
+page_title: Permission grant formats
+description: |-
+ Permission grant formats
+---
+
+# Permission grant formats
+
+Each grant string is a mapping that describes a resource or set of resources and
+the permissions that should be granted on them.
+
+Refer to [Assignable permissons](/boundary/docs/configuration/identity-access-management/assignable-permissions) for more information about the permissions you can include in grants.
+
+A grant string has a form similar to:
+
+`ids=;type=;actions=;output_fields=`
+
+There are two types of selectors:
+
+- An `id` field that indicates a specific resource or a wildcard to match all
+- A `type` field that indicates a specific resource type or a wildcard to match
+ all; this might also be used to grant permissions on collections of resources
+
+Selectors are used to indicate the resources on which the grant should apply,
+using specific IDs or wildcard IDs and type selectors.
+
+You can supply grant strings using a human-friendly string syntax or using JSON.
+The following examples use the canonical string syntax.
+The JSON equivalents are an object with a string `id` value, a string `type` value, a string array `actions` value, and a string array `output_fields` value.
+
+In the following examples, `output_fields` is omitted for brevity, but they are valid for each example.
+It is also valid to omit `actions` and specify only `output_fields`.
+
+## ID only
+
+The simplest form of grant allows the specified actions for a given resource.
+Refer to the following example:
+
+`ids=hsst_1234567890;actions=read,update`
+
+This example grants `read` and `update` actions to the resource `hsst_1234567890`. It is invalid
+to specify `create` or `list` as actions in this format, because this format
+explicitly identifies a resource.
+The `create` and `list` actions are only supported for collections.
+
+## Type only
+
+You can configure a grant to allow the specified actions for a given type.
+Refer to the following example:
+
+`type=host-catalog;actions=create,list`
+
+Because type specifies only a collection as opposed to specific resources within
+that collection, only collection actions are allowed in this format. Currently,
+this includes the `create` and `list` actions.
+
+There is one additional restriction: this grant format is only valid against "top-level"
+resource types, which include:
+
+- Auth methods
+- Auth tokens
+- Groups
+- Host catalogs
+- Roles
+- Scopes
+- Sessions
+- Targets
+- Users
+
+The reason for this is that other types of resources are contained within one of
+these resource types.
+For example, accounts are instantiated within an auth
+method. To specify actions against an auth method, you must also specify the
+specific containing resource you want to apply the grants to.
+You can update those resources using the pinned format shown below.
+
+## Pinned ID
+
+This form "pins" actions to a non-top-level type within a specific ID.
+Refer to the following example:
+
+`ids=hcst_1234567890;type=host-set;actions=create,read,update`
+
+In this example, the user is able to create, read, or update host sets within
+the scope, but only the host sets belonging to host catalog `hcst_1234567890`.
+Pinning is essentially a way to use top-level resources to create mini
+permission boundaries for their subordinate resources.
+
+## Wildcards
+
+You can use wildcards in grants.
+Refer to the following sections for the various wildcard possibilities that are supported.
+
+### Wildcard ID
+
+When just the ID is `*`, it matches all IDs of the given type. You can use this grant format
+with both top-level resource types and non-top-level resource types.
+Refer to the following example:
+
+`ids=*;type=host-set;actions=create,read,update,set-hosts`
+
+### Wildcard type
+
+For non-top-level resources with pinned IDs, the `type` can be a wildcard.
+Refer to the following example:
+
+`ids=hcst_1234567890;type=*;actions=create,read,update`
+
+This grant format would allow `create`, `read`, and `update` actions for all types of
+subordinate resources underneath the host
+catalog with ID `hcst_1234567890`.
+In this example, that would include host sets and hosts.
+
+### Wildcard ID and type
+
+If the ID and type are both wildcards, the grant is essentially a catch-all that matches any resource of any type within the scope and allows the given actions.
+Refer to the following example:
+
+`ids=*;type=*;actions=read,list`
+
+### Wildcard ID, type, and actions
+
+ID, type, and actions can all be wildcards.
+Refer to the following example:
+
+`ids=*;type=*;actions=*`
+
+Such a grant is essentially a full administrator grant for a scope.
+
+## Templates
+
+A few template possibilities exist for grants.
+The following templates substitute a given value into the ID field of the grant string at evaluation time:
+
+- `{{.Account.Id}}`: The substituted value is the account ID associated with the
+ token used to perform the action. As an example,
+ `ids={{.Account.Id}};actions=read,change-password"` is one of Boundary's
+ default grants to allow users that have authenticated with the Password auth
+ method to change their own password.
+- `{{.User.Id}}`: The substituted value is the user ID associated with the token
+ used to perform the action.
+
+## More information
+
+1. Refer to [Assignable permissions](/boundary/docs/configuration/identity-access-management/assignable-permissions) for more information about the permissions you can assign to Boundary principals.
+1. Refer to the [Resource table](/boundary/docs/configuration/identity-access-management/resource-table) for a cheat sheet to help you manage your permissions.
+
+## Next steps
+
+Refer to [Manage roles and permissions](/boundary/docs/common-workflows/manage-roles) for instructions to configure roles and grant scopes for principals.
diff --git a/website/content/docs/concepts/security/permissions/resource-table.mdx b/website/content/docs/configuration/identity-access-management/resource-table.mdx
similarity index 99%
rename from website/content/docs/concepts/security/permissions/resource-table.mdx
rename to website/content/docs/configuration/identity-access-management/resource-table.mdx
index 629c37493..87ce7b630 100644
--- a/website/content/docs/concepts/security/permissions/resource-table.mdx
+++ b/website/content/docs/configuration/identity-access-management/resource-table.mdx
@@ -7,7 +7,7 @@ description: |-
# Resource tables
-The following tables work as a quick cheat-sheet to help you manage your
+The following tables work as a quick cheat sheet to help you manage your
permissions. Note that the tables are not exhaustive; for brevity they do _not_ show
wildcard or templated grant strings.
@@ -52,7 +52,7 @@ The **Account** resource type supports the following scopes: **Global**, **Org**
## Alias
-The **Alias** resource type supports the following scopes: **Global**, **Org**, **Project**
+The **Alias** resource type supports the following scopes: **Global**
| API endpoint | Parameters into permissions engine | Available actions / examples |
| ------------ | ---------------------------------- | ---------------------------- |
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index ea3ce9ba7..3e0d2010a 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -253,27 +253,6 @@
"title": "Overview",
"path": "concepts/security"
},
- {
- "title": "Permissions",
- "routes": [
- {
- "title": "Overview",
- "path": "concepts/security/permissions"
- },
- {
- "title": "Assignable permissions",
- "path": "concepts/security/permissions/assignable-permissions"
- },
- {
- "title": "Permission grant formats",
- "path": "concepts/security/permissions/permission-grant-formats"
- },
- {
- "title": "Resource tables",
- "path": "concepts/security/permissions/resource-table"
- }
- ]
- },
{
"title": "Data encryption",
"path": "concepts/security/data-encryption"
@@ -519,6 +498,31 @@
}
]
},
+ {
+ "title": "Identity and access management",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "configuration/identity-access-management"
+ },
+ {
+ "title": "Assignable permissions",
+ "path": "configuration/identity-access-management/assignable-permissions"
+ },
+ {
+ "title": "Permission grant formats",
+ "path": "configuration/identity-access-management/permission-grant-formats"
+ },
+ {
+ "title": "Manage roles",
+ "href": "common-workflows/manage-roles"
+ },
+ {
+ "title": "Resource table",
+ "path": "configuration/identity-access-management/resource-table"
+ }
+ ]
+ },
{
"title": "Session recordings",
"badge": {
diff --git a/website/public/img/ui/add-role-grant_dark.png b/website/public/img/ui/add-role-grant_dark.png
new file mode 100644
index 000000000..b1f1328b1
Binary files /dev/null and b/website/public/img/ui/add-role-grant_dark.png differ
diff --git a/website/public/img/ui/add-role-grant_light.png b/website/public/img/ui/add-role-grant_light.png
new file mode 100644
index 000000000..468cdf709
Binary files /dev/null and b/website/public/img/ui/add-role-grant_light.png differ
diff --git a/website/public/img/ui/add-role-principal_dark.png b/website/public/img/ui/add-role-principal_dark.png
new file mode 100644
index 000000000..f3a2a05ab
Binary files /dev/null and b/website/public/img/ui/add-role-principal_dark.png differ
diff --git a/website/public/img/ui/add-role-principal_light.png b/website/public/img/ui/add-role-principal_light.png
new file mode 100644
index 000000000..9b4ccb87b
Binary files /dev/null and b/website/public/img/ui/add-role-principal_light.png differ
diff --git a/website/public/img/ui/add-role-scopes_dark.png b/website/public/img/ui/add-role-scopes_dark.png
new file mode 100644
index 000000000..bc69074e7
Binary files /dev/null and b/website/public/img/ui/add-role-scopes_dark.png differ
diff --git a/website/public/img/ui/add-role-scopes_light.png b/website/public/img/ui/add-role-scopes_light.png
new file mode 100644
index 000000000..84fcd5cec
Binary files /dev/null and b/website/public/img/ui/add-role-scopes_light.png differ
diff --git a/website/public/img/ui/new-role_dark.png b/website/public/img/ui/new-role_dark.png
new file mode 100644
index 000000000..4a7ff6150
Binary files /dev/null and b/website/public/img/ui/new-role_dark.png differ
diff --git a/website/public/img/ui/new-role_light.png b/website/public/img/ui/new-role_light.png
new file mode 100644
index 000000000..76212b6e2
Binary files /dev/null and b/website/public/img/ui/new-role_light.png differ
diff --git a/website/redirects.js b/website/redirects.js
index 3b8818e60..12fd2a283 100644
--- a/website/redirects.js
+++ b/website/redirects.js
@@ -194,4 +194,24 @@ module.exports = [
destination: '/boundary/docs/configuration/worker/worker-configuration',
permanent: true,
},
+ {
+ source: '/boundary/docs/concepts/security/permissions/resource-table',
+ destination: '/boundary/docs/configuration/identity-access-management/resource-table',
+ permanent: true,
+ },
+ {
+ source: '/boundary/docs/concepts/security/permissions',
+ destination: '/boundary/docs/configuration/identity-access-management',
+ permanent: true,
+ },
+ {
+ source: '/boundary/docs/concepts/security/permissions/assignable-permissions',
+ destination: '/boundary/docs/configuration/identity-access-management/assignable-permisisons',
+ permanent: true,
+ },
+ {
+ source: '/boundary/docs/concepts/security/permissions/permission-grant-formats',
+ destination: '/boundary/docs/configuration/identity-access-management/permission-grant-formats',
+ permanent: true,
+ },
]