From c7901e170e079104d36cb8a0288763bb8497ea5b Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Thu, 23 May 2024 17:49:35 +0000 Subject: [PATCH 1/4] backport of commit f7daa1fb55de2f7e2c7211c08e4ad6b7c59cb2b2 --- .../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', From afca62c7247667bf62b5378fc678cb047a277b3d Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Thu, 23 May 2024 17:50:36 +0000 Subject: [PATCH 2/4] backport of commit f039357bf790e2626df6e6a0c24b621097ac6cf6 --- .../docs/concepts/domain-model/managed-groups.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/content/docs/concepts/domain-model/managed-groups.mdx b/website/content/docs/concepts/domain-model/managed-groups.mdx index 29f19c861e..9309f07785 100644 --- a/website/content/docs/concepts/domain-model/managed-groups.mdx +++ b/website/content/docs/concepts/domain-model/managed-groups.mdx @@ -34,12 +34,10 @@ 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. + For general syntax information refer to the [filtering concepts][] page; for more specific information on the data available for this purpose refer to the [managed groups filtering][] page. [filtering concepts]: /boundary/docs/concepts/filtering -[oidc managed groups filtering]: /boundary/docs/concepts/filtering/oidc-managed-groups +[managed groups filtering]: /boundary/docs/concepts/filtering/managed-groups ### LDAP managed group information and attributes @@ -68,4 +66,6 @@ The following services are relevant to this resource: ## Tutorial -Refer to the [Manage Users and Groups with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-users-groups) tutorial to learn how to complete user management related tasks. +Refer to the [Manage users and groups with HCP Boundary](/boundary/tutorials/hcp-administration/hcp-manage-users-groups) tutorial to learn how to complete user management related tasks. + +Refer to the [Identity management](/boundary/tutorials/identity-management) tutorials to learn about OIDC, LDAP, and managed groups. \ No newline at end of file From 31e381ca58666fd6b1153ffd1e47c0ef2060d256 Mon Sep 17 00:00:00 2001 From: Robin Beck Date: Wed, 5 Jun 2024 18:42:02 +0000 Subject: [PATCH 3/4] backport of commit 001c603deaf0e8635feadb3fe3708e9ed6265e27 --- website/content/docs/concepts/filtering/managed-groups.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/concepts/filtering/managed-groups.mdx b/website/content/docs/concepts/filtering/managed-groups.mdx index b001727efd..e37d68a6f6 100644 --- a/website/content/docs/concepts/filtering/managed-groups.mdx +++ b/website/content/docs/concepts/filtering/managed-groups.mdx @@ -83,7 +83,7 @@ To enable managed groups, the LDAP auth method `enable_groups` attribute should 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 +### LDAP auth method search 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. From 66d868d4ec6d13e549f19f5345452b9b3ee281fe Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Thu, 6 Jun 2024 17:30:34 +0000 Subject: [PATCH 4/4] backport of commit 36e43afdaa9494fda1bc9c72610bc69b92a201b0 --- .../concepts/filtering/managed-groups.mdx | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/website/content/docs/concepts/filtering/managed-groups.mdx b/website/content/docs/concepts/filtering/managed-groups.mdx index e37d68a6f6..98e1d0fa79 100644 --- a/website/content/docs/concepts/filtering/managed-groups.mdx +++ b/website/content/docs/concepts/filtering/managed-groups.mdx @@ -9,14 +9,14 @@ description: |- # 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/). +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 these filters for OIDC: +Currently, two blocks of data are available for OIDC filters: -- `/token/` contains claims from the JWT returned by the OIDC Identity +- `/token/` 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/` contains claims from the @@ -25,11 +25,9 @@ Currently, two blocks of data are available for these filters for OIDC: ### 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: +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: @@ -69,46 +67,48 @@ Example UserInfo claims: 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. +- `"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"` would match users (like Alice) that are either in the `ops` or `infosec` - departments. +- `"/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, and every authentication updates the group membership comparison. +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, the LDAP auth method `enable_groups` attribute should be set to `true`. +To enable managed groups, set the LDAP auth method `enable_groups` attribute 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. +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 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. +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. -An optional `group_dn` can be set to define the base DN to perform a group search under. A common example is: +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, 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: +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}}))` -A `group_attr` may also be set that enumerates group membership based on the objects returned from the `group_filter`. Common examples include: +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 +### 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. +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): +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` +Bind password: `password` All user passwords are `password`. You may also bind to individual Users (uid) or the two Groups (ou) that include: @@ -146,7 +146,7 @@ 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) +- `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"`