Updated Branches: refs/heads/master d0958d0be -> 48abf3c98
Change ldap docs to suit new implementation Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/48abf3c9 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/48abf3c9 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/48abf3c9 Branch: refs/heads/master Commit: 48abf3c98dfe0f1aad6740e09366372136fccc69 Parents: d0958d0 Author: Ian Duffy <[email protected]> Authored: Fri Jul 12 15:10:48 2013 +0100 Committer: Sebastien Goasguen <[email protected]> Committed: Fri Jul 12 10:39:53 2013 -0400 ---------------------------------------------------------------------- docs/en-US/LDAP-for-user-authentication.xml | 42 +++++++++++++ .../LDAPserver-for-user-authentication.xml | 39 ------------ docs/en-US/accounts.xml | 6 +- .../example-LDAP-configuration-commands.xml | 47 --------------- .../example-activedirectory-configuration.xml | 43 +++++++++++++ docs/en-US/example-openldap-configuration.xml | 44 ++++++++++++++ docs/en-US/images/add-ldap-configuration-ad.png | Bin 0 -> 31803 bytes .../images/add-ldap-configuration-openldap.png | Bin 0 -> 30176 bytes docs/en-US/query-filter.xml | 60 ------------------- docs/en-US/search-user-bind-dn.xml | 47 --------------- 10 files changed, 132 insertions(+), 196 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/LDAP-for-user-authentication.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/LDAP-for-user-authentication.xml b/docs/en-US/LDAP-for-user-authentication.xml new file mode 100644 index 0000000..61f204c --- /dev/null +++ b/docs/en-US/LDAP-for-user-authentication.xml @@ -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> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/LDAPserver-for-user-authentication.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/LDAPserver-for-user-authentication.xml b/docs/en-US/LDAPserver-for-user-authentication.xml deleted file mode 100644 index 376631c..0000000 --- a/docs/en-US/LDAPserver-for-user-authentication.xml +++ /dev/null @@ -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> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/accounts.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/accounts.xml b/docs/en-US/accounts.xml index aa62f68..1c4454c 100644 --- a/docs/en-US/accounts.xml +++ b/docs/en-US/accounts.xml @@ -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> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/example-LDAP-configuration-commands.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/example-LDAP-configuration-commands.xml b/docs/en-US/example-LDAP-configuration-commands.xml deleted file mode 100644 index e557386..0000000 --- a/docs/en-US/example-LDAP-configuration-commands.xml +++ /dev/null @@ -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&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</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 -&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 - </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&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</programlisting> - <para>The next few sections explain some of the concepts you will need to know when filling out the ldapConfig parameters. </para> -</section> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/example-activedirectory-configuration.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/example-activedirectory-configuration.xml b/docs/en-US/example-activedirectory-configuration.xml new file mode 100644 index 0000000..98ab5da --- /dev/null +++ b/docs/en-US/example-activedirectory-configuration.xml @@ -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> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/example-openldap-configuration.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/example-openldap-configuration.xml b/docs/en-US/example-openldap-configuration.xml new file mode 100644 index 0000000..2b28032 --- /dev/null +++ b/docs/en-US/example-openldap-configuration.xml @@ -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> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/images/add-ldap-configuration-ad.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/add-ldap-configuration-ad.png b/docs/en-US/images/add-ldap-configuration-ad.png new file mode 100644 index 0000000..7d0aa0f Binary files /dev/null and b/docs/en-US/images/add-ldap-configuration-ad.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/images/add-ldap-configuration-openldap.png ---------------------------------------------------------------------- diff --git a/docs/en-US/images/add-ldap-configuration-openldap.png b/docs/en-US/images/add-ldap-configuration-openldap.png new file mode 100644 index 0000000..c801275 Binary files /dev/null and b/docs/en-US/images/add-ldap-configuration-openldap.png differ http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/query-filter.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/query-filter.xml b/docs/en-US/query-filter.xml deleted file mode 100644 index 1c0e493..0000000 --- a/docs/en-US/query-filter.xml +++ /dev/null @@ -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> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/48abf3c9/docs/en-US/search-user-bind-dn.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/search-user-bind-dn.xml b/docs/en-US/search-user-bind-dn.xml deleted file mode 100644 index a2d8b6a..0000000 --- a/docs/en-US/search-user-bind-dn.xml +++ /dev/null @@ -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>
