Ticket #5568: 0001-Fix-LDAP-For-Active-Directory_docs.patch

mediagoblin/plugins/ldap/README.rst

@@ -18 +18 @@
 =============
 
 .. Warning::
-   This plugin is not compatible with the other authentication plugins.
+    This plugin is not compatible with the other authentication plugins.
+    All other authentication plugins will need to be disabled in order
+    for this plugin to work.
 
-This plugin allow your GNU MediaGoblin instance to authenticate against an
+This plugin allow your GNU Mediagoblin instance to authenticate against an
 LDAP server.
 
-Set up the LDAP plugin
+Set up the ldap plugin
 ======================
 
 1. Install the ``python-ldap`` package.
@@ -32 +34 @@
 
     [[mediagoblin.plugins.ldap]]
 
-Configuring the LDAP plugin
+Configuring the ldap plugin
 ===========================
 
-This plugin allows you to use multiple LDAP servers for authentication.
+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:: 
+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'
+    LDAP_SEARCH_BASE = '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
+
+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.
 
+If you are using Microsoft's Active Directory for your LDAP provider, you will
+want to specify the following::
+
+    [[mediagoblin.plugins.ldap]]
+    [[[server1]]]
+    LDAP_SERVER_URI = 'ldap://ldap.testathon.net'
+    LDAP_USER_DN_TEMPLATE = '{username}@testathon.net'
+    LDAP_SEARCH_BASE = 'ou=users,dc=testathon,dc=net'
+    LDAP_IS_ACTIVE_DIRECTORY = 'true'
+    UID_SEARCH_FIELD = 'sAMAccountName'
+    [[[server2]]]
+    ...
+
 .. 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
+   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.
+
+   If you are able, start with SSL & TLS disabled, until you have things working,
+   then enable the security pieces one at a time to help eliminate issues as you
+   are getting started.
+
+How LDAP Authentication works
+=============================
+
+When the LDAP plugin is enabled and all other authentication plugins are
+disabled, attempting to Register or Login will result in the LDAP login form
+being presented to the end user.
+
+The end user will enter their LDAP credentials. A lookup is made against the
+local users table in the GNU Mediagoblin database. If a user with the specified
+username already exists, then the user will be authenticated against the
+directory.
+
+If a user with the specified username does not already exist in the GNU
+Mediagoblin database, then the LDAP authenitcation will be performed. If the
+user does not have permissions in LDAP to authenticate to GNU Mediagoblin,
+they will be presented with a login error.
+
+If they are allowed to authenticate, and ``EMAIL_SEARCH_FIELD`` is not
+specified, the user will be prompted to enter their email address. Upon
+submission, they will be successfully registered and authenticated.
+
+If they are allowed to authenticate and ``EMAIL_SEARCH_FIELD`` is specified,
+an email address lookup will be performed against the directory. The user will
+be prompted to confirm or change their email address. Upon submission, they
+will be successfully registered and authenticated.
+
+
+LDAP Configuration Options
+==========================
+
+LDAP_SERVER_URI
+---------------
+
+This required option is to specify the DNS name or IP address of the LDAP
+server to which your GNU Mediagoblin instance will attempt to bind. In the
+examples, the ports are specified but they are not required.
+
+For plain LDAP, the default port is 387.
+For LDAPS, the default port is 636.
+
+If your instance is using a non-standard port, the port should be indicated.
+
+LDAP_USER_DN_TEMPLATE
+---------------------
+
+This is the required template to use when LDAP searches for a user. It is
+imperative that the value have ``{username}`` in it somewhere, as the string is
+interpolated with the username at the time of login.
+
+The value of this will vary depending up the LDAP schema in the domain. It is
+possible to use either a full path
+( ``cn={username},ou=users,dc=testathon,dc=net`` ) or a UPN
+( ``{username}@testathon.net`` ). Some Active Directory users have reported
+that the second form of the LDAP_USER_DN_TEMPLATE works better.
+
+LDAP_SEARCH_BASE
+----------------
+
+This is required and represents the root of the domain where GNU Mediagoblin
+will search for users' email addresses. If your users should all exist under
+a certain OU, then it is possible to restrict the scope of the search by
+specifying an OU, as in the example. If users are scattered across all of the
+domain, the it is also possible to specify just the domain itself:
+``LDAP_SEARCH_BASE = 'dc=testathon,dc=net'``
+
+EMAIL_SEARCH_FIELD
+------------------
+
+If this optional field is specified in the LDAP configuration, then GNU
+Mediagoblin will lookup the user's email address in LDAP as soon as the user
+authenticates, and the field named in the configuration will used as the search
+field.
+
+If this field is not specified, the user will be asked to input
+their email address when registering.
+
+The default value is None.
+
+UID_SEARCH_FIELD
+----------------
+
+This optional value is used to specify the name of the field that holds the UID.
+For example, imagine that your username in LDAP is ``media.goblin``. For most
+LDAP the search string will need to be ``uid = media.goblin``. In this case,
+the value of UID_SEARCH_FIELD should be set to ``uid``.
+
+However, Active Directory uses a different field for this, and the value should
+be adjusted to be ``sAMAccountName``.
+
+The default value is ``'uid'``.
+
+LDAP_IS_ACTIVE_DIRECTORY
+---------------------
+
+This optional value is used to specify if you are using Active Directory. If that is the
+case, this value should be set to ``'true'``, otherwise it should be left at
+``'false'``
+
+The default value is ``'false'``.
+
+LDAP_START_TLS
+--------------
+
+This optional value will enable TLS for LDAP communications. If your LDAP
+server has a TLS certificate that your GNU Mediagoblin will trust, then enable
+this by setting the value to ``'true'``.
+
+The default value is ``'false'``.
+
+LDAP_FILTER
+-----------
+This optional value will be used to restrict the LDAP authentication to users
+who match the filter criteria. This string is built using LDAP filtering syntax.
+
+For example, to restrict authentication to members of the MediaGoblinGroup
+container that is located in the Groups OU, a filter such as this could be used:
+
+``LDAP_FILTER = '(&(objectClass=person)(memberOf=cn=MediaGoblinGroup,ou=Groups,dc=testathon,dc=net))'``
+
+Any user who is not a member of the MediaGoblinGroup container will be denied authentication.
+
+The default value of this filter is ``(objectClass=person)``