From: John Crygier <john.crygier@aon.com>
Date: Tue, 10 Apr 2012 18:50:51 +0000 (-0500)
Subject: Documentation for LDAP.  Covers the setup case that is in the JUnit Integration Test.
X-Git-Tag: v1.0.0~72^2~3
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=073b11b1e33c2c52a0796b75920b588c937eb6e9;p=gitblit.git

Documentation for LDAP.  Covers the setup case that is in the JUnit Integration Test.
---

diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd
index 75b51419..a7b4cdaa 100644
--- a/docs/01_setup.mkd
+++ b/docs/01_setup.mkd
@@ -447,4 +447,63 @@ Nothing special to configure, EGit figures out everything.
 <pre>https://yourserver/git/your/repository</pre>
 - **Command-line Git**  
 My testing indicates that your username must be embedded in the url.  YMMV.  
-<pre>https://username@yourserver/git/your/repository</pre>
\ No newline at end of file
+<pre>https://username@yourserver/git/your/repository</pre>
+
+## LDAP Support
+*SINCE 1.0.0*
+
+LDAP can be used with Gitblit to read Users and the Teams that they belong to.  If configured, LDAP will be queried upon every login to the system, and synchronize that information with the traditional Gitblit backed file (.conf or .properties).  This "lazy" reading approach provides for fast reaction times, but will force a user to log in before you can maintain them (or their teams).
+
+### Example Diagram (with attributes)
+![block diagram](ldapSample.png "LDAP Sample")
+
+Please see <gitblit>/tests/com/gitblit/tests/resources/ldapUserServiceSampleData.ldif to see the data in LDAP that reflects the above picture.
+
+### GitBlit Properties (See gitblit.properties for full description)
+The following is are descriptions of the properties that would follow the sample layout of an LDAP (or Active Directory) setup above.
+
+<table border="1" cellpadding="1" cellspacing="1">
+<tr>
+  <td>realm.ldap.server</td><td>ldap://localhost:389</td>
+  <td>Tells Gitblit to connect to the LDAP server on localhost, port 389.  URL Must be of form ldap(s)://<server>:<port> with port being optional (389 for ldap, 636 for ldaps).</td>
+</tr>
+<tr>
+  <td>realm.ldap.username</td><td>cn=Directory Manager</td>
+  <td>The credentials that will log into this gitblit server</td>
+</tr>
+<tr>
+  <td>realm.ldap.password</td><td>password</td>
+  <td>The credentials that will log into this gitblit server</td>
+</tr>
+<tr>
+  <td>realm.ldap.backingUserService</td><td>users.conf</td>
+  <td>Where to store all information that is used by Gitblit.  All information will be synced here upon user login.</td>
+</tr>
+<tr>
+  <td>realm.ldap.maintainTeams</td><td>true</td>
+  <td>Are users maintained in LDAP (true), or manually in Gitblit (false).</td>
+</tr>
+<tr>
+  <td>realm.ldap.accountBase</td><td>OU=Users,OU=UserControl,OU=MyOrganization,DC=MyDomain</td>
+  <td>What is the root node for all users in this LDAP system.  Searches will be subtree searches starting from this node.</td>
+</tr>
+<tr>
+  <td>realm.ldap.accountPattern</td><td>(&(objectClass=person)(sAMAccountName=${username}))</td><td>The LDAP Search filter that will match a particular user in LDAP.  ${username} will be replaced with whatever the user types in as their user name.</td>
+</tr>
+<tr>
+  <td>realm.ldap.groupBase</td><td>OU=Groups,OU=UserControl,OU=MyOrganization,DC=MyDomain</td>
+  <td>What is the root node for all teams in this LDAP system.  Searches will be subtree searches starting from this node.</td>
+</tr>
+<tr>
+  <td>realm.ldap.groupMemberPattern</td><td>(&(objectClass=group)(member=${dn}))</td><td>The LDAP Search filter that will match all teams for the logging in user in LDAP.  ${username} will be replaced with whatever the user types in as their user name.  Anything else in ${} will be replaced by Attributes on the User node.</td>
+</tr>
+<tr>
+  <td>realm.ldap.admins</td><td>@Git_Admins</td><td>A space delimited list of users and teams (if starting with @) that indicate admin status in Gitblit.</td>
+</tr>
+</table>
+
+You may notice that there are no properties to find the password on the User record.  This is intentional, and the service utilizes the LDAP login process to verify that the user credentials are correct.
+
+You can also start Gitblit GO with an in-memory (backed by an LDIF file) LDAP server by using the --ldapLdifFile property.  It will always start at ldap://localhost:389, so be sure to set that in gitblit.settings.  It reads the user / password in gitblit.settings to create the root user login.
+
+Finally, writing back to LDAP is not implemented at this time, so do not worry about corrupting your corporate LDAP.  Many orgnizations are likely to go through a different flow to update their LDAP, so it's unlikely that this will become a feature.
\ No newline at end of file
diff --git a/docs/ldapSample.png b/docs/ldapSample.png
new file mode 100644
index 00000000..fd8c999a
Binary files /dev/null and b/docs/ldapSample.png differ