mirror of
https://github.com/apache/cloudstack.git
synced 2025-12-19 12:03:50 +01:00
136 lines
11 KiB
HTML
136 lines
11 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>3.2. Using an LDAP Server for User Authentication</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.8" /><meta name="package" content="Apache_CloudStack-Admin_Guide-4.0.0-incubating-en-US-1-" /><link rel="home" href="index.html" title="CloudStack Administrator's Guide" /><link rel="up" href="accounts.html" title="Chapter 3. Accounts" /><link rel="prev" href="accounts-users-domains.html" title="3.1. Accounts, Users, and Domains" /><link rel="next" href="user-services-overview.html" title="Chapter 4. User Services Overview" /></head><body><p id="title"><a class="left" href="http://cloudstack.org"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="http://docs.cloudstack.org"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="accounts-users-domains.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="user-services-overview.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="section" id="LDAPserver-for-user-authentication" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="LDAPserver-for-user-authentication">3.2. Using an LDAP Server for User Authentication</h2></div></div></div><div class="para">
|
||
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..
|
||
</div><div class="para">
|
||
To set up LDAP authentication in CloudStack, call the CloudStack API command ldapConfig and provide the following:
|
||
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
|
||
Hostname or IP address and listening port of the LDAP server
|
||
</div></li><li class="listitem"><div class="para">
|
||
Base directory and query filter
|
||
</div></li><li class="listitem"><div class="para">
|
||
Search user DN credentials, which give CloudStack permission to search on the LDAP server
|
||
</div></li><li class="listitem"><div class="para">
|
||
SSL keystore and password, if SSL is used
|
||
</div></li></ul></div><div xml:lang="en-US" class="section" id="example-LDAP-configuration-commands" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="example-LDAP-configuration-commands">3.2.1. Example LDAP Configuration Commands</h3></div></div></div><div class="para">
|
||
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.
|
||
</div><div class="para">
|
||
The following shows an example invocation of ldapConfig with an ApacheDS LDAP server
|
||
</div><pre class="programlisting">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</pre><div class="para">
|
||
The command must be URL-encoded. Here is the same example without the URL encoding:
|
||
</div><pre class="programlisting">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
|
||
</pre><div class="para">
|
||
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.
|
||
</div><pre class="programlisting">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</pre><div class="para">
|
||
The next few sections explain some of the concepts you will need to know when filling out the ldapConfig parameters.
|
||
</div></div><div xml:lang="en-US" class="section" id="search-base" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="search-base">3.2.2. Search Base</h3></div></div></div><div class="para">
|
||
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..
|
||
</div><div class="informaltable"><table border="1"><colgroup><col width="50%" /><col width="50%" /></colgroup><thead><tr><th align="left">
|
||
<div class="para">
|
||
LDAP Server
|
||
</div>
|
||
</th><th align="left">
|
||
<div class="para">
|
||
Example Search Base DN
|
||
</div>
|
||
</th></tr></thead><tbody><tr><td align="left">
|
||
<div class="para">
|
||
ApacheDS
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
ou=testing,o=project
|
||
</div>
|
||
</td></tr><tr><td align="left">
|
||
<div class="para">
|
||
Active Directory
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
OU=testing, DC=company
|
||
</div>
|
||
</td></tr></tbody></table></div></div><div xml:lang="en-US" class="section" id="query-filter" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="query-filter">3.2.3. Query Filter</h3></div></div></div><div class="para">
|
||
The query filter is used to find a mapped user in the external LDAP server. The query filter should uniquely map the CloudPlatform user to LDAP user for a meaningful authentication. For more information about query filter syntax, consult the documentation for your LDAP server.
|
||
</div><div class="para">
|
||
The CloudPlatform query filter wildcards are:
|
||
</div><div class="informaltable"><table border="1"><colgroup><col width="50%" /><col width="50%" /></colgroup><thead><tr><th align="left">
|
||
<div class="para">
|
||
Query Filter Wildcard
|
||
</div>
|
||
</th><th align="left">
|
||
<div class="para">
|
||
Description
|
||
</div>
|
||
</th></tr></thead><tbody><tr><td align="left">
|
||
<div class="para">
|
||
%u
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
User name
|
||
</div>
|
||
</td></tr><tr><td align="left">
|
||
<div class="para">
|
||
%e
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
Email address
|
||
</div>
|
||
</td></tr><tr><td align="left">
|
||
<div class="para">
|
||
%n
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
First and last name
|
||
</div>
|
||
</td></tr></tbody></table></div><div class="para">
|
||
The following examples assume you are using Active Directory, and refer to user attributes from the Active Directory schema.
|
||
</div><div class="para">
|
||
If the CloudPlatform user name is the same as the LDAP user ID:
|
||
</div><pre class="programlisting">(uid=%u)</pre><div class="para">
|
||
If the CloudPlatform user name is the LDAP display name:
|
||
</div><pre class="programlisting">(displayName=%u)</pre><div class="para">
|
||
To find a user by email address:
|
||
</div><pre class="programlisting">(mail=%e)</pre></div><div xml:lang="en-US" class="section" id="search-user-bind-dn" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="search-user-bind-dn">3.2.4. Search User Bind DN</h3></div></div></div><div class="para">
|
||
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.
|
||
</div><div class="informaltable"><table border="1"><colgroup><col width="50%" /><col width="50%" /></colgroup><thead><tr><th align="left">
|
||
<div class="para">
|
||
LDAP Server
|
||
</div>
|
||
</th><th align="left">
|
||
<div class="para">
|
||
Example Bind DN
|
||
</div>
|
||
</th></tr></thead><tbody><tr><td align="left">
|
||
<div class="para">
|
||
ApacheDS
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
cn=Administrator,dc=testing,ou=project,ou=org
|
||
</div>
|
||
</td></tr><tr><td align="left">
|
||
<div class="para">
|
||
Active Directory
|
||
</div>
|
||
</td><td align="left">
|
||
<div class="para">
|
||
CN=Administrator, OU=testing, DC=company, DC=com
|
||
</div>
|
||
</td></tr></tbody></table></div></div><div xml:lang="en-US" class="section" id="SSL-keystore-path-and-password" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="SSL-keystore-path-and-password">3.2.5. SSL Keystore Path and Password</h3></div></div></div><div class="para">
|
||
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.
|
||
</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="accounts-users-domains.html"><strong>Prev</strong>3.1. Accounts, Users, and Domains</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="user-services-overview.html"><strong>Next</strong>Chapter 4. User Services Overview</a></li></ul></body></html>
|