Greetings, In 2015 IBM Cloudant developed an LDAP based authentication handler for its CouchDB 2.x-based Cloudant Local offering. Since then, it has been used in production on several large Cloudant Local deployments, accruing many bug fixes and enhancements in the process.
Over the years, there has clearly been interest in using LDAP with CouchDB [1], so it seems like the ldap_auth functionality might be something the greater community could benefit from. If there are no objections from the community or PMC, I'd be happy to open a PR in the hopes of getting it included in CouchDB 3.2. To give an idea of what it's all about, I've included the README.md contents below. Thanks, Jay [1] https://couchdb.markmail.org/search/?q=LDAP README.md: # Delegating Basic and Cookie authentication and authorization to LDAP CouchDB includes a built-in security model, with self-contained authentication and authorization which rely on .ini files and/or user databases to store user data, including usernames (uids), password hashes, and user roles for accessing database resources. For an organization which already uses an LDAP service for access control, it may make more sense to delegate authentication and authorization services to LDAP when accessing CouchDB. This is where `ldap_auth` comes in. At a high level, when `ldap_auth` is configured, it completely replaces the default Basic and Cookie authentication and authorization. It ignores .ini files and user databases altogether, and attempts to validate user credentials using the configured LDAP service. Once credentials have been authentication by the LDAP service, `ldap_auth` determines the user's roles (which in turn determine what the user is authorized to access) based on the LDAP groups of which the user is a member. ## ldap_interface This low-level interface module uses [eldap](http://www.erlang.org/doc/man/eldap.html) to connect to, authenticate, and search LDAP server(s) which are configured to model user accounts and their associated CouchDB roles. ### Configuration All configuration is done via `.ini` file, mostly in the `[ldap_auth]` section. The following parameters can be modified, and have the associated defaults in parentheses: - `servers (127.0.0.1)` one or more LDAP servers; defaults to a single host, but could be a comma separated list (note that all servers must use the same port, a limitation of the underlying eldap library) - `port (389)` LDAP server port for un-encrypted communication - `ssl_port (636)` LDAP server port for encrypted communication - `use_ssl (true)` if `true`, use TLS to encrypt traffic to LDAP servers - `timeout (5000)` milliseconds to wait for a response from an LDAP server before throwing an error - `user_base_dn (ou=users,dc=example,dc=com)` defines a directory location to start searching for users - `user_classes (person)` defines which `objectClass`es indicate a particular entry as a user during search - `user_uid_attribute (uid)` defines which attribute maps to username - `group_base_dn (ou=groups,dc=example,dc=com)` defines directory location to start searching for groups - `group_classes (posixGroup)` defines which `objectClass`es indicate a particular entry as a group during search - `group_member_attribute (memberUid)` defines which group attribute maps to user Uid - `group_role_attribute (description)` defines which group attribute maps to a particular role - `searcher_dn (uid=ldapsearch,ou=users,dc=example,dc=com)` defines the DN to use when searching for users and groups - `searcher_password (secret)` defines the password for the `searcher_dn` above - `user_bind_dns ([])` defines one or more base DNs into which the authenticating user's username can be inserted as the `user_uid_attribute`, and used to bind directly. See the "Efficiency Considerations" section below for details **Please note** that at least one of the above parameters must be set inside the `[ldap_auth]` section of a .ini configuration file in order for ldap_auth to be considered "configured", and to function as an authentication/authorization handler. Failure to explicitly set at least one `[ldap_auth]` parameter will result in the system using the default basic and cookie authentication/authorization handlers instead. ### Efficiency Considerations `ldap_auth` effectively has 2 modes of operation, depending on whether `user_bind_dns` has been defined or not. Both modes return a list of roles associated with a user upon authentication success. By default, `ldap_auth` opens a connection to an LDAP server and binds the connection handle with the searcher DN and password. It then uses that connection to search for a user record with the authenticating username. If a matching user DN is found, it opens a second connection to the server and attempts to bind that connection using the username and password credentials. If the bind is successful, it closes that connection, and uses the original "searcher" bound connection to search for groups which contain the `group_member_attribute` matching the user's username. Those groups have a `group_role_attribute` which indicates the actual roles for the user. On the other hand, if you know in advance that all your users' DNs can be constructed by inserting their usernames into the following pattern: `$uid_attribute=$username,$user_bind_dn` (e.g. `uid=jay,ou=users,dc=example,dc=com`), then you can configure one or more `user_bind_dns`, and `ldap_auth` will not make use of the searcher DN, nor `user_base_dn`, but instead attempt to bind directly with the constructed user DNs. If the bind is successful, that bound connection is further used to make the same group search as described in the above paragraph. Overall, this technique can be used to eliminate several additional network round trips. ## ldap_auth Implements Basic and Cookie based authentication handlers, using `ldap_interface:authorized_roles(Username, Password)` to obtain the roles associated with a particular user. Using `ldap_auth` with basic authentication requires no client side changes. A properly configured database will automatically attempt to authenticate via LDAP using the supplied credentials. Similarly, for cookie authentication, POST credentials to the `_session` endpoint to obtain an AuthSession cookie, which contains a signed hash of its contents: name, time issued, and authorized roles. Subsequent requests using that cookie will automatically use the roles in the cookie until it expires. The following configuration parameters in the `[couch_httpd_auth]` section are used: - `timeout (600)` seconds until the AuthSession cookie expires - `secret` the shared secret used to sign the AuthSession cookie, it should be created when the cluster is provisioned
