From f7daa1fb55de2f7e2c7211c08e4ad6b7c59cb2b2 Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Thu, 23 May 2024 11:49:35 -0600 Subject: [PATCH] renames managed groups filtering page, adds LDAP support --- .../concepts/filtering/managed-groups.mdx | 167 ++++++++++++++++++ .../filtering/oidc-managed-groups.mdx | 69 -------- website/data/docs-nav-data.json | 4 +- website/redirects.js | 5 + 4 files changed, 174 insertions(+), 71 deletions(-) create mode 100644 website/content/docs/concepts/filtering/managed-groups.mdx delete mode 100644 website/content/docs/concepts/filtering/oidc-managed-groups.mdx diff --git a/website/content/docs/concepts/filtering/managed-groups.mdx b/website/content/docs/concepts/filtering/managed-groups.mdx new file mode 100644 index 0000000000..b001727efd --- /dev/null +++ b/website/content/docs/concepts/filtering/managed-groups.mdx @@ -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 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) or [LDAP](https://ldap.com/ldap-specifications/). + + +## OIDC filters + +Currently, two blocks of data are available for these filters for OIDC: + +- `/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. + +### OIDC 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" +} +``` + + + +The 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. + +## LDAP managed groups + +Membership is determined by matching the LDAP group names against an LDAP account's associated groups, and every authentication updates the group membership comparison. + +To enable managed groups, the LDAP auth method `enable_groups` attribute should be set to `true`. + +After enabling 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 filter attributes + +When defining the auth method, a number of group and user attributes can be set to resolve group membership according to the structure of your directory schema. + +An optional `group_dn` can be set to define the base DN to perform a group search under. A common example is: + +`ou=Groups,dc=example,dc=com` + +Because the directory schema can vary, a `group_filter` may be specified 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}}))` + +A `group_attr` may also be set 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 + +Because directory schemas can vary according to implementation, no specific syntax can be conveyed, but some examples are given below using the schema declared for the [Online LDAP Test Server](https://www.forumsys.com/2022/05/10/online-ldap-test-server/) provided by ForumSystems. + +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: + + + +```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 +``` + + + +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 using Terraform) +- `user-dn`:` "dc=example,dc=com"` +- `user-attr`:` "uid"` +- `group-dn`:` "dc=example,dc=com"` + +Example managed group attributes: + + + +```text +Attributes: + group_names: [Mathematicians] +``` + + + +In this example, the following attribute is set on the managed group: + +- `group-names`: `"Mathematicians"` \ No newline at end of file diff --git a/website/content/docs/concepts/filtering/oidc-managed-groups.mdx b/website/content/docs/concepts/filtering/oidc-managed-groups.mdx deleted file mode 100644 index 0a10319d59..0000000000 --- a/website/content/docs/concepts/filtering/oidc-managed-groups.mdx +++ /dev/null @@ -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/` 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 ab92cba4f4..0ae06f9f9f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -396,8 +396,8 @@ "path": "concepts/filtering" }, { - "title": "OIDC managed groups", - "path": "concepts/filtering/oidc-managed-groups" + "title": "Managed groups", + "path": "concepts/filtering/managed-groups" }, { "title": "Resource listing", diff --git a/website/redirects.js b/website/redirects.js index 0bdcf75be5..3b8818e605 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -179,6 +179,11 @@ module.exports = [ destination: '/boundary/docs/concepts/host-discovery', permanent: true, }, + { + source: '/boundary/docs/concepts/filtering/oidc-managed-groups', + destination: '/boundary/docs/concepts/filtering/managed-groups', + permanent: true, + }, { source: '/boundary/docs/configuration/worker/kms-worker', destination: '/boundary/docs/configuration/worker/worker-configuration',