cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [30/40] git commit: CLOUDSTACK-6634
Date Wed, 10 Sep 2014 06:39:39 GMT

updated the ldap section in admin guide

Signed-off-by: Pierre-Luc Dion <>


Branch: refs/heads/4.4
Commit: 733b8665968f1b4b9d4efde58579b09260c89b7e
Parents: 018c1ad
Author: Rajani Karuturi <>
Authored: Tue Aug 19 16:27:43 2014 +0530
Committer: Pierre-Luc Dion <>
Committed: Tue Aug 19 20:14:37 2014 -0400

 .../_static/images/CloudStack-ldap-screen1.png  | Bin 0 -> 23243 bytes
 source/accounts.rst                             | 172 ++++---------------
 2 files changed, 33 insertions(+), 139 deletions(-)
diff --git a/source/_static/images/CloudStack-ldap-screen1.png b/source/_static/images/CloudStack-ldap-screen1.png
new file mode 100644
index 0000000..46032a4
Binary files /dev/null and b/source/_static/images/CloudStack-ldap-screen1.png differ
diff --git a/source/accounts.rst b/source/accounts.rst
index e5d4b6d..a4d95a2 100644
--- a/source/accounts.rst
+++ b/source/accounts.rst
@@ -186,160 +186,54 @@ Using an LDAP Server for User Authentication
 You can use an external LDAP server such as Microsoft Active Directory
-or ApacheDS to authenticate CloudStack end-users. Just map CloudStack
-accounts to the corresponding LDAP accounts using a query filter. The
-query filter is written using the query syntax of the particular LDAP
-server, and can include special wildcard characters provided by
-CloudStack for matching common values such as the user’s email address
-and name. CloudStack will search the external LDAP directory tree
-starting at a specified base directory and return the distinguished name
-(DN) and password of the matching user. This information along with the
-given password is used to authenticate the user..
+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. 
-To set up LDAP authentication in CloudStack, call the CloudStack API
-command ldapConfig and provide the following:
--  Hostname or IP address and listening port of the LDAP server
--  Base directory and query filter
--  Search user DN credentials, which give CloudStack permission to
-   search on the LDAP server
--  SSL keystore and password, if SSL is used
-Example LDAP Configuration Commands
-To understand the examples in this section, you need to know the basic
-concepts behind calling the CloudStack API, which are explained in the
-Developer’s Guide.
-The following shows an example invocation of ldapConfig with an ApacheDS
-LDAP server
-.. code:: bash
-The command must be URL-encoded. Here is the same example without the
-URL encoding:
-.. code:: bash
-   &hostname=
-   &searchbase=ou=testing,o=project
-   &queryfilter=(&(%uid=%u))
-   &binddn=cn=John+Singh,ou=testing,o=project
-   &bindpass=secret
-   &port=10389
-   &ssl=true
-   &truststore=C:/company/info/trusted.ks
-   &truststorepass=secret
-   &response=json
-   &apiKey=YourAPIKey&signature=YourSignatureHash
-The following shows a similar command for Active Directory. Here, the
-search base is the testing group within a company, and the users are
-matched up based on email address.
-.. code:: bash
+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
-The next few sections explain some of the concepts you will need to know
-when filling out the ldapConfig parameters.
-Search Base
-An LDAP query is relative to a given node of the LDAP directory tree,
-called the search base. The search base is the distinguished name (DN)
-of a level of the directory tree below which all users can be found. The
-users can be in the immediate base directory or in some subdirectory.
-The search base may be equivalent to the organization, group, or domain
-name. The syntax for writing a DN varies depending on which LDAP server
-you are using. A full discussion of distinguished names is outside the
-scope of our documentation. The following table shows some examples of
-search bases to find users in the testing department..
-================  =======================
-LDAP Server       Example Search Base DN
-================  =======================
-ApacheDS          OU=testing, O=project
-Active Directory  OU=testing, DC=company
-================  =======================
-Query Filter
-The query filter is used to find a mapped user in the external LDAP
-server. The query filter should uniquely map the CloudStack user to LDAP
-user for a meaningful authentication. For more information about query
-filter syntax, consult the documentation for your LDAP server.
-The CloudStack query filter wildcards are:
-=====================  ====================
-Query Filter Wildcard  Description
-=====================  ====================
-%u                     User name
-%e                     Email address
-%n                     First and last name
-=====================  ====================
-The following examples assume you are using Active Directory, and refer
-to user attributes from the Active Directory schema.
-If the CloudStack user name is the same as the LDAP user ID:
-.. code:: bash
-   (uid=%u)
+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.
+You could configure multiple servers as well. These are expected to be replicas. If one fails,
the next one is used.
-If the CloudStack user name is the LDAP display name:
-.. code:: bash
+The following global configurations should also be configured (the default values are for
-   (displayName=%u)
-To find a user by email address:
+- ldap.basedn:	Sets the basedn for LDAP. Ex: OU=APAC,DC=company,DC=com
+- ldap.bind.principal,ldap.bind.password: DN and password for a user who can list all the
users in the above basedn. Ex: CN=Administrator, OU=APAC, DC=company, DC=com
+- ldap.user.object: object type of users within LDAP. Defaults value is user for AD and interorgperson
for openldap.
+- email attribute within ldap for a user. Default value for AD and
openldap is mail.
+- ldap.firstname.attribute: firstname attribute within ldap for a user. Default value for
AD and openldap is givenname.
+- ldap.username.attribute: username attribute for a user within LDAP. Default value is SAMAccountNAme
for AD and uid for openldap.
-.. code:: bash
+Restricting LDAP users to a group:
+- this is optional and if set only users from this group are
-   (mail=%e)
+- ldap.lastname.attribute: lsatname attribute within ldap for a user. Default value for AD
and openldap is sn.
+- ldap.truststore, ldap.truststore.password:	truststore,password to use for LDAP SSL.	
+LDAP groups:  
+- object type of groups within LDAP. Default value is group for AD and
groupOfUniqueNames for openldap.	
+- attribute for uniquemembers within a group. Default value
is member for AD and uniquemember for openldap.
+Once configured, on Add Account page, you will see an "Add LDAP Account" button which opens
a dialog and the selected users can be imported.
-Search User Bind DN
+.. figure:: _static/images/CloudStack-ldap-screen1.png
+   :align:   center
-The bind DN is the user on the external LDAP server permitted to search
-the LDAP directory within the defined search base. When the DN is
-returned, the DN and passed password are used to authenticate the
-CloudStack user with an LDAP bind. A full discussion of bind DNs is
-outside the scope of our documentation. The following table shows some
-examples of bind DNs.
-================  =================================================
-LDAP Server       Example Bind DN
-================  =================================================
-ApacheDS          CN=Administrator,DC=testing,OU=project,OU=org
-Active Directory  CN=Administrator, OU=testing, DC=company, DC=com
-================  =================================================
+You could also use api commands: listLdapUsers, ldapCreateAccount and importLdapUsers.
-SSL Keystore Path and Password
+Once LDAP is enabled, the users will not be allowed to changed password directly in cloudstack.
-If the LDAP server requires SSL, you need to enable it in the ldapConfig
-command by setting the parameters ssl, truststore, and truststorepass.
-Before enabling SSL for ldapConfig, you need to get the certificate
-which the LDAP server is using and add it to a trusted keystore. You
-will need to know the path to the keystore and the password.
 .. |button to dedicate a zone, pod,cluster, or host| image:: _static/images/dedicate-resource-button.png

View raw message