From 8589650605505229ed18c453254c3aa77de6ea24 Mon Sep 17 00:00:00 2001
From: rithu john <rithujohn191@gmail.com>
Date: Tue, 15 Nov 2016 15:09:16 -0800
Subject: [PATCH] Documentation: LDAP connector documentation.

---
 Documentation/ldap-connector.md | 102 ++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 Documentation/ldap-connector.md

diff --git a/Documentation/ldap-connector.md b/Documentation/ldap-connector.md
new file mode 100644
index 00000000..44637ba6
--- /dev/null
+++ b/Documentation/ldap-connector.md
@@ -0,0 +1,102 @@
+# Authentication through LDAP
+
+## Overview
+
+The LDAP connector allows email/password based authentication, backed by a LDAP directory.
+
+The connector executes two primary queries:
+
+1. Finding the user based on the end user's credentials.
+2. Searching for groups using the user entry.
+
+## Configuration
+
+User entries are expected to have an email attribute (configurable through `emailAttr`), and a display name attribute (configurable through `nameAttr`). The following is an example config file that can be used by the LDAP connector to authenticate a user.
+
+```yaml
+
+connectors:
+- type: ldap
+  id: ldap
+  config:
+    # Host and optional port of the LDAP server in the form "host:port".
+    # If the port is not supplied, it will be guessed based on the TLS config.
+    host: ldap.example.com:636
+    # Following field is required if the LDAP host is not using TLS (port 389).
+    # insecureNoSSL: true
+    # Path to a trusted root certificate file. Default: use the host's root CA.
+    rootCA: /etc/dex/ldap.ca
+    # The DN and password for an application service account. The connector uses
+    # these credentials to search for users and groups. Not required if the LDAP
+    # server provides access for anonymous auth.
+    bindDN: uid=seviceaccount,cn=users,dc=example,dc=com
+    bindPW: password
+    # User entry search configuration.
+    userSearch:
+      # BaseDN to start the search from. It will translate to the query
+      # "(&(objectClass=person)(uid=<username>))".
+      baseDN: cn=users,dc=example,dc=com
+      # Optional filter to apply when searching the directory.
+      filter: "(objectClass=person)"
+      # username attribute used for comparing user entries. This will be translated
+      # and combined with the other filter as "(<attr>=<username>)".
+      username: uid
+      # The following three fields are direct mappings of attributes on the user entry.
+      # String representation of the user.
+      idAttr: uid
+      # Required. Attribute to map to Email.
+      emailAttr: mail
+      # Maps to display name of users. No default value.
+      nameAttr: name
+    # Group search configuration.
+    groupSearch:
+      # BaseDN to start the search from. It will translate to the query
+      # "(&(objectClass=group)(member=<user uid>))".
+      baseDN: cn=groups,dc=freeipa,dc=example,dc=com
+      # Optional filter to apply when searching the directory.
+      filter: "(objectClass=group)"
+      # Following two fields are used to match a user to a group. It adds an additional
+      # requirement to the filter that an attribute in the group must match the user's
+      # attribute value.
+      userAttr: uid
+      groupAttr: member
+      # Represents group name.
+      nameAttr: name
+```
+
+The LDAP connector first initializes a connection to the LDAP directory using the `bindDN` and `bindPW`. It then tries to search for the given `username` and bind as that user to verify their password.
+Searches that return multiple entries are considered ambiguous and will return an error.
+
+## Example: Searching a FreeIPA server with groups
+
+The following configuration will allow the LDAP connector to search a FreeIPA directory using an LDAP filter.
+
+```yaml
+
+connectors:
+- type: ldap
+  id: ldap
+  config:
+    # host and port of the LDAP server in form "host:port".
+    host: freeipa.example.com:636
+    # freeIPA server's CA
+    rootCA: ca.crt
+    userSearch:
+      # Would translate to the query "(&(objectClass=person)(uid=<username>))".
+      baseDN: cn=users,dc=freeipa,dc=example,dc=com
+      filter: "(objectClass=posixAccount)"
+      username: uid
+      idAttr: uid
+      # Required. Attribute to map to Email.
+      emailAttr: mail
+      # Entity attribute to map to display name of users.
+    groupSearch:
+      # Would translate to the query "(&(objectClass=group)(member=<user uid>))".
+      baseDN: cn=groups,dc=freeipa,dc=example,dc=com
+      filter: "(objectClass=group)"
+      userAttr: uid
+      groupAttr: member
+      nameAttr: name
+```
+
+If the search finds an entry, it will attempt to use the provided password to bind as that user entry.