This is an automated email from the ASF dual-hosted git repository.
weizhouapache pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new c93090d1 Document LDAPS configuration for LDAP integration (#612)
c93090d1 is described below
commit c93090d14d9730f9d66856c78ba4ebe4b3abf29e
Author: Jithin Raju <[email protected]>
AuthorDate: Tue Sep 1 17:43:24 2026 +0530
Document LDAPS configuration for LDAP integration (#612)
* Document LDAPS configuration for LDAP integration
Added detailed instructions for configuring LDAPS/LDAP SSL trust for LDAP
integration with Apache CloudStack, including certificate retrieval, truststore
creation, and LDAP settings configuration.
* Refactor LDAP settings table format
Reformatted LDAP settings table for clarity and consistency.
* Update LDAP settings format
Update LDAP settings format
* Revise LDAP settings and restart instructions
Updated LDAP settings and descriptions for clarity. Added instructions for
restarting CloudStack Management Services after configuration changes.
* Fix typo: change microsftad to microsoftad in LDAP provider settings
* Improve LDAP Settings table layout and fix typo
- Adjust LDAP Settings table column widths to 20-25-55 for better
readability
- Add table-layout:fixed CSS to enforce column width specifications
- Fix typo: microsftad -> microsoftad in ldap.provider setting
---------
Co-authored-by: Jithin Raju <[email protected]>
---
source/_static/theme_overrides.css | 12 +++
source/adminguide/accounts.rst | 191 ++++++++++++++++++++++++++++++-------
2 files changed, 170 insertions(+), 33 deletions(-)
diff --git a/source/_static/theme_overrides.css
b/source/_static/theme_overrides.css
index f8e561cc..7d1a67b0 100644
--- a/source/_static/theme_overrides.css
+++ b/source/_static/theme_overrides.css
@@ -11,6 +11,18 @@
overflow: visible;
}
+/* Force table to respect column widths */
+.wy-table-responsive table {
+ table-layout: fixed;
+ width: 100%;
+}
+
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+ overflow-wrap: break-word;
+ word-wrap: break-word;
+}
+
.rst-content li {
padding-top: 4px;
}
diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst
index 55d27670..e27ea7b9 100644
--- a/source/adminguide/accounts.rst
+++ b/source/adminguide/accounts.rst
@@ -488,51 +488,72 @@ OpenLDAP)
.. list-table:: LDAP Settings
:header-rows: 1
+ :widths: 20 25 55
* - Setting
- - OpenLDAP
- - Active Directory
+ - OpenLDAP / Active Directory
- Description
* - ``ldap.basedn``
- - `Ex: OU=APAC, DC=company, DC=com`
- - `Ex: DC=company, DC=com`
- - Sets the basedn for LDAP.
+ - ``OU=APAC,DC=company,DC=com``
+ - Sets the base DN for LDAP searches.
* - ``ldap.search.group.principle``
- - `Ex: CN=ACSGroup, DC=company, DC=com`
- - `Ex: CN=ACSGroup, CN=Users, DC=company, DC=com`
- - (optional) if set only Users from this group are listed.
+ - ``CN=ACSGroup,DC=company,DC=com``
+ - *(Optional)* If set, only users belonging to this group are listed.
* - ``ldap.bind.principal``
- - `Ex: CN=ACSServiceAccount, OU=APAC, DC=company, DC=com`
- - `Ex: CN=ACSServiceAccount, CN=Users, DC=company, DC=com`
- - Service account that can list all the Users in the above basedn. Avoid
using privileged account such as Administrator.
+ - ``CN=ACSServiceAccount,OU=APAC,DC=company,DC=com``
+ - Service account used to list users under the configured base DN.
+ Avoid using privileged accounts such as ``Administrator``.
* - ``ldap.bind.password``
- - `******************`
- - `******************`
- - Password for a DN User. Is entered in plain text but gets stored
encrypted.
+ - ``****************``
+ - Password for the bind DN. Entered in plain text but stored encrypted.
* - ``ldap.user.object``
- - `interorgperson`
- - `user`
- - Object type of Users within LDAP.
+ - * OpenLDAP: ``inetOrgPerson``
+ * Active Directory: ``user``
+ - LDAP object class representing user accounts.
* - ``ldap.email.attribute``
- - `mail`
- - `mail`
- - Email attribute within ldap for a User.
+ - ``mail``
+ - Attribute used to retrieve the user email address.
* - ``ldap.firstname.attribute``
- - `givenname`
- - `givenname`
- - firstname attribute within ldap for a User.
+ - ``givenName``
+ - Attribute used to retrieve the user first name.
* - ``ldap.lastname.attribute``
- - `sn`
- - `sn`
- - lastname attribute within ldap for a User.
+ - ``sn``
+ - Attribute used to retrieve the user last name.
* - ``ldap.group.object``
- - `groupOfUniqueNames`
- - `groupOfUniqueNames`
- - Object type of groups within LDAP.
+ - * OpenLDAP: ``groupOfUniqueNames``
+ * Active Directory: ``group``
+ - LDAP object class representing groups.
* - ``ldap.group.user.uniquemember``
- - `uniquemember`
- - `uniquemember`
- - Attribute for uniquemembers within a group.
+ - ``uniqueMember``
+ - Attribute defining user membership within a group.
+ * - ``ldap.username.attribute``
+ - * OpenLDAP: ``uid``
+ * Active Directory: ``sAMAccountName``
+ - Sets the username attribute used within LDAP.
+ * - ``ldap.nested.groups.enable``
+ - ``true``
+ - If true, nested groups will also be queried.
+ * - ``ldap.provider``
+ - * OpenLDAP: ``openldap``
+ * Active Directory: ``microsoftad``
+ - LDAP provider (e.g. ``openldap``, ``microsoftad``).
+
+
+
+Restart CloudStack Management Services
+
+
+After updating the configuration, restart the CloudStack Management Server:
+
+.. code-block:: bash
+
+ systemctl restart cloudstack-management
+
+Notes
+
+
+* Configuration changes do not take effect until the management service is
restarted.
+
.. note:: ``ldap.search.group.principle`` is required when using
``linkaccounttoldap``.
@@ -566,7 +587,111 @@ You will need to know the path to the keystore and the
password.
- ``ldap.truststore.password`` : truststore password
-.. |button to dedicate a zone, pod,cluster, or host| image::
/_static/images/dedicate-resource-button.png
+Configuring LDAPS/ LDAP SSL Trust for LDAP Integration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When integrating Apache CloudStack with an LDAP directory over **LDAPS (TCP
636)**,
+the CloudStack Management Server must trust the TLS certificate presented by
the
+LDAP server. This trust is established by importing the LDAP server certificate
+into a Java truststore and configuring CloudStack to use that truststore for
LDAP
+communication.
+
+Retrieve the LDAP Server Certificate
+
+
+1. On a CloudStack Management Server, navigate to the CloudStack management
+ configuration directory:
+
+ .. code-block:: bash
+
+ cd /etc/cloudstack/management/
+
+2. Retrieve **only the LDAP server certificate** (not the full certificate
chain
+ or root CA):
+
+ .. code-block:: bash
+
+ echo "" | openssl s_client -connect ldap.example.com:636 -showcerts
2>/dev/null | \
+ openssl x509 -out ldap-server-certificate.pem
+
+3. Verify the retrieved certificate:
+
+ .. code-block:: bash
+
+ openssl x509 -in ldap-server-certificate.pem -noout -text
+
+ Ensure that the certificate details (Subject, Issuer, and validity dates)
+ match the LDAP server configuration.
+
+Create and Populate a Java Truststore
+
+
+1. Import the LDAP server certificate into a Java KeyStore (JKS):
+
+ .. code-block:: bash
+
+ keytool -importcert \
+ -alias ldap-server \
+ -file ldap-server-certificate.pem \
+ -trustcacerts \
+ -keystore cloudstack-ldap-truststore.jks \
+ -storetype JKS
+
+2. Verify the contents of the truststore:
+
+ .. code-block:: bash
+
+ keytool -v -list -keystore cloudstack-ldap-truststore.jks
+
+3. Verify file permissions:
+
+ .. code-block:: bash
+
+ ls -l /etc/cloudstack/management/cloudstack-ldap-truststore.jks
+
+ Example output:
+
+ .. code-block:: text
+
+ -rw-r--r-- 1 root root 1332 <date> cloudstack-ldap-truststore.jks
+
+ Ensure that the CloudStack Management Server process has read access to the
+ truststore file.
+
+Distribute the Truststore
+
+
+If multiple CloudStack Management Servers are deployed:
+
+* Copy the truststore file to **all management servers**
+* Ensure the **file path is identical** on each server
+* Ensure file permissions allow CloudStack to read the truststore
+
+Example path:
+
+::
+
+ /etc/cloudstack/management/cloudstack-ldap-truststore.jks
+
+
+
+Restart CloudStack Management Services after updating the global settings.
+
+
+After updating the configuration, restart the CloudStack Management Server:
+
+.. code-block:: bash
+
+ systemctl restart cloudstack-management
+
+Notes
+
+
+* Configuration changes do not take effect until the management service is
restarted.
+* Certificate renewal on the LDAP server requires repeating this procedure and
+ redeploying the updated truststore.
+
+
Using a SAML 2.0 Identity Provider for User Authentication
----------------------------------------------------------
