LDAP Authentication Handler for CouchDB

Features

• Basic authentication handler
• Session handler
  • works with CouchDB built-in cookie_authentication_handler
• Supports users and recursive-group association

Installation

First, check out the source and cd into it.

Prerequisites

• Erlang
• Rebar
• eldap (bundled with Erlang >= R15B. See their github repo.)

Build from Source

rebar get-deps clean compile

Run Tests

rebar test

Install binaries and config

# Create module folder
mkdir /usr/local/lib/couchdb/erlang/lib/ldap-auth
# Copy binaries
cp -R ebin /usr/local/lib/couchdb/erlang/lib/ldap-auth/

# Copy/overwrite the default config
cp -f priv/default.d/* /usr/local/etc/couchdb/default.d/

# Copy (but don't overwrite!) the custom config
cp -n priv/local.d/* /usr/local/etc/couchdb/local.d/

Configuration

Authentication Handlers

The defaults included in ldap_auth.ini provide a basic, out-of-the-box configuration for sessions, cookies, basic authentication, and system admin role assignment based on LDAP.

If you have a custom configuration of CouchDB, you may need to edit it.

Keep in mind that the first handler to authenticate a credential "wins." Specifically, this means that if you keep the built-in {couch_httpd_auth, default_authentication_handler}, CouchDB will continue to inspect the _users database for credentials and use the ini files for system admins.

Basic Auth

To allow requests with the users' names and passwords encoded in the URL, simply include {ldap_auth, handle_basic_auth_req} in the authentication_handlers:

[httpd] authentication_handlers = {ldap_auth, handle_basic_auth_req}

Sessions and Cookies

In order for session management and cookies to work, you need a few options set.

The first binds the /_session REST endpoint to the LDAP session manager.

[httpd_global_handlers]
    _session = {ldap_auth, handle_session_req}

The session manager will authenticate the POST payload credentials and provide a cookie token.

In order to use the cookie token, the CouchDB built-in cookie handler must be included in the list of authentication handlers:

[httpd] authentication_handlers = {couch_httpd_auth, cookie_authentication_handler}

Each time handle_session_req is called, the _users database is updated with the user's roles. If the user document does not exist beforehand, a new one is created; the user's password is not stored.

System Admin Delegation

If you'd like to use LDAP to also control the list of system administrators, rather than the CouchDB built-in list in .ini files, you can add {ldap_auth, handle_admin_role} to the end of the authentication_handlers list.

Options

UseSSL

Set to true to use SSL to bind to the LDAP server. Default: false

LdapServers

The LDAP servers to use for searches and authentication, separated by commas. These will be tried in-order.

BaseDN

The distinguished name to constrain the scope of which users may authenticate. This may be as broad (the entire domain) or narrow (an OU or even a group) as needed.

SearchUserDN and SearchUserPassword

In order to authenticate users by an arbitrary attribute (like username) instead of a distinguished name, a service user must be available with permission to query LDAP (no other permissions are needed). Some LDAP servers provide anonymous querying, but this is not recommended by LDAP vendors.

The SearchUserDN and SearchUserPassword should be set to the credentials of the desired service user. If anonymous queries are allowed and preferred, the DN must be set to the anon DN, but the password may remain blank.

UserDNMapAttr

The attribute to use as the login name for CouchDB. On Active Directory, you might use:

• sAMAccountName, e.g. jsmith
• userPrincipalName, e.g. [email protected]
  NOTE: if you use userPrincipalName, be sure to URL-encode the username when using basic auth.
  e.g. http://jsmith%40example.com:[email protected]:5984

Any attribute could be used, though.

GroupDNMapAttr

The same as UserDNMapAttr, but for groups. Most LDAP software has a name attribute on group objects.

SystemAdminRoleName

If you're using system admin delegation, this is the name of the role that will be promoted to _admin, aka the system admin.