diff --git a/website/content/docs/concepts/domain-model/accounts.mdx b/website/content/docs/concepts/domain-model/accounts.mdx index 5d8a075a16..4944ac8b63 100644 --- a/website/content/docs/concepts/domain-model/accounts.mdx +++ b/website/content/docs/concepts/domain-model/accounts.mdx @@ -39,9 +39,11 @@ Password account types have the following additional attributes: ## Referenced By - [Auth Method][] +- [Managed Group][] - [User][] [auth method]: /docs/concepts/domain-model/auth-methods +[managed group]: /docs/concepts/domain-model/managed-groups [user]: /docs/concepts/domain-model/users ## Service API Docs diff --git a/website/content/docs/concepts/domain-model/auth-methods.mdx b/website/content/docs/concepts/domain-model/auth-methods.mdx index 34eee86af6..2d291ac52b 100644 --- a/website/content/docs/concepts/domain-model/auth-methods.mdx +++ b/website/content/docs/concepts/domain-model/auth-methods.mdx @@ -7,12 +7,12 @@ description: |- # Auth Methods -An auth method is a resource -that provides a mechanism -for [users][] to authenticate to Boundary. -An auth method contains [accounts][] -which link an individual user to a set of credentials. -Auth methods can be defined at either a [Global][] or [Organization][] [scope][]. +An auth method is a resource that provides a mechanism for [users][] to +authenticate to Boundary. An auth method contains [accounts][] which link an +individual user to a set of credentials and [managed groups][] which groups +[accounts][] that satisfy criteria and can be used as principals in [roles][]. +Auth methods can be defined at either a [Global][] or [Organization][] +[scope][]. ## Attributes @@ -35,12 +35,16 @@ The password auth method has the following additional attributes: - [Account][] - [Global][] +- [Managed Group][] - [Organization][] [account]: /docs/concepts/domain-model/accounts [accounts]: /docs/concepts/domain-model/accounts [global]: /docs/concepts/domain-model/scopes#global +[managed group]: /docs/concepts/domain-model/managed-groups +[managed groups]: /docs/concepts/domain-model/managed-groups [organization]: /docs/concepts/domain-model/scopes#organizations +[roles]: /docs/concepts/domain-model/roles [scope]: /docs/concepts/domain-model/scopes [users]: /docs/concepts/domain-model/users diff --git a/website/content/docs/concepts/domain-model/index.mdx b/website/content/docs/concepts/domain-model/index.mdx index d3cb882d78..9f2b371645 100644 --- a/website/content/docs/concepts/domain-model/index.mdx +++ b/website/content/docs/concepts/domain-model/index.mdx @@ -57,6 +57,11 @@ All resources have an ID which is unique within Boundary. which are considered equivalent for the purposes of access control. +- **[Managed Group][]** : + A managed group is a resource that groups [accounts][] based on criteria + established by a third-party service backing the [authentication method][]. It + can be used as a principal in [roles][]. + - **[Role][]** : A role is a resource that contains a collection of [permissions][] @@ -104,6 +109,7 @@ That page can help you understand the structure of resources within Boundary. [host sets]: /docs/concepts/domain-model/host-sets [host]: /docs/concepts/domain-model/hosts [hosts]: /docs/concepts/domain-model/hosts +[managed group]: /docs/concepts/domain-model/managed-groups [role]: /docs/concepts/domain-model/roles [roles]: /docs/concepts/domain-model/roles [scope]: /docs/concepts/domain-model/scopes diff --git a/website/content/docs/concepts/domain-model/managed-groups.mdx b/website/content/docs/concepts/domain-model/managed-groups.mdx new file mode 100644 index 0000000000..38e24e6d1a --- /dev/null +++ b/website/content/docs/concepts/domain-model/managed-groups.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: Domain Model - Managed Groups +description: |- + The anatomy of a Boundary managed group +--- + +# Managed Groups + +A managed group is a resource that represents a collection of [accounts][]. The +collection is formed by evaluating account information defined by the [auth +method][]'s identity provider against the managed group's configuration; members +cannot be managed manually. An account can be associated with zero or more +managed groups within the same [auth method][]. The managed group can be used as +a principal within [roles][] to assign grants. + +## Attributes + +All managed group types have the following configurable attributes: + +- `name` - (optional) + If set, the `name` must be unique within the account's [auth method][]. + +- `description` - (optional) + +### OIDC Managed Group Information and Attributes + +Membership in OIDC managed groups is evaluated when the auth method is used for +authentication, based on information contained within the OIDC ID token and the +OIDC User Info endpoint. Every authentication will result in a new evaluation of +managed group membership. + +OIDC managed groups have the following additional attributes: + +- `filter` - (required) + A boolean expression defining a filter run against the provided information. + For general syntax information see the [filtering concepts][] page; for more + specific information on the data available for this purpose see the [OIDC + Managed Groups Filtering][] page. + +[filtering concepts]: /docs/concepts/filtering + +## Referenced By + +- [Account][] +- [Auth Method][] + +[account]: /docs/concepts/domain-model/account +[accounts]: /docs/concepts/domain-model/accounts +[auth method]: /docs/concepts/domain-model/auth-methods + +## Service API Docs + +The following services are relevant to this resource: + +- [Managed Group Service](/api-docs/managed-group-service) diff --git a/website/content/docs/concepts/domain-model/roles.mdx b/website/content/docs/concepts/domain-model/roles.mdx index 25ea085f2a..7e246ae658 100644 --- a/website/content/docs/concepts/domain-model/roles.mdx +++ b/website/content/docs/concepts/domain-model/roles.mdx @@ -10,7 +10,7 @@ description: |- A role is a resource that contains a collection of [permissions][] which are granted to any principal assigned to the role. -[Users][] and [groups][] are principals +[Users][], [groups][], and [managed groups][] are principals which allows either to be assigned to a role. A role can be defined within any [scope][]. A role can be assigned to principals from any scope. @@ -27,11 +27,14 @@ A role has the following configurable attributes: ## Referenced By - [Group][] +- [Managed Group][] - [Project][] - [User][] [group]: /docs/concepts/domain-model/groups [groups]: /docs/concepts/domain-model/groups +[managed group]: /docs/concepts/domain-model/managed-groups +[managed groups]: /docs/concepts/domain-model/managed-groups [permissions]: /docs/concepts/security/permissions [project]: /docs/concepts/domain-model/scopes#projects [scope]: /docs/concepts/domain-model/scopes diff --git a/website/content/docs/concepts/filtering/oidc-managed-groups.mdx b/website/content/docs/concepts/filtering/oidc-managed-groups.mdx new file mode 100644 index 0000000000..0c21c77686 --- /dev/null +++ b/website/content/docs/concepts/filtering/oidc-managed-groups.mdx @@ -0,0 +1,69 @@ +--- +layout: docs +page_title: Filtering - OIDC Managed Groups +description: |- + How to configure filters for managed groups within the OIDC auth method. +--- + +This page describes how to use filters with OIDC managed groups. It assumes that +the reader is familiar with the general [filter syntax][] as well as with +[OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html). + +~> This feature was introduced in Boundary 0.3.0. + +[filter syntax]: /docs/concepts/filtering + +# OIDC Managed Groups Filtering + +Currently, two blocks of data are available for these filters: + +- `/token/` contains claims from the JWT returned by the OIDC Identity + Provider (IdP). For example, `/token/sub` is the `"sub"` claim from the token. + +- `/userinfo/` contains claims from the + [UserInfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) + endpoint. + +## Examples + +As the content of these claims is specific to the given IdP (other than those +claims mandated by the OIDC specification), no specific syntax can be conveyed, +but some examples are given below using contrived sets of claims. + +Given the example claims below: + +Example JWT claims: + +```json +{ + "iss": "https://server.example.com", + "sub": "24400320", + "aud": "s6BhdRkqt3", + "nonce": "n-0S6_WzA2Mj", + "exp": 1311281970, + "iat": 1311280970, + "auth_time": 1311280969, + "custom": { + "department": "infosec" + } +} +``` + +Example UserInfo claims: + +```json +{ + "roles": ["user", "operator"], + "sub": "alice@example.com", + "email": "rabbithole@example.com", + "name": "Alice of Wonderland" +} +``` + +Following are some examples of using these values in filters: + +- `"operator" in "/userinfo/roles"` would match users (like Alice) that have + `"operator"` in the roles returned in the UserInfo reply. + +- `"/token/custom/department" == "infosec" or "/token/custom/department" == "ops"` would match users (like Alice) that are either in the `ops` or `infosec` + departments. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index d55067ef09..6fa919098b 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -139,6 +139,10 @@ "title": "Host Sets", "path": "concepts/domain-model/host-sets" }, + { + "title": "Managed Groups", + "path": "concepts/domain-model/managed-groups" + }, { "title": "Scopes", "path": "concepts/domain-model/scopes" @@ -168,6 +172,10 @@ "title": "Overview", "path": "concepts/filtering" }, + { + "title": "OIDC Managed Groups", + "path": "concepts/filtering/oidc-managed-groups" + }, { "title": "Resource Listing", "path": "concepts/filtering/resource-listing"