Document LDAPS configuration for LDAP integration

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 <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
+
+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
 ----------------------------------------------------------