From 3122e351cde5505d03c88a1a66639b943c54e754 Mon Sep 17 00:00:00 2001
From: Sheogorath
Date: Wed, 26 Sep 2018 19:08:50 +0200
Subject: Add documentation for an LDAP setup against Active Directory

Since our documentation on our LDAP configs is quite small, I add this
example for LDAP in an Active Directory environment.

Signed-off-by: Sheogorath <sheogorath@shivering-isles.com>
---
 docs/guides/auth/ldap-AD.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 docs/guides/auth/ldap-AD.md

(limited to 'docs/guides/auth')

diff --git a/docs/guides/auth/ldap-AD.md b/docs/guides/auth/ldap-AD.md
new file mode 100644
index 00000000..77521db3
--- /dev/null
+++ b/docs/guides/auth/ldap-AD.md
@@ -0,0 +1,42 @@
+AD LDAP auth
+===
+
+
+To setup your CodiMD instance with Active Directory you need the following configs:
+
+```
+CMD_LDAP_URL=ldap://internal.example.com
+CMD_LDAP_BINDDN=cn=binduser,cn=Users,dc=internal,dc=example,dc=com
+CMD_LDAP_BINDCREDENTIALS=<super secret password>
+CMD_LDAP_SEARCHBASE=dc=internal,dc=example,dc=com
+CMD_LDAP_SEARCHFILTER=(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))
+CMD_LDAP_USERIDFIELD=sAMAccountName
+CMD_LDAP_PROVIDERNAME=Example Inc AD
+```
+
+
+`CMD_LDAP_BINDDN` is either the `distinguishedName` or the `userPrincipalName`. *This can cause "username/password is invalid" when either this value or the password from `CMD_LDAP_BINDCREDENTIALS` are incorrect.*
+
+`CMD_LDAP_SEARCHFILTER` matches on all users and uses either the email address or the `sAMAccountName` (usually the login name you also use to login to Windows).
+
+*Only using `sAMAccountName` looks like this:* `(&(objectcategory=person)(objectclass=user)(sAMAccountName={{username}}))`
+
+`CMD_LDAP_USERIDFIELD` says we want to use `sAMAccountName` as unique identifier for the account itself.
+
+`CMD_LDAP_PROVIDERNAME` just the name written above the username and password field on the login page.
+
+
+Same in json:
+
+```json
+"ldap": {
+    "url": "ldap://internal.example.com",
+    "bindDn": "cn=binduser,cn=Users,dc=internal,dc=example,dc=com",
+    "bindCredentials": "<super secret password>",
+    "searchBase": "dc=internal,dc=example,dc=com",
+    "searchFilter": "(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))",
+    "useridField": "sAMAccountName",
+},
+```
+
+More details and example: https://www.npmjs.com/package/passport-ldapauth
-- 
cgit v1.2.3