From efa17a1111db4650fdb2d745b40babf482054585 Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Tue, 23 Dec 2025 12:21:20 +0530 Subject: [PATCH] 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. --- source/adminguide/accounts.rst | 165 ++++++++++++++++++++++++++++++++- 1 file changed, 164 insertions(+), 1 deletion(-) diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index e23d9fe6e1..826bd80fb1 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -564,7 +564,170 @@ 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. + +This procedure uses the **manual certificate import method** used for LDAP/LDAPS +integration in CloudStack and Microsoft AD. + +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 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 + +Configure CloudStack LDAP Settings + +Configure the following LDAP-related settings in the global settings: + +.. list-table:: LDAP Settings + :header-rows: 1 + :widths: 25 25 25 35 + + * - Setting + - OpenLDAP + - Active Directory + - Description + * - ``ldap.basedn`` + - ``OU=APAC,DC=company,DC=com`` + - ``DC=company,DC=com`` + - Sets the base DN for LDAP searches. + * - ``ldap.search.group.principle`` + - ``CN=ACSGroup,DC=company,DC=com`` + - ``CN=ACSGroup,CN=Users,DC=company,DC=com`` + - *(Optional)* If set, only users belonging to this group are listed. + * - ``ldap.bind.principal`` + - ``CN=ACSServiceAccount,OU=APAC,DC=company,DC=com`` + - ``CN=ACSServiceAccount,CN=Users,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 the bind DN. Entered in plain text but stored encrypted. + * - ``ldap.user.object`` + - ``inetOrgPerson`` + - ``user`` + - LDAP object class representing user accounts. + * - ``ldap.email.attribute`` + - ``mail`` + - ``mail`` + - Attribute used to retrieve the user email address. + * - ``ldap.firstname.attribute`` + - ``givenName`` + - ``givenName`` + - Attribute used to retrieve the user first name. + * - ``ldap.lastname.attribute`` + - ``sn`` + - ``sn`` + - Attribute used to retrieve the user last name. + * - ``ldap.group.object`` + - ``groupOfUniqueNames`` + - ``groupOfUniqueNames`` + - LDAP object class representing groups. + * - ``ldap.group.user.uniquemember`` + - ``uniqueMember`` + - ``uniqueMember`` + - Attribute defining user membership within a group. + + +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. +* This procedure as it is applies to the **manual LDAP certificate import method** used by + CloudStack bt can be referenced for other methods as well. +* 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 ----------------------------------------------------------