mirror of https://github.com/hashicorp/boundary
Add resource/filtering docs for OIDC managed groups (#1297)
Jeff Mitchell
5 years ago
committed by
GitHub
parent
e3ea54c98d
commit
f50ed866ef
@ -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)
|
||||
@ -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.
|
||||
Loading…
Reference in new issue