From efa17a1111db4650fdb2d745b40babf482054585 Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Tue, 23 Dec 2025 12:21:20 +0530 Subject: [PATCH 1/6] 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 ---------------------------------------------------------- From 5985fe205bf3dbce6a86e128cbf1f33edf2cb10a Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Wed, 31 Dec 2025 14:45:15 +0530 Subject: [PATCH 2/6] Refactor LDAP settings table format Reformatted LDAP settings table for clarity and consistency. --- source/adminguide/accounts.rst | 76 +++++++++++++--------------------- 1 file changed, 28 insertions(+), 48 deletions(-) diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index 826bd80fb1..ef8ddd0bd5 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -657,55 +657,35 @@ 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 +.. cssclass:: table-striped table-bordered table-hover - * - 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. +==================================== ================================ ===================================================================== +Setting Example Value Description +==================================== ================================ ===================================================================== +ldap.basedn DC=company,DC=com Base DN for LDAP searches. + +ldap.search.group.principle CN=ACSGroup,CN=Users,DC=company,DC=com + *(Optional)* If set, only users belonging to this group are listed. + +ldap.bind.principal 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 user LDAP object class representing user accounts. + +ldap.email.attribute mail Attribute used to retrieve the user email address. + +ldap.firstname.attribute givenName Attribute used to retrieve the user first name. + +ldap.lastname.attribute sn Attribute used to retrieve the user last name. + +ldap.group.object groupOfUniqueNames LDAP object class representing groups. + +ldap.group.user.uniquemember uniqueMember Attribute defining user membership within a group. +==================================== ================================ ===================================================================== Restart CloudStack Management Services From 359f743ed4a6a945d5a01dfc2eed7749605ea4a5 Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Wed, 31 Dec 2025 14:54:50 +0530 Subject: [PATCH 3/6] Update LDAP settings format Update LDAP settings format --- source/adminguide/accounts.rst | 63 +++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index ef8ddd0bd5..bc1709080d 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -657,35 +657,44 @@ Configure CloudStack LDAP Settings Configure the following LDAP-related settings in the global settings: -.. cssclass:: table-striped table-bordered table-hover - -==================================== ================================ ===================================================================== -Setting Example Value Description -==================================== ================================ ===================================================================== -ldap.basedn DC=company,DC=com Base DN for LDAP searches. - -ldap.search.group.principle CN=ACSGroup,CN=Users,DC=company,DC=com - *(Optional)* If set, only users belonging to this group are listed. - -ldap.bind.principal 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 user LDAP object class representing user accounts. - -ldap.email.attribute mail Attribute used to retrieve the user email address. - -ldap.firstname.attribute givenName Attribute used to retrieve the user first name. - -ldap.lastname.attribute sn Attribute used to retrieve the user last name. +.. list-table:: LDAP Settings (Active Directory) + :header-rows: 1 -ldap.group.object groupOfUniqueNames LDAP object class representing groups. + * - Setting + - Active Directory + - Description + * - ``ldap.basedn`` + - ``DC=company,DC=com`` + - Sets the base DN for LDAP searches. + * - ``ldap.search.group.principle`` + - ``CN=ACSGroup,CN=Users,DC=company,DC=com`` + - *(Optional)* If set, only users belonging to this group are listed. + * - ``ldap.bind.principle`` + - ``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`` + - ``user`` + - LDAP object class representing user accounts. + * - ``ldap.email.attribute`` + - ``mail`` + - Attribute used to retrieve the user email address. + * - ``ldap.firstname.attribute`` + - ``givenName`` + - Attribute used to retrieve the user first name. + * - ``ldap.lastname.attribute`` + - ``sn`` + - Attribute used to retrieve the user last name. + * - ``ldap.group.object`` + - ``groupOfUniqueNames`` + - LDAP object class representing groups. + * - ``ldap.group.user.uniquemember`` + - ``uniqueMember`` + - Attribute defining user membership within a group. -ldap.group.user.uniquemember uniqueMember Attribute defining user membership within a group. -==================================== ================================ ===================================================================== Restart CloudStack Management Services From 59736619b73c0d98daf7bda0348e28cf631571b5 Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Wed, 7 Jan 2026 11:35:38 +0530 Subject: [PATCH 4/6] Revise LDAP settings and restart instructions Updated LDAP settings and descriptions for clarity. Added instructions for restarting CloudStack Management Services after configuration changes. --- source/adminguide/accounts.rst | 134 +++++++++++++-------------------- 1 file changed, 53 insertions(+), 81 deletions(-) diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index bc1709080d..74c185b12f 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -488,49 +488,69 @@ OpenLDAP) :header-rows: 1 * - 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: ``microsftad`` + - 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``. @@ -573,9 +593,6 @@ 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 @@ -653,51 +670,9 @@ 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 (Active Directory) - :header-rows: 1 - - * - Setting - - Active Directory - - Description - * - ``ldap.basedn`` - - ``DC=company,DC=com`` - - Sets the base DN for LDAP searches. - * - ``ldap.search.group.principle`` - - ``CN=ACSGroup,CN=Users,DC=company,DC=com`` - - *(Optional)* If set, only users belonging to this group are listed. - * - ``ldap.bind.principle`` - - ``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`` - - ``user`` - - LDAP object class representing user accounts. - * - ``ldap.email.attribute`` - - ``mail`` - - Attribute used to retrieve the user email address. - * - ``ldap.firstname.attribute`` - - ``givenName`` - - Attribute used to retrieve the user first name. - * - ``ldap.lastname.attribute`` - - ``sn`` - - Attribute used to retrieve the user last name. - * - ``ldap.group.object`` - - ``groupOfUniqueNames`` - - LDAP object class representing groups. - * - ``ldap.group.user.uniquemember`` - - ``uniqueMember`` - - Attribute defining user membership within a group. - - -Restart CloudStack Management Services +Restart CloudStack Management Services after updating the global settings. After updating the configuration, restart the CloudStack Management Server: @@ -710,14 +685,11 @@ 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 ---------------------------------------------------------- From 8403b6a853e82b51a736859de90370aa6fa9f29d Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Mon, 12 Jan 2026 11:08:43 +0530 Subject: [PATCH 5/6] Fix typo: change microsftad to microsoftad in LDAP provider settings --- source/adminguide/accounts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index 74c185b12f..48c5abae3f 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -532,7 +532,7 @@ OpenLDAP) - If true, nested groups will also be queried. * - ``ldap.provider`` - * OpenLDAP: ``openldap`` - * Active Directory: ``microsftad`` + * Active Directory: ``microsoftad`` - LDAP provider (e.g. ``openldap``, ``microsoftad``). From ff102bbd46efa3616a20116bf38a9cafc8683190 Mon Sep 17 00:00:00 2001 From: Jithin Raju Date: Mon, 12 Jan 2026 11:16:15 +0530 Subject: [PATCH 6/6] 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 --- source/_static/theme_overrides.css | 12 ++++++++++++ source/adminguide/accounts.rst | 1 + 2 files changed, 13 insertions(+) diff --git a/source/_static/theme_overrides.css b/source/_static/theme_overrides.css index 6e508351c9..bbbe786f48 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 48c5abae3f..85bdda8cac 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -486,6 +486,7 @@ OpenLDAP) .. list-table:: LDAP Settings :header-rows: 1 + :widths: 20 25 55 * - Setting - OpenLDAP / Active Directory