added additional config docs

README.md

@@ -43,4 +43,105 @@ cp -n priv/local.d/* /usr/local/etc/couchdb/local.d/
 
 ## Configuration
 
-See [ldap_auth.ini] (priv/local.d/ldap_auth.ini) for details.
+### 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.
+
+```ini
+[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`
+
+#### LdapServer
+
+The LDAP server to use for searches and authentication.
+
+#### 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. jsmith@example.com<br/>
+  NOTE: if you use userPrincipalName, be sure to URL-encode the username when using basic auth.<br/>
+  e.g. `http://jsmith%40example.com:password@example.com: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.