short description of the evolution of LDAP bindings (apache#67)

Author: DaanHoogland

source/adminguide/accounts.rst

@@ -279,17 +279,96 @@ or ApacheDS to authenticate CloudStack end-users. CloudStack will search
 the external LDAP directory tree starting at a specified base directory
 and gets user info such as first name, last name, email and username.
 
-Starting with CloudStack 4.11, an ldap connection per domain can be
-defined.
+Starting with CloudStack 4.11, an LDAP connection per domain can be
+defined. In this domain autosync per account can be configured,
+keeping the users in the domain up to date with their group membership
+in LDAP.
+
+.. Note:: A caveat with this is that ApacheDS does not yet support the virtual 'memberOf' attribute needed to check if a user moved to another account. Microsoft AD and OpenLDAP as well as OpenDJ do support this. It is a planned feature for ApacheDS that can be tracked in https://issues.apache.org/jira/browse/DIRSERVER-1844.
+
+There are now three ways to link LDAP users to CloudStack users. These
+three ways where developed as extensions on top of each other.
+
+To authenticate, in all three cases username and password entered by
+the user are used.
+
+#. **manual import**. A user is explicitely mapped to a domain/account
+   and created as a user in that account.
+
+       #. CloudStack does a search for a user with the given username.
+
+       #. If it exists, it checks if the user is enabled.
+
+       #. If the user is enabled, CloudStack searches for it in LDAP
+          by the configured ``ldap.username.attribute``.
+
+       #. If the LDAP user is found, CloudStack does a bind request
+          with the returned principal for that LDAP user and the
+          entered password.
+
+       #. The authentication result from LAP is honoured.
+
+#. **autoimport**. A domain is configured to import any user if it does
+   not yet exist in that domain. For these users a account by the same
+   name as the user is created on the fly and the user is created in
+   that account.
+
+       #. If the domain is configured to be used with LDAP,
+
+       #. CloudStack searches for it in LDAP by the configured
+          ``ldap.username.attribute``.
+
+       #. If an LDAP user is found is found, CloudStack does a bind
+          request with the returned principal for that LDAP user and
+          the entered password.
+
+       #. If LDAP authentication checks out, CloudStack checks if the
+          authenticated user exists in the domain it is trying to log
+          on to.
+
+          #. If the user exists in CloudStack, it is ensured to be enabled
+
+          #. If it doesn't exist it is created in a new account with
+             the username as names for both account and user.
+
+       #. In case authentication fails the user will be disabled in
+          cloudstack after the configured
+          ``incorrect.login.attempts.allowed`` number of attempts.
+
+#. **autosync**. A domain is configured to use a LDAP server and in this
+   domain a number of accounts are 'mapped' against LDAP groups. Any
+   user that is in one of these configured accounts will be checked against the
+   current state of LDAP and if they exist they will be asserted to be
+   in the right account according to their LDAP group. If they do not
+   exist in LDAP they will be disabled in CloudStack.
+
+       #. If the domain is configured to be used by LDAP,
+
+       #. CloudStack searches for it in LDAP by the configured
+          ``ldap.username.attribute``.
+
+       #. If an LDAP user is found, it is checked for
+          memberships of mapped account, i.e. accounts for which LDAP
+          groups are configured.
+
+          #. If the LDAP user has 0, 2 or more memberships the account
+             is disabled and authentication fails.
+
+       #. CloudStack then does a bind request with the returned
+          principal for that LDAP user and the entered password.
+
+       #. If no CloudStack user exists it is created in the
+          appropriate account.
+
+
+       #. If a CloudStack user exists but is not in the appropriate
+          account its credentials will be moved.
 
-To authenticate, username and password entered by the user are used.
-Cloudstack does a search for a user with the given username. If it
-exists, it does a bind request with DN and password.
 
 To set up LDAP authentication in CloudStack, call the CloudStack API
 command ``addLdapConfiguration`` and provide Hostname or IP address
 and listening port of the LDAP server. Optionally a domain id can be
-given for the domain for which this LDP connection is valid. You could
+given for the domain for which this LDAP connection is valid. You could
 configure multiple servers as well. These are expected to be
 replicas. If one fails, the next one is used.
 
@@ -356,7 +435,7 @@ You could also use api commands: ``listLdapUsers``, ``ldapCreateAccount`` and
 ``importLdapUsers``.
 
 Once LDAP is enabled, the users will not be allowed to changed password
-directly in cloudstack.
+directly in CloudStack.