From defe95a38e91b8f28a41ce364b3349a837e1c892 Mon Sep 17 00:00:00 2001 From: cheelio Date: Sat, 20 Sep 2025 14:48:08 +0200 Subject: [PATCH] Add documentation on LDAP group provider Co-Authored-By: Manfred Moser --- .../src/main/sphinx/security/group-mapping.md | 158 ++++++++++++++++-- 1 file changed, 146 insertions(+), 12 deletions(-) diff --git a/docs/src/main/sphinx/security/group-mapping.md b/docs/src/main/sphinx/security/group-mapping.md index e2e52b0cfcc0..683145255701 100644 --- a/docs/src/main/sphinx/security/group-mapping.md +++ b/docs/src/main/sphinx/security/group-mapping.md @@ -1,6 +1,6 @@ # Group mapping -Group providers in Trino to map usernames onto groups for easier access control +Group providers in Trino map usernames onto groups for easier access control and resource group management. Configure a group provider by creating an `etc/group-provider.properties` file @@ -9,8 +9,8 @@ on the coordinator: ```properties group-provider.name=file ``` -_The configuration of the chosen group provider should be appended to this -file_ +The value for `group-provider.name` must be either `file` or `ldap` and the +configuration of the chosen group provider must be included in the same file. :::{list-table} Group provider configuration :widths: 40, 60 @@ -24,7 +24,7 @@ file_ Supported values are: * `file`: [See configuration](file-group-provider) - * `ldap` + * `ldap`: [See configuration](ldap-group-provider) * - `group-provider.group-case` - Optional transformation of the case of the group name. Supported values are: @@ -39,11 +39,12 @@ file_ (file-group-provider)= ## File group provider -Group file resolves group membership using a file on the coordinator. +The file group provider resolves group memberships with the configuration in +the group-provider.properties file on the coordinator. -### Group file configuration +### Configuration -Enable group file by creating an `etc/group-provider.properties` +Enable the file group provider by creating an `etc/group-provider.properties` file on the coordinator: ```properties @@ -59,14 +60,12 @@ The following configuration properties are available: * - Property name - Description - * - `file.group-file` - - Path of the group file + - Path of the group file. * - `file.refresh-period` - [Duration](prop-type-duration) between refreshing the group mapping - configuration from the file. - Defaults to `5s`. - ::: + configuration from the file. Defaults to `5s`. +::: ### Group file format @@ -77,3 +76,138 @@ separated by a colon. Users are separated by a comma. group_name:user_1,user_2,user_3 ``` +(ldap-group-provider)= +## LDAP group provider + +The LDAP group provider resolves user group memberships from configuration +retrieved from an LDAP server. +This allows access rules to be defined based on LDAP groups instead of +individual users. + +### Configuration + +Enable LDAP group provider by creating an `etc/group-provider.properties` file +on the coordinator and add further configuration for the LDAP server +connections and other information as detailed in the following sections. + +```properties +group-provider.name=ldap +``` + +:::{list-table} Generic LDAP properties +:widths: 40, 60 +:header-rows: 1 +* - Property name + - Description +* - `ldap.url` + - LDAP server URI. For example, `ldap://host:389` or `ldaps://host:636`. +* - `ldap.allow-insecure` + - Allow insecure connection to the LDAP server. +* - `ldap.ssl.keystore.path` + - Path to the PEM or JKS key store. +* - `ldap.ssl.keystore.password` + - Password for the key store. +* - `ldap.ssl.truststore.path` + - Path to the PEM or JKS trust store. +* - `ldap.ssl.truststore.password` + - Password for the trust store. +* - `ldap.ignore-referrals` + - Referrals allow finding entries across multiple LDAP servers. Ignore them + to only search within one LDAP server. +* - `ldap.timeout.connect` + - Timeout for establishing a connection. +* - `ldap.timeout.read` + - Timeout for reading data from LDAP. +* - `ldap.admin-user` + - Bind distinguished name for admin user. For example, + `CN=UserName,OU=City,OU=State,DC=domain,DC=domain_root` +* - `ldap.admin-password` + - Bind password used for the admin user. +* - `ldap.user-base-dn` + - Base distinguished name for users. For example, `dc=example,dc=com`. +* - `ldap.user-search-filter` + - LDAP filter to find user entries; `{0}` is replaced with the Trino username. + For example, `(cn={0})` +* - `ldap.group-name-attribute` + - Attribute to extract group name from group entry. For example, `cn`. +* - `ldap.use-group-filter` + - Whether to use search-based group resolution. Defaults to `true`. + If `false`, Trino uses the attribute-based method. +::: + +Group resolution behavior is controlled by the `ldap.use-group-filter` property. +With search-based group resolution, Trino searches for group entries that +include the user DN. This requires the following properties: + +:::{list-table} Search-based group resolution +:widths: 40, 60 +:header-rows: 1 +* - Property name + - Description +* - `ldap.group-base-dn` + - Base distinguished name for groups. For example, `dc=example,dc=com`. +* - `ldap.group-search-filter` + - Search filter for group documents. For example, `(cn=trino_*)`. +* - `ldap.group-search-member-attribute` + - Attribute from group documents used for filtering by member. For example, + `cn`. +::: + +In case of attribute-based group resolution, Trino reads the group list +directly from a user attribute. This requires the following property: + +:::{list-table} Attribute-based (single query) group resolution +:widths: 40, 60 +:header-rows: 1 + +* - Property name + - Description +* - `ldap.user-member-of-attribute` + - Group membership attribute in user documents. For example, `memberOf`. +::: + +### Example configurations + +The following configuration is an example for an OpenLDAP (search-based) +group provider: + +```properties +group-provider.name=ldap +group-provider.group-case=lower + +ldap.url=ldap://ldap.example.com:389 +ldap.admin-user=cn=admin,dc=example,dc=com +ldap.admin-password=your_password +ldap.group-name-attribute=cn +ldap.user-base-dn=ou=users,dc=example,dc=com +ldap.user-search-filter=(uid={0}) +ldap.use-group-filter=true + +ldap.group-base-dn=ou=groups,dc=example,dc=com +ldap.group-search-filter=(cn=trino_*) +ldap.group-search-member-attribute=member +``` + +The following configuration is an example for an Active Directory +(single query, attribute-based) group provider: + +```properties +group-provider.name=ldap +group-provider.group-case=lower + +ldap.url=ldaps://ad.example.com:636 +ldap.admin-user=cn=admin,dc=example,dc=com +ldap.admin-password=your_password +ldap.group-name-attribute=cn +ldap.user-base-dn=ou=users,dc=example,dc=com +ldap.user-search-filter=(sAMAccountName={0}) +ldap.use-group-filter=false + +ldap.user-member-of-attribute=memberOf +``` + +### Integration with access control + +Groups resolved by the LDAP provider are passed to Trino’s system access +control engine. Access control rules can reference these group names to grant +or restrict permissions.