Skip to content

Document LDAPS configuration for LDAP integration #612

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rajujith wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Document LDAPS configuration for LDAP integration #612

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
efa17a1
Document LDAPS configuration for LDAP integration
rajujith Dec 23, 2025
5985fe2
Refactor LDAP settings table format
rajujith Dec 31, 2025
359f743
Update LDAP settings format
rajujith Dec 31, 2025
5973661
Revise LDAP settings and restart instructions
rajujith Jan 7, 2026
94b5dd0
Add widths to LDAP Settings list-table
rajujith Jan 9, 2026
e0dbfce
Refactor LDAP settings table in accounts.rst
rajujith Jan 9, 2026
664ca83
Revise LDAP configuration items in accounts.rst
rajujith Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
207 changes: 160 additions & 47 deletions source/adminguide/accounts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -484,53 +484,62 @@ In addition to those shown in the example script above, the following
configuration items can be configured on a Global or on a per Domain level (the default values are for
OpenLDAP)

.. list-table:: LDAP Settings
:header-rows: 1
.. cssclass:: table-striped table-bordered table-hover

+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| Setting | OpenLDAP / Active Directory | Description |
+======================================+===============================================+========================================================================+
| ``ldap.basedn`` | ``OU=APAC,`` | Sets the base DN for LDAP searches. |
| | ``DC=company,DC=com`` | |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``ldap.search.group.principle`` | ``CN=ACSGroup,`` | *(Optional)* If set, only users belonging to this group are listed. |
| | ``DC=company,DC=com`` | |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``ldap.bind.principal`` | ``CN=ACSServiceAccount,OU=APAC,`` | Service account used to list users under the configured base DN. |
| | ``DC=company,DC=com`` | 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`` | OpenLDAP: ``inetOrgPerson`` | LDAP object class representing user accounts. |
| | Active Directory: ``user`` | |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``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`` | OpenLDAP: ``groupOfUniqueNames`` | LDAP object class representing groups. |
| | Active Directory: ``group`` | |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``ldap.group.user.uniquemember`` | ``uniqueMember`` | Attribute defining user membership within a group. |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``ldap.username.attribute`` | OpenLDAP: ``uid`` | Sets the username attribute used within LDAP. |
| | Active Directory: ``sAMAccountName`` | |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``ldap.nested.groups.enable`` | ``true`` | If true, nested groups will also be queried. |
+--------------------------------------+-----------------------------------------------+------------------------------------------------------------------------+
| ``ldap.provider`` | OpenLDAP: ``openldap`` | LDAP provider (e.g. ``openldap``, ``microsoftad``). |
| | Active Directory: ``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.

* - Setting
- OpenLDAP
- Active Directory
- Description
* - ``ldap.basedn``
- `Ex: OU=APAC, DC=company, DC=com`
- `Ex: DC=company, DC=com`
- Sets the basedn for LDAP.
* - ``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.
* - ``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.
* - ``ldap.bind.password``
- `******************`
- `******************`
- Password for a DN User. Is entered in plain text but gets stored encrypted.
* - ``ldap.user.object``
- `interorgperson`
- `user`
- Object type of Users within LDAP.
* - ``ldap.email.attribute``
- `mail`
- `mail`
- Email attribute within ldap for a User.
* - ``ldap.firstname.attribute``
- `givenname`
- `givenname`
- firstname attribute within ldap for a User.
* - ``ldap.lastname.attribute``
- `sn`
- `sn`
- lastname attribute within ldap for a User.
* - ``ldap.group.object``
- `groupOfUniqueNames`
- `groupOfUniqueNames`
- Object type of groups within LDAP.
* - ``ldap.group.user.uniquemember``
- `uniquemember`
- `uniquemember`
- Attribute for uniquemembers within a group.

.. note:: ``ldap.search.group.principle`` is required when using ``linkaccounttoldap``.

Expand Down Expand Up @@ -564,7 +573,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
----------------------------------------------------------
Expand Down