apache/cloudstack
1
0
Fork 0
mirror of https://github.com/apache/cloudstack.git synced 2025-11-03 04:12:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Change ldap docs to suit new implementation

Browse Source
This commit is contained in:
Ian Duffy 2013-07-12 15:10:48 +01:00 committed by Sebastien Goasguen
parent d0958d0be0
commit 48abf3c98d
10 changed files with 132 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/en-US/LDAP-for-user-authentication.xml Normal file
View File

@ -0,0 +1,42 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="LDAP-for-user-authentication">
<title>Using an LDAP Server for User Authentication</title>
<para>You can use an external LDAP server such as Microsoft Active Directory or OpenLDAP to authenticate &PRODUCT; end-users.</para>
<para>To set up LDAP authentication in &PRODUCT;, open the global settings page and set:</para>
<itemizedlist>
<listitem><para>ldap.basedn - The base directory you want to search within for uses</para></listitem>
<listitem><para>ldap.bind.password - The password you wish to use to bind, this can be blank if the server supports anonymous binding</para></listitem>
<listitem><para>ldap.bind.principal - The account you wish to use to bind, this can be blank if the server supports anonymous binding</para></listitem>
<listitem><para>ldap.email.attribute - The attribute within your LDAP server that holds a value for users email address</para></listitem>
<listitem><para>ldap.realname.attribute - The attribute within your LDAP server that holds a value users realname</para></listitem>
<listitem><para>ldap.user.object - The object class that identifies a user</para></listitem>
<listitem><para>ldap.username.attribute - The attribute within your LDAP server that has a value that will match the cloudstack accounts username field</para></listitem>
</itemizedlist>
<para>Finally you can add LDAP servers from Global Settings -> Select View -> LDAP Configuration. This requires a hostname and port</para>
<xi:include href="example-activedirectory-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="example-openldap-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- Support for SSL has been removed but will be back shortly. -->
<!-- <xi:include href="SSL-keystore-path-and-password.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
</section>

39
docs/en-US/LDAPserver-for-user-authentication.xml
View File

@ -1,39 +0,0 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="LDAPserver-for-user-authentication">
<title>Using an LDAP Server for User Authentication</title>
<para>You can use an external LDAP server such as Microsoft Active Directory or ApacheDS to authenticate &PRODUCT; end-users. Just map &PRODUCT; 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 &PRODUCT; for matching common values such as the user’s email address and name. &PRODUCT; 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..</para>
<para>To set up LDAP authentication in &PRODUCT;, call the &PRODUCT; API command ldapConfig and provide the following:</para>
<itemizedlist>
<listitem><para>Hostname or IP address and listening port of the LDAP server</para></listitem>
<listitem> <para>Base directory and query filter</para></listitem>
<listitem><para>Search user DN credentials, which give &PRODUCT; permission to search on the LDAP server</para></listitem>
<listitem><para>SSL keystore and password, if SSL is used</para></listitem>
</itemizedlist>
<xi:include href="example-LDAP-configuration-commands.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="search-base.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="query-filter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="search-user-bind-dn.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="SSL-keystore-path-and-password.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>

6
docs/en-US/accounts.xml
View File

@ -11,9 +11,9 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@ -25,5 +25,5 @@
<chapter id="accounts">
<title>Accounts</title>
<xi:include href="accounts-users-domains.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="LDAPserver-for-user-authentication.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="LDAP-for-user-authentication.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</chapter>

47
docs/en-US/example-LDAP-configuration-commands.xml
View File

@ -1,47 +0,0 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="example-LDAP-configuration-commands">
<title>Example LDAP Configuration Commands</title>
<para>To understand the examples in this section, you need to know the basic concepts behind calling the &PRODUCT; API, which are explained in the Developer’s Guide.</para>
<para>The following shows an example invocation of ldapConfig with an ApacheDS LDAP server</para>
<programlisting>http://127.0.0.1:8080/client/api?command=ldapConfig&amp;hostname=127.0.0.1&amp;searchbase=ou%3Dtesting%2Co%3Dproject&amp;queryfilter=%28%26%28uid%3D%25u%29%29&amp;binddn=cn%3DJohn+Singh%2Cou%3Dtesting%2Co%project&amp;bindpass=secret&amp;port=10389&amp;ssl=true&amp;truststore=C%3A%2Fcompany%2Finfo%2Ftrusted.ks&amp;truststorepass=secret&amp;response=json&amp;apiKey=YourAPIKey&amp;signature=YourSignatureHash</programlisting>
<para>The command must be URL-encoded. Here is the same example without the URL encoding:</para>
<programlisting>http://127.0.0.1:8080/client/api?command=ldapConfig
&amp;hostname=127.0.0.1
&amp;searchbase=ou=testing,o=project
&amp;queryfilter=(&amp;(%uid=%u))
&amp;binddn=cn=John+Singh,ou=testing,o=project
&amp;bindpass=secret
&amp;port=10389
&amp;ssl=true
&amp;truststore=C:/company/info/trusted.ks
&amp;truststorepass=secret
&amp;response=json
&amp;apiKey=YourAPIKey&amp;signature=YourSignatureHash
</programlisting>
<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.</para>
<programlisting>http://10.147.29.101:8080/client/api?command=ldapConfig&amp;hostname=10.147.28.250&amp;searchbase=OU%3Dtesting%2CDC%3Dcompany&amp;queryfilter=%28%26%28mail%3D%25e%29%29 &amp;binddn=CN%3DAdministrator%2COU%3Dtesting%2CDC%3Dcompany&amp;bindpass=1111_aaaa&amp;port=389&amp;response=json&amp;apiKey=YourAPIKey&amp;signature=YourSignatureHash</programlisting>
<para>The next few sections explain some of the concepts you will need to know when filling out the ldapConfig parameters. </para>
</section>

43
docs/en-US/example-activedirectory-configuration.xml Normal file
View File

@ -0,0 +1,43 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="example-activedirectory-configuration">
<title>Example LDAP Configuration for Active Directory</title>
<para>This shows the configuration settings required for using ActiveDirectory</para>
<itemizedlist>
<listitem><para>samAccountName - Logon name</para></listitem>
<listitem><para>mail - Email Address</para></listitem>
<listitem><para>cn - Real name</para></listitem>
</itemizedlist>
<para>Along with this the ldap.user.object name needs to be modified, by default ActiveDirectory uses the value "user" for this.</para>
<para>Map the following attributes accordingly as shown below within the cloudstack ldap configuration:</para>
<mediaobject>
<imageobject>
<imagedata fileref="./images/add-ldap-configuration-ad.png"/>
</imageobject>
<textobject>
<phrase>add-ldap-configuration-ad.png: example configuration for active directory.</phrase>
</textobject>
</mediaobject>
</section>

44
docs/en-US/example-openldap-configuration.xml Normal file
View File

@ -0,0 +1,44 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="example-openldap-configuration">
<title>Example LDAP Configuration for OpenLdap</title>
<para>This shows the configuration settings required for using OpenLDAP</para>
<para>The default values supplied are suited for OpenLDAP</para>
<itemizedlist>
<listitem><para>uid - Logon name</para></listitem>
<listitem><para>mail - Email Address</para></listitem>
<listitem><para>cn - Real name</para></listitem>
</itemizedlist>
<para>Along with this the ldap.user.object name needs to be modified, by default OpenLDAP uses the value "inetOrgPerson" for this.</para>
<para>Map the following attributes accordingly as shown below within the cloudstack ldap configuration:</para>
<mediaobject>
<imageobject>
<imagedata fileref="./images/add-ldap-configuration-openldap.png"/>
</imageobject>
<textobject>
<phrase>add-ldap-configuration-openldap.png: example configuration for OpenLdap.</phrase>
</textobject>
</mediaobject>
</section>

BIN
docs/en-US/images/add-ldap-configuration-ad.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/en-US/images/add-ldap-configuration-openldap.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

60
docs/en-US/query-filter.xml
View File

@ -1,60 +0,0 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="query-filter">
<title>Query Filter</title>
<para>The query filter is used to find a mapped user in the external LDAP server. The query filter should uniquely map the &PRODUCT; user to LDAP user for a meaningful authentication. For more information about query filter syntax, consult the documentation for your LDAP server.</para>
<para>The &PRODUCT; query filter wildcards are:</para>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry><para>Query Filter Wildcard</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>%u</para></entry>
<entry><para>User name</para></entry>
</row>
<row>
<entry><para>%e</para></entry>
<entry><para>Email address</para></entry>
</row>
<row>
<entry><para>%n</para></entry>
<entry><para>First and last name</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The following examples assume you are using Active Directory, and refer to user attributes from the Active Directory schema.</para>
<para>If the &PRODUCT; user name is the same as the LDAP user ID:</para>
<programlisting>(uid=%u)</programlisting>
<para>If the &PRODUCT; user name is the LDAP display name:</para>
<programlisting>(displayName=%u)</programlisting>
<para>To find a user by email address:</para>
<programlisting>(mail=%e)</programlisting>
</section>

47
docs/en-US/search-user-bind-dn.xml
View File

@ -1,47 +0,0 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<section id="search-user-bind-dn">
<title>Search User Bind DN</title>
<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 &PRODUCT; 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.</para>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry><para>LDAP Server</para></entry>
<entry><para>Example Bind DN</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>ApacheDS</para></entry>
<entry><para>cn=Administrator,dc=testing,ou=project,ou=org</para></entry>
</row>
<row>
<entry><para>Active Directory</para></entry>
<entry><para>CN=Administrator, OU=testing, DC=company, DC=com</para></entry></row>
</tbody>
</tgroup>
</informaltable>
</section>