added docs for ldap plugin

diff --git a/docs/source/index.rst b/docs/source/index.rst
index de6c9c0d7795362ac5ba957602264fad0b741ef7..cad3c0333842fc6bdcac5be797164caf6c5b7c4d 100644 (file)
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -59,6 +59,7 @@ Part 2: Core plugin documentation
    plugindocs/oauth
    plugindocs/trim_whitespace
    plugindocs/raven
+   plugindocs/ldap
 
 
 Part 3: Plugin Writer's Guide

diff --git a/docs/source/plugindocs/ldap.rst b/docs/source/plugindocs/ldap.rst
new file mode 100644 (file)
index 0000000..3938c0c
--- /dev/null
+++ b/docs/source/plugindocs/ldap.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../mediagoblin/plugins/ldap/README.rst
+

diff --git a/mediagoblin/plugins/ldap/README.rst b/mediagoblin/plugins/ldap/README.rst
new file mode 100644 (file)
index 0000000..2539eb1
--- /dev/null
+++ b/mediagoblin/plugins/ldap/README.rst
@@ -0,0 +1,49 @@
+=============
+ ldap plugin
+=============
+
+.. Warning:
+   This plugin is not compatible with the other authentication plugins.
+
+This plugin allow your GNU Mediagoblin instance to authenticate against an
+LDAP server.
+
+Set up the ldap plugin
+======================
+
+1. Install the ``python-ldap`` package.
+
+2. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section::
+
+    [[mediagoblin.plugins.ldap]]
+
+Configuring the ldap plugin
+===========================
+
+This plugin allows you to use multiple ldap servers for authentication.
+
+In order to configure a server, add the following to you MediaGoblin .ini file
+under the ldap plugin:: 
+
+    [[mediagoblin.plugins.ldap]]
+    [[[server1]]]
+    LDAP_SERVER_URI = 'ldap://ldap.testathon.net:389'
+    LDAP_USER_DN_TEMPLATE = 'cn={username},ou=users,dc=testathon,dc=net'
+    [[[server2]]]
+    ...
+
+Make any necessary changes to the above to work with your sever. Make sure
+``{username}`` is where the username should be in LDAP_USER_DN_TEMPLATE.
+   
+If you would like to fetch the users email from the ldap server upon account
+registration, add ``LDAP_SEARCH_BASE = 'ou=users,dc=testathon,dc=net'`` and
+``EMAIL_SEARCH_FIELD = 'mail'`` under you server configuration in your
+MediaGoblin .ini file.
+
+.. Warning:
+   By default, this plugin provides no encryption when communicating with the
+   ldap servers. If you would like to use an SSL connection, change
+   LDAP_SERVER_URI to use ``ldaps://'' and whichever port you use. Default ldap
+   port for SSL connections is 636. If you would like to use a TLS connection,
+   add ``LDAP_START_TLS = 'true'`` under your server configuration in your
+   MediaGoblin .ini file.