diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index e23d9fe6e1..b7b434e033 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -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``. @@ -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 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 ----------------------------------------------------------