mirror of https://github.com/hashicorp/boundary
Rab update filtering managed groups (#4821)
* renames managed groups filtering page, adds LDAP support * updates managed groups filtering links and tutorials links * Update website/content/docs/concepts/filtering/managed-groups.mdx Co-authored-by: Jim <jlambert@hashicorp.com> * docs: Edits --------- Co-authored-by: Jim <jlambert@hashicorp.com> Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>pull/4890/head
Robin Beck
2 years ago
committed by
GitHub
parent
61e7ab4738
commit
029ab627e2
@ -0,0 +1,167 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Filtering - managed groups
|
||||
description: |-
|
||||
How to configure filters for managed groups within the OIDC or LDAP auth methods.
|
||||
---
|
||||
|
||||
[filter syntax]: /boundary/docs/concepts/filtering
|
||||
|
||||
# Filter managed groups
|
||||
|
||||
This page describes how to use filters with OIDC or LDAP managed groups. It assumes that you are familiar with the general [filter syntax][] as well as [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) or [LDAP](https://ldap.com/ldap-specifications/).
|
||||
|
||||
|
||||
## OIDC filters
|
||||
|
||||
Currently, two blocks of data are available for OIDC filters:
|
||||
|
||||
- `/token/<claims>` contains claims from the JSON web token (JWT) that is 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.
|
||||
|
||||
### OIDC examples
|
||||
|
||||
The specific content of the claims is unique to the IdP, besides any claims that are part of the OIDC specification.
|
||||
We provide some examples in this section using sample claims.
|
||||
Refer to your IdP for the specific syntax.
|
||||
|
||||
Example JWT claims:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```json
|
||||
{
|
||||
"iss": "https://server.example.com",
|
||||
"sub": "24400320",
|
||||
"aud": "s6BhdRkqt3",
|
||||
"nonce": "n-0S6_WzA2Mj",
|
||||
"exp": 1311281970,
|
||||
"iat": 1311280970,
|
||||
"auth_time": 1311280969,
|
||||
"custom": {
|
||||
"department": "infosec"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
Example UserInfo claims:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```json
|
||||
{
|
||||
"roles": ["user", "operator"],
|
||||
"sub": "alice@example.com",
|
||||
"email": "rabbithole@example.com",
|
||||
"name": "Alice of Wonderland"
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
The following are some examples of using these values in filters:
|
||||
|
||||
- `"operator" in "/userinfo/roles"` matches users (like Alice) that have
|
||||
`"operator"` in the roles returned by UserInfo.
|
||||
|
||||
- `"/token/custom/department" == "infosec" or "/token/custom/department" == "ops"` matches users (like Alice) that are either in the `ops` or `infosec` departments.
|
||||
|
||||
## LDAP managed groups
|
||||
|
||||
Membership is determined by matching the LDAP group names against an LDAP account's associated groups.
|
||||
Every authentication updates the group membership comparison.
|
||||
|
||||
To enable managed groups, set the LDAP auth method `enable_groups` attribute to `true`.
|
||||
|
||||
After you enable groups on the auth method, the managed group membership is defined as a list with the `group-names` attribute on the managed group itself.
|
||||
|
||||
### LDAP auth method search filter attributes
|
||||
|
||||
When you define the auth method, you can set a number of group and user attributes to resolve group membership according to the structure of your directory schema.
|
||||
|
||||
You can set an optional `group_dn` to define the base distinguished name (DN) to perform a group search under. A common example is:
|
||||
|
||||
`ou=Groups,dc=example,dc=com`
|
||||
|
||||
Because the directory schema can vary, you may specify a `group_filter` that constructs a group membership query from a template. The following default template is compatible with several common directory schemas:
|
||||
|
||||
`(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`
|
||||
|
||||
You may also set a `group_attr` value that enumerates group membership based on the objects returned from the `group_filter`. Common examples include:
|
||||
|
||||
- `group_filter` queries returning group objects, use: `cn`. This is the default.
|
||||
- `group_filter` queries returning user objects, use: `memberOf`.
|
||||
|
||||
### LDAP examples
|
||||
|
||||
Directory schemas can vary according to your implementation.
|
||||
We provide some examples in this section using the schema declared for the [Online LDAP Test Server](https://www.forumsys.com/2022/05/10/online-ldap-test-server/) provided by ForumSystems.
|
||||
Refer to your directory schema for the specific syntax.
|
||||
|
||||
LDAP server information (read-only access):
|
||||
Server: `ldap.forumsys.com `
|
||||
Port: `389`
|
||||
Bind DN: `cn=read-only-admin,dc=example,dc=com`
|
||||
Bind password: `password`
|
||||
|
||||
All user passwords are `password`. You may also bind to individual Users (uid) or the two Groups (ou) that include:
|
||||
|
||||
Mathematicians: `ou=mathematicians,dc=example,dc=com`
|
||||
- riemann
|
||||
- gauss
|
||||
- euler
|
||||
- euclid
|
||||
|
||||
Scientists: `ou=scientists,dc=example,dc=com`
|
||||
- einstein
|
||||
- newton
|
||||
- galieleo
|
||||
- tesla
|
||||
|
||||
Example LDAP auth method attributes:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```text
|
||||
Attributes:
|
||||
bind_dn: cn=read-only-admin,dc=example,dc=com
|
||||
bind_password_hmac: IC29KNPDTPC57nc2aT9UFthOh4Kh1i3660_euBsgL7Y
|
||||
enable_groups: true
|
||||
group_dn: dc=example,dc=com
|
||||
state: active-public
|
||||
urls: [ldap://ldap.forumsys.com]
|
||||
user_attr: uid
|
||||
user_dn: dc=example,dc=com
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
In this example, the following attributes are set on the LDAP auth method:
|
||||
|
||||
- `urls:` `"ldap://ldap.forumsys.com"`
|
||||
- `bind-dn`:` "cn=read-only-admin,dc=example,dc=com"`
|
||||
- `bind-password`:` file://bind-pass.txt` (passed directly if you use Terraform)
|
||||
- `user-dn`:` "dc=example,dc=com"`
|
||||
- `user-attr`:` "uid"`
|
||||
- `group-dn`:` "dc=example,dc=com"`
|
||||
|
||||
Example managed group attributes:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```text
|
||||
Attributes:
|
||||
group_names: [Mathematicians]
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
In this example, the following attribute is set on the managed group:
|
||||
|
||||
- `group-names`: `"Mathematicians"`
|
||||
@ -1,69 +0,0 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Filtering - OIDC managed groups
|
||||
description: |-
|
||||
How to configure filters for managed groups within the OIDC auth method.
|
||||
---
|
||||
|
||||
[filter syntax]: /boundary/docs/concepts/filtering
|
||||
|
||||
# Filter OIDC managed groups
|
||||
|
||||
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).
|
||||
|
||||
~> **Note:** This feature was introduced in Boundary 0.3.0.
|
||||
|
||||
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