docs: update LDAP documentation according to user feedback.

docs/auth/auth-ldap-groups.rst

@@ -0,0 +1,112 b''
+.. _config-ldap-groups-ref:
+
+LDAP/AD With User Groups Sync
+-----------------------------
+
+|RCM| supports LDAP (Lightweight Directory Access Protocol) or
+AD (active Directory) authentication.
+All LDAP versions are supported, with the following |RCM| plugins managing each:
+
+* For LDAP/AD with user group sync use ``LDAP + User Groups (egg:rhodecode-enterprise-ee#ldap_group)``
+
+RhodeCode reads all data defined from plugin and creates corresponding
+accounts on local database after receiving data from LDAP. This is done on
+every user log-in including operations like pushing/pulling/checkout.
+In addition group membership is read from LDAP and following operations are done:
+
+- automatic addition of user to |RCM| user group
+- automatic removal of user from any other  |RCM| user groups not specified in LDAP.
+  The removal is done *only* on groups that are marked to be synced from ldap.
+  This setting can be changed in advanced settings on user groups
+- automatic creation of user groups if they aren't yet existing in |RCM|
+- marking user as super-admins if he is a member of any admin group defined in plugin settings
+
+This plugin is available only in EE Edition.
+
+.. important::
+
+   The email used with your |RCE| super-admin account needs to match the email
+   address attached to your admin profile in LDAP. This is because
+   within |RCE| the user email needs to be unique, and multiple users
+   cannot share an email account.
+
+   Likewise, if as an admin you also have a user account, the email address
+   attached to the user account needs to be different.
+
+
+LDAP Configuration Steps
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To configure |LDAP|, use the following steps:
+
+1. From the |RCM| interface, select
+   :menuselection:`Admin --> Authentication`
+2. Enable the ldap+ groups plugin and select :guilabel:`Save`
+3. Select the :guilabel:`Enabled` check box in the plugin configuration section
+4. Add the required LDAP information and :guilabel:`Save`, for more details,
+   see :ref:`config-ldap-groups-examples`
+
+For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
+
+.. _config-ldap-groups-examples:
+
+Example LDAP configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: bash
+
+        # Auth Cache TTL, Defines the caching for authentication to offload LDAP server.
+        # This means that cache result will be saved for 3600 before contacting LDAP server to verify the user access
+        3600
+        # Host, comma seperated format is optionally possible to specify more than 1 server
+        https://ldap1.server.com/ldap-admin/,https://ldap2.server.com/ldap-admin/
+        # Default LDAP Port, use 689 for LDAPS
+        389
+        # Account, used for SimpleBind if LDAP server requires an authentication
+        e.g [e-mail]
+        # Password used for simple bind
+        ldap-user-password
+        # LDAP connection security
+        LDAPS
+        # Certificate checks level
+        DEMAND
+        # Base DN
+        cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com
+        # User Search Base
+        ou=groups,ou=users
+        # LDAP search filter to narrow the results
+        (objectClass=person)
+        # LDAP search scope
+        SUBTREE
+        # Login attribute
+        sAMAccountName
+        # First Name Attribute to read
+        givenName
+        # Last Name Attribute to read
+        sn
+        # Email Attribute to read email address from
+        mail
+        # group extraction method
+        rfc2307bis
+        # Group search base
+        ou=RC-Groups
+        # Group Name Attribute, field to read the group name from
+        sAMAAccountName
+        # User Member of Attribute, field in which groups are stored
+        memberOf
+        # LDAP Group Search Filter, allows narrowing the results
+
+        # Admin Groups. Comma separated list of groups. If user is member of
+        # any of those he will be marked as super-admin in RhodeCode
+        admins, management
+
+
+Below is example setup that can be used with Active Directory and ldap groups.
+
+.. image:: ../images/ldap-groups-example.png
+   :alt: LDAP/AD setup example
+   :scale: 50 %
+
+.. toctree::
+
+   ldap-active-directory
+   ldap-authentication
  No newline at end of file

docs/auth/auth-ldap.rst

@@ -1,14 +1,17 b''
 .. _config-ldap-ref:
 
-LDAP
-----
+LDAP/AD
+-------
 
 |RCM| supports LDAP (Lightweight Directory Access Protocol) or
 AD (active Directory) authentication.
 All LDAP versions are supported, with the following |RCM| plugins managing each:
 
-* For LDAPv3 use ``LDAP (egg:rhodecode-enterprise-ce#ldap)``
-* For LDAPv3 with user group sync use ``LDAP + User Groups (egg:rhodecode-enterprise-ee#ldap_group)``
+* For LDAP or Active Directory use ``LDAP (egg:rhodecode-enterprise-ce#ldap)``
+
+RhodeCode reads all data defined from plugin and creates corresponding
+accounts on local database after receiving data from LDAP. This is done on
+every user log-in including operations like pushing/pulling/checkout.
 
 
 .. important::
@@ -21,6 +24,7 b' All LDAP versions are supported, with th'
    Likewise, if as an admin you also have a user account, the email address
    attached to the user account needs to be different.
 
+
 LDAP Configuration Steps
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -28,7 +32,7 b' To configure |LDAP|, use the following s'
 
 1. From the |RCM| interface, select
    :menuselection:`Admin --> Authentication`
-2. Enable the required plugin and select :guilabel:`Save`
+2. Enable the ldap plugin and select :guilabel:`Save`
 3. Select the :guilabel:`Enabled` check box in the plugin configuration section
 4. Add the required LDAP information and :guilabel:`Save`, for more details,
    see :ref:`config-ldap-examples`
@@ -41,15 +45,16 b' Example LDAP configuration'
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. code-block:: bash
 
-        # Auth Cache TTL
+        # Auth Cache TTL, Defines the caching for authentication to offload LDAP server.
+        # This means that cache result will be saved for 3600 before contacting LDAP server to verify the user access
         3600
-        # Host
+        # Host, comma seperated format is optionally possible to specify more than 1 server
         https://ldap1.server.com/ldap-admin/,https://ldap2.server.com/ldap-admin/
-        # Port
+        # Default LDAP Port, use 689 for LDAPS
         389
-        # Account
-        cn=admin,dc=rhodecode,dc=com
-        # Password
+        # Account, used for SimpleBind if LDAP server requires an authentication
+        e.g [e-mail]
+        # Password used for simple bind
         ldap-user-password
         # LDAP connection security
         LDAPS
@@ -57,32 +62,26 b' Example LDAP configuration'
         DEMAND
         # Base DN
         cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com
-        # User Search Base
-        ou=groups,ou=users
-        # LDAP search filter
+        # LDAP search filter to narrow the results
         (objectClass=person)
         # LDAP search scope
         SUBTREE
         # Login attribute
-        rmagillacuddy
-        # First Name Attribute
-        Rufus
-        # Last Name Attribute
-        Magillacuddy
-        # Email Attribute
-        [e-mail]
-        # User Member of Attribute
-        Organizational Role
-        # Group search base
-        cn=users,ou=groups,dc=rhodecode,dc=com
-        # LDAP Group Search Filter
-        (objectclass=posixGroup)
-        # Group Name Attribute
-        users
-        # Group Member Of Attribute
-        cn
-        # Admin Groups
-        admin,devops,qa
+        sAMAccountName
+        # First Name Attribute to read
+        givenName
+        # Last Name Attribute to read
+        sn
+        # Email Attribute to read email address from
+        mail
+
+
+Below is example setup that can be used with Active Directory/LDAP server.
+
+.. image:: ../images/ldap-example.png
+   :alt: LDAP/AD setup example
+   :scale: 50 %
+
 
 .. toctree::
 

docs/auth/auth.rst

@@ -3,35 +3,30 b''
 Authentication Options
 ======================
 
-|RCE| provides a built in authentication plugin
-``rhodecode.lib.auth_rhodecode``. This is enabled by default and accessed
-through the administrative interface. Additionally,
-|RCE| provides a Pluggable Authentication System (PAS). This gives the
+|RCE| provides a built in authentication against its own database. This is
+implemented using ``rhodecode.lib.auth_rhodecode`` plugin. This plugin is
+enabled by default.
+Additionally, |RCE| provides a Pluggable Authentication System. This gives the
 administrator greater control over how users authenticate with the system.
 
 .. important::
 
   You can disable the built in |RCM| authentication plugin
   ``rhodecode.lib.auth_rhodecode`` and force all authentication to go
-  through your authentication plugin. However, if you do this,
-  and your external authentication tools fails, you will be unable to
-  access |RCM|.
+  through your authentication plugin of choice e.g LDAP only.
+  However, if you do this, and your external authentication tools fails,
+  you will be unable to access |RCM|.
 
 |RCM| comes with the following user authentication management plugins:
 
-.. only:: latex
-
-    * :ref:`config-ldap-ref`
-    * :ref:`config-pam-ref`
-    * :ref:`config-crowd-ref`
-    * :ref:`config-token-ref`
 
 .. toctree::
 
-    ldap-config-steps
-    crowd-auth
-    pam-auth
-    token-auth
+    auth-ldap
+    auth-ldap-groups
+    auth-crowd
+    auth-pam
+    auth-token
     ssh-connection
 
 

docs/conf.py

@@ -104,7 +104,6 b' exclude_patterns = ['
 
     # Other RST files
     'admin/rhodecode-backup.rst',
-    'auth/ldap-configuration-example.rst',
     'issue-trackers/redmine.rst',
     'known-issues/error-msg-guide.rst',
     'tutorials/docs-build.rst',