You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ra...@apache.org on 2014/09/10 08:39:39 UTC
[30/40] git commit: CLOUDSTACK-6634
CLOUDSTACK-6634
updated the ldap section in admin guide
Signed-off-by: Pierre-Luc Dion <pd...@apache.org>
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/commit/733b8665
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/tree/733b8665
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/diff/733b8665
Branch: refs/heads/4.4
Commit: 733b8665968f1b4b9d4efde58579b09260c89b7e
Parents: 018c1ad
Author: Rajani Karuturi <ra...@gmail.com>
Authored: Tue Aug 19 16:27:43 2014 +0530
Committer: Pierre-Luc Dion <pd...@apache.org>
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(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/733b8665/source/_static/images/CloudStack-ldap-screen1.png
----------------------------------------------------------------------
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
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/733b8665/source/accounts.rst
----------------------------------------------------------------------
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
-
- http://127.0.0.1:8080/client/api?command=ldapConfig&hostname=127.0.0.1&searchbase=ou%3Dtesting%2Co%3Dproject&queryfilter=%28%26%28uid%3D%25u%29%29&binddn=cn%3DJohn+Singh%2Cou%3Dtesting%2Co%project&bindpass=secret&port=10389&ssl=true&truststore=C%3A%2Fcompany%2Finfo%2Ftrusted.ks&truststorepass=secret&response=json&apiKey=YourAPIKey&signature=YourSignatureHash
-
-The command must be URL-encoded. Here is the same example without the
-URL encoding:
-
-.. code:: bash
-
- http://127.0.0.1:8080/client/api?command=ldapConfig
- &hostname=127.0.0.1
- &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
- http://10.147.29.101:8080/client/api?command=ldapConfig&hostname=10.147.28.250&searchbase=OU%3Dtesting%2CDC%3Dcompany&queryfilter=%28%26%28mail%3D%25e%29%29 &binddn=CN%3DAdministrator%2COU%3Dtesting%2CDC%3Dcompany&bindpass=1111_aaaa&port=389&response=json&apiKey=YourAPIKey&signature=YourSignatureHash
-
-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 openldap)
- (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.
+- ldap.email.attribute: 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:
+~~~~~~~~~~~~~
+- ldap.search.group.principle: this is optional and if set only users from this group are listed.
- (mail=%e)
+LDAP SSL:
+~~~~~~~~~~~~~
+- 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:
+~~~~~~~~~~~~~
+- ldap.group.object: object type of groups within LDAP. Default value is group for AD and groupOfUniqueNames for openldap.
+- ldap.group.user.uniquemember: 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