From 3285bb1120475cdedfd65d239e548e7bb132b2fe Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Fri, 23 May 2025 16:54:38 -0500 Subject: [PATCH] DOC-4577 Added dn_group_query and user_dn_query details and examples to LDAP REST API references --- .../rs/references/rest-api/objects/ldap.md | 18 +++++++++--------- .../rest-api/requests/cluster/ldap.md | 12 ++++++++++-- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/content/operate/rs/references/rest-api/objects/ldap.md b/content/operate/rs/references/rest-api/objects/ldap.md index 825845f81..6386dbc90 100644 --- a/content/operate/rs/references/rest-api/objects/ldap.md +++ b/content/operate/rs/references/rest-api/objects/ldap.md @@ -17,13 +17,13 @@ An API object that represents the cluster's [LDAP]({{< relref "/operate/rs/secur | bind_dn | string | DN used when binding with the LDAP server to run queries | | bind_pass | string | Password used when binding with the LDAP server to run queries | | ca_cert | string | PEM-encoded CA certificate(s) used to validate TLS connections to the LDAP server | -| cache_ttl | integer (default: 300) | Maximum TTL (in seconds) of cached entries | -| control_plane | boolean (default: false) | Use LDAP for user authentication/authorization in the control plane | -| data_plane | boolean (default: false) | Use LDAP for user authentication/authorization in the data plane | -| directory_timeout_s | integer (range: 5-60) (default: 5) | The connection timeout to the LDAP server when authenticating a user, in seconds | -| dn_group_attr | string | The name of an attribute of the LDAP user entity that contains a list of the groups that user belongs to. (Mutually exclusive with "dn_group_query") | -| dn_group_query | complex object | An LDAP search query for mapping from a user DN to the groups the user is a member of. The substring "%D" in the filter will be replaced with the user's DN. (Mutually exclusive with "dn_group_attr") | -| starttls | boolean (default: false) | Use StartTLS negotiation for the LDAP connection | +| cache_ttl | integer (default: 300) | Maximum TTL (in seconds) of cached entries | +| control_plane | boolean (default: false) | Use LDAP for user authentication/authorization in the control plane | +| data_plane | boolean (default: false) | Use LDAP for user authentication/authorization in the data plane | +| directory_timeout_s | integer (range: 5-60) (default: 5) | The connection timeout to the LDAP server when authenticating a user, in seconds | +| dn_group_attr | string | The name of an attribute of the LDAP user entity that contains a list of the groups that user belongs to. `dn_group_attr` is mutually exclusive with `dn_group_query`. | +| dn_group_query | complex object | An LDAP search query used to find a user’s groups, which determine the user’s level of access to the cluster and database as defined by Redis ACLs when [mapped to roles]({{}}). `dn_group_query` is mutually exclusive with `dn_group_attr`.

Contains the following fields:
**base**: Defines the starting point DN (unique identifier Distinguished Name) in the directory information tree for the search. Example value: `"DC=example,DC=com"`
**filter**: An [RFC-4515](https://www.rfc-editor.org/info/rfc4515) string representation of the search filter to apply. Defines the conditions required for an entry to appear in the search results. Example value: `"member=%D"` where `%D` is replaced with the user's DN.
**scope**: Defines the scope of the LDAP search according to the following values:
**"base"**: Search the base entry.
**"one"**: Search the base entry's immediate children.
**"subtree"**: Search the base entry and all its descendants. | +| starttls | boolean (default: false) | Use StartTLS negotiation for the LDAP connection | | uris | array of strings | URIs of LDAP servers that only contain the schema, host, and port | -| user_dn_query | complex object | An LDAP search query for mapping from a username to a user DN. The substring "%u" in the filter will be replaced with the username. (Mutually exclusive with "user_dn_template") | -| user_dn_template | string | A string template that maps between the username, provided to the cluster for authentication, and the LDAP DN. The substring "%u" will be replaced with the username. (Mutually exclusive with "user_dn_query") | +| user_dn_query | complex object | An LDAP search query used to find and authenticate LDAP users. `user_dn_query` is mutually exclusive with `user_dn_template`.

Contains the following fields:
**base**: Defines the starting point DN (unique identifier Distinguished Name) in the directory information tree for the search. Example value: `"DC=example,DC=com"`
**filter**: An [RFC-4515](https://www.rfc-editor.org/info/rfc4515) string representation of the search filter to apply. Defines the conditions required for an entry to appear in the search results. Example value: `"(&(objectClass=Person)(cn=%u))"` where `%u` is replaced with the username.
**scope**: Defines the scope of the LDAP search according to the following values:
**"base"**: Search the base entry.
**"one"**: Search the base entry's immediate children.
**"subtree"**: Search the base entry and all its descendants. | +| user_dn_template | string | A string template that maps between the username, provided to the cluster for authentication, and the LDAP DN. The substring "%u" will be replaced with the username. `user_dn_template` is mutually exclusive with `user_dn_query`. | diff --git a/content/operate/rs/references/rest-api/requests/cluster/ldap.md b/content/operate/rs/references/rest-api/requests/cluster/ldap.md index afe7dc0dd..0dc62af5f 100644 --- a/content/operate/rs/references/rest-api/requests/cluster/ldap.md +++ b/content/operate/rs/references/rest-api/requests/cluster/ldap.md @@ -56,10 +56,18 @@ Returns an [LDAP object]({{< relref "/operate/rs/references/rest-api/objects/lda "control_plane": false, "data_plane": false, "dn_group_attr": "MemberOf", - "dn_group_query": {}, + "dn_group_query": { + "base": "DC=windowsAD,DC=qa,DC=redislabs,DC=com", + "filter": "member=%D", + "scope": "subtree" + }, "starttls": false, "uris": ["ldap://ldap.example.org:636"], - "user_dn_query": {}, + "user_dn_query": { + "base": "DC=windowsAD,DC=qa,DC=redislabs,DC=com", + "filter": "(&(objectClass=Person)(cn=%u))", + "scope": "subtree" + }, "user_dn_template": "cn=%u, ou=users,dc=example,dc=org" } ```