You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by du...@apache.org on 2014/01/28 13:46:23 UTC
git commit: Update LDAP docs
Updated Branches:
refs/heads/master 48875dfe0 -> 59f1842bb
Update LDAP docs
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/59f1842b
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/tree/59f1842b
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/diff/59f1842b
Branch: refs/heads/master
Commit: 59f1842bb10714312f98cd3d2bfbe3399b82f985
Parents: 48875df
Author: Ian Duffy <ia...@ianduffy.ie>
Authored: Tue Jan 28 12:45:53 2014 +0000
Committer: Ian Duffy <ia...@ianduffy.ie>
Committed: Tue Jan 28 12:45:53 2014 +0000
----------------------------------------------------------------------
.../images/add-ldap-configuration-ad.png | Bin 0 -> 70112 bytes
.../images/add-ldap-configuration-openldap.png | Bin 0 -> 65270 bytes
source/accounts.rst | 210 +++++--------------
3 files changed, 57 insertions(+), 153 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/59f1842b/source/_static/images/add-ldap-configuration-ad.png
----------------------------------------------------------------------
diff --git a/source/_static/images/add-ldap-configuration-ad.png b/source/_static/images/add-ldap-configuration-ad.png
new file mode 100644
index 0000000..d4d3e78
Binary files /dev/null and b/source/_static/images/add-ldap-configuration-ad.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/59f1842b/source/_static/images/add-ldap-configuration-openldap.png
----------------------------------------------------------------------
diff --git a/source/_static/images/add-ldap-configuration-openldap.png b/source/_static/images/add-ldap-configuration-openldap.png
new file mode 100644
index 0000000..70ce579
Binary files /dev/null and b/source/_static/images/add-ldap-configuration-openldap.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs-admin/blob/59f1842b/source/accounts.rst
----------------------------------------------------------------------
diff --git a/source/accounts.rst b/source/accounts.rst
index 154f1c7..497011c 100644
--- a/source/accounts.rst
+++ b/source/accounts.rst
@@ -83,13 +83,13 @@ that domain.
There are several types of dedication available:
--
+-
Explicit dedication. A zone, pod, cluster, or host is dedicated to an
account or domain by the root administrator during initial deployment
and configuration.
--
+-
Strict implicit dedication. A host will not be shared across multiple
accounts. For example, strict implicit dedication is useful for
@@ -97,7 +97,7 @@ There are several types of dedication available:
no host can be shared between different accounts without violating
the desktop software's terms of license.
--
+-
Preferred implicit dedication. The VM will be deployed in dedicated
infrastructure if possible. Otherwise, the VM can be deployed in
@@ -164,181 +164,85 @@ with system VMs or virtual routers can be used for preferred implicit
dedication.
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..
+'''''''''''''''''''''''''''''''''''''''''''''''''
-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.
+You can use an external LDAP server such as Microsoft Active Directory or
+OpenLDAP to authentication Cloudstack end users.
-.. code:: bash
+In order to do this you must:
- 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
+To set up LDAP authentication in CloudStack, call the CloudStack API
+command ldapConfig and provide the following:
-User name
+- Set your LDAP configuration within Cloudstack
+- Create Cloudstack accounts for LDAP Users
-%e
+To setup LDAP authentication in Cloudstack, open the global settings page and
+search for LDAP.
-Email address
+Set ldap.base to match your servers base directory.
-%n
+Review the defaults for the following and ensure they match your schema:
-First and last name
+ - ldap.email.attribute
+ - ldap.firstname.attribute
+ - ldap.lastname.attribute
+ - ldap.username.attribute
+ - ldap.user.object
-The following examples assume you are using Active Directory, and refer
-to user attributes from the Active Directory schema.
+Optionally you can set the following:
-If the CloudStack user name is the same as the LDAP user ID:
+-
-.. code:: bash
+ If you do not want to use anonymous binding you can set ldap.bind.principle
+ and ldap.bind.password as credentials for your LDAP server that will grant
+ Cloudstack permission to perform a search on the LDAP server.
- (uid=%u)
+-
-If the CloudStack user name is the LDAP display name:
+ For SSL support set ldap.truststore to a path on the file system where your
+ trusted store is located. Along with this set ldap.truststore.password as
+ the password that unlocks the truststore.
-.. code:: bash
+-
- (displayName=%u)
+ If you wish to filter down the user set that is granted access to Cloudstack
+ via the LDAP attribute memberof you can do so using
+ ldap.search.group.principle
-To find a user by email address:
+Finally, you can add your LDAP server. To do so select LDAP Configuration from
+the views section within global settings. Click on "Configure LDAP" and fill
+in your server's hostname and port.
-.. code:: bash
+Example LDAP Configuration for Active Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- (mail=%e)
+This shows the configuration settings required for using ActiveDirectory.
-Search User Bind DN
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+- samAccountName - Logon name
+- mail - Email Address
+- cn - Real name
-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.
+Along with this the ldap.user.object name needs to be modified, by default
+ActiveDirectory uses the value "user" for this.
-LDAP Server
+Map the following attributes accordingly as shown below:
-Example Bind DN
+.. image:: ./_static/images/add-ldap-configuration-ad.png
-ApacheDS
+Example LDAP Configuration for OpenLDAP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cn=Administrator,dc=testing,ou=project,ou=org
+This shows the configuration settings required for using OpenLDAP.
+The default values supplied are suited for OpenLDAP.
-Active Directory
+- uid - Login Name
+- mail - Email Address
+- cn - Real name
-CN=Administrator, OU=testing, DC=company, DC=com
+Along with this the ldap.user.object name needs to be modified, by default
+OpenLDAP uses the value "inetOrgPerson" for this.
-SSL Keystore Path and Password
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Map the following attributes accordingly as shown below:
-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.
+.. image:: ./_static/images/add-ldap-configuration-openldap.png
\ No newline at end of file