Add resource/filtering docs for OIDC managed groups (#1297)

2021-06-09 08:55:02 -04:00
1 parent e3ea54c98d
commit f50ed866ef
@@ -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
@@ -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

@@ -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
@@ -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)
@@ -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
@@ -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/<claims>` contains claims from the JWT returned by the OIDC Identity
+  Provider (IdP). For example, `/token/sub` is the `"sub"` claim from the token.
+
+- `/userinfo/<claims>` 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.
@@ -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"