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

File 0001-Fix-LDAP-For-Active-Directory_docs.patch, 9.5 KB (added by Meaulnes, 6 years ago)

LDAP Active Directory patch - doc changes

  • mediagoblin/plugins/ldap/README.rst

    From 473d9abaebdf75e3bc9dc59f012a8faf070b69b7 Mon Sep 17 00:00:00 2001
    From: Kirk Gleason <kgleason@bloominsuranceagency.com>
    Date: Sun, 15 Apr 2018 13:59:12 -0400
    Subject: [PATCH] Rollback README for LDAP plugin to match stable so new patch
     can be applied. Only whitespace and capitalization changes are lost.
    Added in Active Directory config flags that are required. Adjusted email search so that it returns the entire user object. Made the search field variable.
    Updated docs to add in AD specific bits
    Converted the LDAP_START_TLS option from string to bool
    Added some explanation to all of the LDAP configuration options.
    Converted LDAP_ACTIVE_DIRECTORY from bool to string
    Converted bool config options to string
    Ignore PyCharm artifacts, package-lock, and pytest cache files.
    Added in checks for all of the possible LDAP config variables, and tested for them. It is not yet properly handling required values, but it's no different than when I started looking at it.
    Updated the docs to reflect the optional config values.
    More details on how authenitcation works are in the documentation. The logic of EMAIL_SEARCH_FIELD is more clear.
    EMAIL_SEARCH_FIELD defaults to None, and is used to trigger or skip the email lookup
    Active Direcotry configuration option is more clearly named.
    Can now restrcit ability to LDAP auth based on group membership.
    Signed-off-by: Kirk Gleason <kgleason@bloominsuranceagency.com>
    Correct capitalization on LDAP in documentation.
     mediagoblin/plugins/ldap/README.rst | 163 ++++++++++++++++++++++++++--
     1 file changed, 153 insertions(+), 10 deletions(-)
    diff --git a/mediagoblin/plugins/ldap/README.rst b/mediagoblin/plugins/ldap/README.rst
    index 049b5c4d..0857de59 100644
    a b  
    2020.. Warning::
    21    This plugin is not compatible with the other authentication plugins.
     21    This plugin is not compatible with the other authentication plugins.
     22    All other authentication plugins will need to be disabled in order
     23    for this plugin to work.
    23 This plugin allow your GNU MediaGoblin instance to authenticate against an
     25This plugin allow your GNU Mediagoblin instance to authenticate against an
    2426LDAP server.
    26 Set up the LDAP plugin
     28Set up the ldap plugin
    29311. Install the ``python-ldap`` package.
    Set up the LDAP plugin  
    3335    [[mediagoblin.plugins.ldap]]
    35 Configuring the LDAP plugin
     37Configuring the ldap plugin
    38 This plugin allows you to use multiple LDAP servers for authentication.
     40This plugin allows you to use multiple ldap servers for authentication.
    4042In order to configure a server, add the following to you MediaGoblin .ini file
    41 under the LDAP plugin::
     43under the ldap plugin::
    4345    [[mediagoblin.plugins.ldap]]
    4446    [[[server1]]]
    4547    LDAP_SERVER_URI = 'ldap://ldap.testathon.net:389'
    4648    LDAP_USER_DN_TEMPLATE = 'cn={username},ou=users,dc=testathon,dc=net'
     49    LDAP_SEARCH_BASE = 'ou=users,dc=testathon,dc=net'
    4750    [[[server2]]]
    4851    ...
    5053Make any necessary changes to the above to work with your sever. Make sure
    5154``{username}`` is where the username should be in LDAP_USER_DN_TEMPLATE.
    53 If you would like to fetch the users email from the LDAP server upon account
     56If you would like to fetch the users email from the ldap server upon account
    5457registration, add ``LDAP_SEARCH_BASE = 'ou=users,dc=testathon,dc=net'`` and
    5558``EMAIL_SEARCH_FIELD = 'mail'`` under you server configuration in your
    5659MediaGoblin .ini file.
     61If you are using Microsoft's Active Directory for your LDAP provider, you will
     62want to specify the following::
     64    [[mediagoblin.plugins.ldap]]
     65    [[[server1]]]
     66    LDAP_SERVER_URI = 'ldap://ldap.testathon.net'
     67    LDAP_USER_DN_TEMPLATE = '{username}@testathon.net'
     68    LDAP_SEARCH_BASE = 'ou=users,dc=testathon,dc=net'
     69    LDAP_IS_ACTIVE_DIRECTORY = 'true'
     70    UID_SEARCH_FIELD = 'sAMAccountName'
     71    [[[server2]]]
     72    ...
    5874.. Warning::
    5975   By default, this plugin provides no encryption when communicating with the
    60    LDAP servers. If you would like to use an SSL connection, change
    61    LDAP_SERVER_URI to use ``ldaps://`` and whichever port you use. Default LDAP
     76   ldap servers. If you would like to use an SSL connection, change
     77   LDAP_SERVER_URI to use ``ldaps://`` and whichever port you use. Default ldap
    6278   port for SSL connections is 636. If you would like to use a TLS connection,
    6379   add ``LDAP_START_TLS = 'true'`` under your server configuration in your
    6480   MediaGoblin .ini file.
     82   If you are able, start with SSL & TLS disabled, until you have things working,
     83   then enable the security pieces one at a time to help eliminate issues as you
     84   are getting started.
     86How LDAP Authentication works
     89When the LDAP plugin is enabled and all other authentication plugins are
     90disabled, attempting to Register or Login will result in the LDAP login form
     91being presented to the end user.
     93The end user will enter their LDAP credentials. A lookup is made against the
     94local users table in the GNU Mediagoblin database. If a user with the specified
     95username already exists, then the user will be authenticated against the
     98If a user with the specified username does not already exist in the GNU
     99Mediagoblin database, then the LDAP authenitcation will be performed. If the
     100user does not have permissions in LDAP to authenticate to GNU Mediagoblin,
     101they will be presented with a login error.
     103If they are allowed to authenticate, and ``EMAIL_SEARCH_FIELD`` is not
     104specified, the user will be prompted to enter their email address. Upon
     105submission, they will be successfully registered and authenticated.
     107If they are allowed to authenticate and ``EMAIL_SEARCH_FIELD`` is specified,
     108an email address lookup will be performed against the directory. The user will
     109be prompted to confirm or change their email address. Upon submission, they
     110will be successfully registered and authenticated.
     113LDAP Configuration Options
     119This required option is to specify the DNS name or IP address of the LDAP
     120server to which your GNU Mediagoblin instance will attempt to bind. In the
     121examples, the ports are specified but they are not required.
     123For plain LDAP, the default port is 387.
     124For LDAPS, the default port is 636.
     126If your instance is using a non-standard port, the port should be indicated.
     131This is the required template to use when LDAP searches for a user. It is
     132imperative that the value have ``{username}`` in it somewhere, as the string is
     133interpolated with the username at the time of login.
     135The value of this will vary depending up the LDAP schema in the domain. It is
     136possible to use either a full path
     137( ``cn={username},ou=users,dc=testathon,dc=net`` ) or a UPN
     138( ``{username}@testathon.net`` ). Some Active Directory users have reported
     139that the second form of the LDAP_USER_DN_TEMPLATE works better.
     144This is required and represents the root of the domain where GNU Mediagoblin
     145will search for users' email addresses. If your users should all exist under
     146a certain OU, then it is possible to restrict the scope of the search by
     147specifying an OU, as in the example. If users are scattered across all of the
     148domain, the it is also possible to specify just the domain itself:
     149``LDAP_SEARCH_BASE = 'dc=testathon,dc=net'``
     154If this optional field is specified in the LDAP configuration, then GNU
     155Mediagoblin will lookup the user's email address in LDAP as soon as the user
     156authenticates, and the field named in the configuration will used as the search
     159If this field is not specified, the user will be asked to input
     160their email address when registering.
     162The default value is None.
     167This optional value is used to specify the name of the field that holds the UID.
     168For example, imagine that your username in LDAP is ``media.goblin``. For most
     169LDAP the search string will need to be ``uid = media.goblin``. In this case,
     170the value of UID_SEARCH_FIELD should be set to ``uid``.
     172However, Active Directory uses a different field for this, and the value should
     173be adjusted to be ``sAMAccountName``.
     175The default value is ``'uid'``.
     180This optional value is used to specify if you are using Active Directory. If that is the
     181case, this value should be set to ``'true'``, otherwise it should be left at
     184The default value is ``'false'``.
     189This optional value will enable TLS for LDAP communications. If your LDAP
     190server has a TLS certificate that your GNU Mediagoblin will trust, then enable
     191this by setting the value to ``'true'``.
     193The default value is ``'false'``.
     197This optional value will be used to restrict the LDAP authentication to users
     198who match the filter criteria. This string is built using LDAP filtering syntax.
     200For example, to restrict authentication to members of the MediaGoblinGroup
     201container that is located in the Groups OU, a filter such as this could be used:
     203``LDAP_FILTER = '(&(objectClass=person)(memberOf=cn=MediaGoblinGroup,ou=Groups,dc=testathon,dc=net))'``
     205Any user who is not a member of the MediaGoblinGroup container will be denied authentication.
     207The default value of this filter is ``(objectClass=person)``