This is an automated email from the ASF dual-hosted git repository. smolnar82 pushed a commit to branch knox_idf in repository https://gitbox.apache.org/repos/asf/knox.git
commit dc3adae656e9110c57fedd0c7c41a560d21193ad Author: Sandor Molnar <[email protected]> AuthorDate: Thu Jun 4 12:27:48 2026 +0200 KNOX-3318: document LDAP service (#1227) --- knox-site/docs/book_service-details.md | 4 +- knox-site/docs/service_ldap_server.md | 149 +++++++++++++++++++++++++++++++++ knox-site/mkdocs.yml | 1 + 3 files changed, 152 insertions(+), 2 deletions(-) diff --git a/knox-site/docs/book_service-details.md b/knox-site/docs/book_service-details.md index 23d8d5065..bca816732 100644 --- a/knox-site/docs/book_service-details.md +++ b/knox-site/docs/book_service-details.md @@ -60,11 +60,11 @@ These are the current Hadoop services with built-in support. * [Cloudera Manager](service_cloudera_manager.md) * [Livy](service_livy.md) * [Elasticsearch](service_elasticsearch.md) -* [SSL Certificate Trust](service_ssl_certificate_trust.md) +* [SSL Certificate Trust](service_ssl_certificate_trust.md) * [Service Test](service_service_test.md) +* [LDAP Server](service_ldap_server.md) ### Assumptions - This document assumes a few things about your environment in order to simplify the examples. * The JVM is executable as simply `java`. diff --git a/knox-site/docs/service_ldap_server.md b/knox-site/docs/service_ldap_server.md new file mode 100644 index 000000000..51080f69a --- /dev/null +++ b/knox-site/docs/service_ldap_server.md @@ -0,0 +1,149 @@ +# Knox LDAP Service + +The Knox LDAP Service provides an embedded LDAP server within the Knox Gateway. It acts as a pluggable LDAP proxy or facade, allowing Knox to expose a standard LDAP interface to clients while fetching user and group information from various backends. + +## Overview + +Introduced in [KNOX-3247](https://issues.apache.org/jira/browse/KNOX-3247), the Knox LDAP Service leverages Apache Directory Server (ApacheDS) to provide a lightweight, embedded LDAP server. Its primary goal is to provide a consistent LDAP interface for authentication and group lookups, even when the underlying identity store is not a traditional LDAP server or is a remote server that requires proxying. + +Key features include: +- **Pluggable Backends**: Support for different data sources (JSON files, remote LDAP/AD). +- **Embedded Server**: No need for an external LDAP server for simple use cases or testing. +- **Active Directory Integration**: Optimized for proxying to AD with support for `sAMAccountName`. + +## Architecture + +The Knox LDAP Service is integrated as a core gateway service. It consists of the following components: + +1. **KnoxLDAPServerManager**: Manages the lifecycle of the ApacheDS instance. +2. **GroupLookupInterceptor**: A custom ApacheDS interceptor that captures search requests. If an entry is not found in the local ApacheDS partitions, it delegates the lookup to the configured backend. +3. **LdapBackend**: A pluggable interface for fetching user and group data. +4. **SchemaManagerFactory**: Programmatically extends the ApacheDS schema to include AD-specific attributes like `sAMAccountName`. + +When a client performs an LDAP search: +1. The request hits the embedded ApacheDS server. +2. The `GroupLookupInterceptor` intercepts the search. +3. The interceptor checks the results of the local search. +4. If not found, it queries the configured `LdapBackend`. +5. Results from the backend are converted into LDAP entries and returned to the client. + +## Configuration + +The service is configured in `gateway-site.xml`. + +### Common Properties + +| Property | Default Value | Description | +| :--- | :--- | :--- | +| `gateway.ldap.enabled` | `false` | Enables or disables the embedded LDAP service. | +| `gateway.ldap.port` | `3890` | The port on which the LDAP server listens. | +| `gateway.ldap.base.dn` | `dc=proxy,dc=com` | The base DN for the LDAP server. | +| `gateway.ldap.backend.type` | `file` | The type of backend to use (`file` or `proxy`). | + +### Backend Types + +#### File Backend (`file`) + +The file backend reads user and group definitions from a JSON file. This is ideal for testing or small, static environments. + +| Property | Default Value | Description | +| :--- | :--- | :--- | +| `gateway.ldap.backend.data.file` | `${GATEWAY_DATA_HOME}/ldap-users.json` | Path to the JSON data file. | + +**JSON File Format Example:** +```json +{ + "users": [ + { + "username": "guest", + "cn": "Guest User", + "sn": "User", + "groups": ["users", "guests"], + "attributes": { + "mail": "[email protected]" + } + } + ] +} +``` + +#### Proxy Backend (`proxy`) + +The proxy backend delegates lookups to a remote LDAP or Active Directory server. + +| Property | Default Value | Description | +| :--- | :--- | :--- | +| `gateway.ldap.backend.proxy.url` | N/A | Remote LDAP URL (e.g., `ldap://remote-host:389`). | +| `gateway.ldap.backend.proxy.host` | N/A | Host of remote LDAP (used if `url` is not provided). | +| `gateway.ldap.backend.proxy.port` | N/A | Port of remote LDAP (used if `url` is not provided). | +| `gateway.ldap.backend.proxy.remoteBaseDn` | N/A | **Required**. The base DN of the remote LDAP server. | +| `gateway.ldap.backend.proxy.systemUsername` | N/A | Bind DN for the remote server (alias: `bindDn`). | +| `gateway.ldap.backend.proxy.systemPassword` | N/A | Password for the bind DN (alias: `bindPassword`). | +| `gateway.ldap.backend.proxy.userSearchBase` | `ou=people,{remoteBaseDn}` | Base DN for user searches on the remote server. | +| `gateway.ldap.backend.proxy.groupSearchBase` | `ou=groups,{remoteBaseDn}` | Base DN for group searches on the remote server. | +| `gateway.ldap.backend.proxy.userIdentifierAttribute` | `uid` | Attribute used for user lookup (e.g., `sAMAccountName` for AD). | +| `gateway.ldap.backend.proxy.groupMemberAttribute` | `memberUid` | Attribute used for group membership (e.g., `member` for AD). | +| `gateway.ldap.backend.proxy.useMemberOf` | `false` | If `true`, use the `memberOf` attribute for efficient group lookups. | +| `gateway.ldap.backend.proxy.poolMaxActive` | `8` | Maximum number of active connections in the pool. | + +## Active Directory (AD) Integration + +The Knox LDAP Service includes several optimizations for working with Active Directory (improved in [KNOX-3277](https://issues.apache.org/jira/browse/KNOX-3277)): + +- **sAMAccountName Support**: The service recognizes `sAMAccountName` in search filters, allowing seamless integration with Windows environments. +- **Efficient Group Lookups**: By setting `gateway.ldap.backend.proxy.useMemberOf` to `true`, Knox can retrieve all of a user's groups in a single query by reading the `memberOf` attribute, rather than searching all group objects. +- **Schema Extensions**: AD-specific attributes (`memberOf`, `sAMAccountName`) are programmatically added to the embedded ApacheDS schema to prevent "attribute not found" errors during proxying. +- **Case Sensitivity**: Search filters are handled to accommodate AD's case-insensitive nature for user identifiers. + +## Usage Example (AD Proxy) + +To configure Knox to act as an LDAP proxy for an Active Directory server: + +```xml +<property> + <name>gateway.ldap.enabled</name> + <value>true</value> +</property> +<property> + <name>gateway.ldap.port</name> + <value>389</value> +</property> +<property> + <name>gateway.ldap.backend.type</name> + <value>proxy</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.url</name> + <value>ldap://ad.example.com:389</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.remoteBaseDn</name> + <value>dc=example,dc=com</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.systemUsername</name> + <value>CN=ReadOnlyUser,CN=Users,DC=example,DC=com</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.systemPassword</name> + <value>secret-password</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.userIdentifierAttribute</name> + <value>sAMAccountName</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.groupMemberAttribute</name> + <value>member</value> +</property> +<property> + <name>gateway.ldap.backend.proxy.useMemberOf</name> + <value>true</value> +</property> +``` + +## Troubleshooting + +- **Logs**: LDAP service logs can be found in `gateway.log`. Look for messages from `org.apache.knox.gateway.services.ldap`. +- **Lock Files**: If Knox crashes, an `instance.lock` file might remain in `${GATEWAY_DATA_HOME}/ldap-server/run/`. The service attempts to clean this up on startup. +- **Anonymous Access**: The embedded LDAP server allows anonymous access by default to facilitate discovery and simple binds, but backend lookups are performed using the configured `systemUsername`. diff --git a/knox-site/mkdocs.yml b/knox-site/mkdocs.yml index e045485a6..f147f0937 100644 --- a/knox-site/mkdocs.yml +++ b/knox-site/mkdocs.yml @@ -50,6 +50,7 @@ nav: - Client/User Guide: - Knox Shell: knoxshell-guide/knoxshell_user_guide.md - Discovering Resources: book_client-details.md + - LDAP Server: service_ldap_server.md - Troubleshooting: - General Troubleshooting: book_troubleshooting.md - Client-Specific Troubleshooting: client_troubleshooting.md
