CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Move permissions to config for usage docs (#4962)

Browse Source 
* docs: Move permissions to config for usage docs

* docs: Update permissions concepts (#4970)

* docs: Update permissions concepts

* docs: Delete comments

* docs: Structural edits and adding workflow

* docs: Fix wording

* docs: Change guide name, add resource table

* Rab manage roles refactor (#4980)

* refreshes the manage-roles docs

* adds href for common-workflows/manage-roles to configuration/identity-access-management

* docs: Fix a couple typos

* docs: Style updates

* docs: Fix image links, update alt text

* docs: Add more info/next steps sections

* docs: Remove number for single instruction

* fixes screenshot

---------

Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>

* updates path to resource-table.mdx

* sets aliases scope to Global

* updates aliases scope in resource table

* clarifies assigned scope id

* Update website/redirects.js

Co-authored-by: Michael Li <michael.li@hashicorp.com>

---------

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
Co-authored-by: Robin Beck <stellarsquall@protonmail.ch>
Co-authored-by: Michael Li <michael.li@hashicorp.com>
This commit is contained in:
Dan HeathMichael LiRobin BeckRobin Beck
 authored and GitHub committed 2024-07-30 17:21:09 -04:00
1 parent af0e89c328
commit bbbe971ed1
18 files changed
+680 -464
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/website/permstable/permstable.go
+2 -2
View File
@@ -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,
website/content/docs/common-workflows/manage-roles.mdx
+350 -142
View File
@@ -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.
<Note>
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.
</Note>
## 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).
<Tabs>
<Tab heading="CLI">
<Tab heading="CLI" group="cli">
```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
```
</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
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
```
</Tab>
<Tab heading="Admin Console">
<Tab heading="Admin UI" group="ui">
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.
<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>
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.
![The Create a new role dialog lets you name and describe the new role.](/img/ui/new-role_light.png#light-theme-only)
![The Create a new role dialog lets you name and describe the new role.](/img/ui/new-role_dark.png#dark-theme-only)
</Tab>
<Tab heading="Terraform">
<Tab heading="Terraform" group="terraform">
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
}
```
</Tab>
</Tabs>
# 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.
<Tabs>
<Tab heading="CLI">
<Tab heading="CLI" group="cli">
```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
```
</Tab>
<Tab heading="Admin Console">
<Tab heading="Admin UI" group="ui">
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.
<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>
![The Principals tab lets you assign principals to a role.](/img/ui/add-role-principal_light.png#light-theme-only)
![The Principals tab lets you assign principals to a role.](/img/ui/add-role-principal_dark.png#dark-theme-only)
</Tab>
<Tab heading="Terraform" group="terraform">
<Tab heading="Terraform">
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
}
```
</Tab>
</Tabs>
## 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.
<Tabs>
<Tab heading="CLI" group="cli">
```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
```
</Tab>
<Tab heading="Admin UI" group="ui">
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.
![The Grants tab on the Roles page lets you add grants to principals.](/img/ui/add-role-grant_light.png#light-theme-only)
![The Grants tab on the Roles page lets you add grants to principals.](/img/ui/add-role-grant_dark.png#dark-theme-only)
</Tab>
<Tab heading="Terraform" group="terraform">
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
}
```
</Tab>
</Tabs>
## 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.
<Tabs>
<Tab heading="CLI" group="cli">
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
```
</Tab>
<Tab heading="Admin UI" group="ui">
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.
![The Manage Scopes dialog lets you customize which scopes are associated with a role.](/img/ui/add-role-scopes_light.png#light-theme-only)
![The Manage Scopes dialog lets you customize which scopes are associated with a role.](/img/ui/add-role-scopes_dark.png#dark-theme-only)
</Tab>
<Tab heading="Terraform" group="terraform">
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"]
}
```
</Tab>
</Tabs>
## 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.
website/content/docs/concepts/security/permissions/assignable-permissions.mdx
-137
View File
@@ -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!)
website/content/docs/concepts/security/permissions/permission-grant-formats.mdx
-130
View File
@@ -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.
website/content/docs/configuration/identity-access-management/assignable-permissions.mdx
+104
View File
@@ -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.
website/content/docs/concepts/security/permissions/index.mdx → website/content/docs/configuration/identity-access-management/index.mdx
+26 -30
View File
@@ -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=<id>;type=<type>;actions=<action list>;output_fields=<fields list>`
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.
website/content/docs/configuration/identity-access-management/permission-grant-formats.mdx
+151
View File
@@ -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=<id>;type=<type>;actions=<action list>;output_fields=<fields list>`
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.
website/content/docs/concepts/security/permissions/resource-table.mdx → website/content/docs/configuration/identity-access-management/resource-table.mdx
+2 -2
View File
@@ -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 |
| ------------ | ---------------------------------- | ---------------------------- |
website/data/docs-nav-data.json
+25 -21
View File
@@ -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": {
website/public/img/ui/add-role-grant_dark.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

website/public/img/ui/add-role-grant_light.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

website/public/img/ui/add-role-principal_dark.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

website/public/img/ui/add-role-principal_light.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

website/public/img/ui/add-role-scopes_dark.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

website/public/img/ui/add-role-scopes_light.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

website/public/img/ui/new-role_dark.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 69 KiB

website/public/img/ui/new-role_light.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 67 KiB

website/redirects.js
+20
View File
@@ -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,
},
]