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 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..98e1d0fa79 --- /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 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/` 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 + [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: + + + +```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"` 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: + + + +```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 you use 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 e39a235d15..850f08dca6 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',