LDAP, as the name suggests is a light weight protocol for accessing directory services. You can use any external LDAP server such as Microsoft Active Directory or ApacheDS or openLDAP to authenticate CloudPlatform users. Once configured, to authenticate users, CloudPlatform will query the external LDAP server using the given username/password and the pre configured settings. LDAP users can co-exist with the native CloudPlatform users.
Enabling LDAP integration
First we need to inform CloudPlatform about the LDAP server and configurations it can use. Its a two step process.
LDAP Global Settings
Go to global setting and search for ldap. Here is a screenshot of the settings I used in my lab for Microsoft AD.
The following global configurations should also be configured:
- ldap.basedn: Sets the basedn for LDAP. Ex: OU=APAC,DC=company,DC=com
- ldap.bind.principal, ldap.bind.password: DN and password for a user who can list all the users in the above basedn. Ex: CN=Administrator, OU=APAC, DC=company, DC=com
- ldap.user.object: object type of users within LDAP. Defaults value is user for AD and interorgperson for openldap.
- ldap.email.attribute: email attribute within ldap for a user. Default value for AD and openldap is mail.
- ldap.firstname.attribute: firstname attribute within ldap for a user. Default value for AD and openldap is givenname.
- ldap.lastname.attribute: lastname attribute within ldap for a user. Default value for AD and openldap is sn.
- ldap.username.attribute: username attribute for a user within LDAP. Default value is SAMAccountName for AD and uid for openldap.
- ldap.nested.groups.enable : if true, nested groups will also be queried (this is specific to microsoft AD)
- ldap.provider: ldap provider. ex:openldap, microsoftad
- ldap.read.timeout: LDAP connection Timeout in milli sec . Default value is 1000
- ldap.request.page.size: page size sent to ldap server on each request. Default value is 1000
Restricting LDAP users to a group:
- ldap.search.group.principle: this is optional and if set only users from this group are listed.
Before enabling SSL for LDAP, you need to get the certificate which the LDAP server is using and add it to a trusted keystore. You will need to know the path to the keystore and the password.
- ldap.truststore : truststore path
- ldap.truststore.password : truststore password
- ldap.group.object: object type of groups within LDAP. Default value is group for AD and groupOfUniqueNames for openldap.
- ldap.group.user.uniquemember: attribute for uniquemembers within a group. Default value is member for AD and uniquemember for openldap.
LDAP server configuration
call the CloudStack API command addLdapConfiguration and provide Hostname or IP address and listening port of the LDAP server. You could configure multiple servers as well. These are expected to be replicas. If one fails, the next one is used.
You could do the same from UI. select the LDAP configuration drop down in global settings and click “Configure LDAP” button.
Importing users to CloudPlatform
Once LDAP is successfully configured, on the Account page, you will see a new “Add Ldap Account” button like below
Once you click on it, you will be presented with the dialog using which you can either selectively import users to a domain in CloudPlatform or bulk import all the users in LDAP group to a domain in CloudPlatform (by entering the LDAP group name in the LDAP Group textbox below). The two api calls that are used here are ldapCreateAccount(single account creation) and importLdapUsers(bulk import)
On successfully importing users, the users the can be used to login to CloudPlatform with their LDAP username and password. Any password/account change on LDAP should be reflected here and account shouldn’t be allowed access as CloudPlatform as it asks LDAP for authentication every time and doesn’t store anything on the CloudPlatform.
Trust LDAP or link CloudPlatform domain to LDAP
The above process required a manual step by the administrator to import the users to CloudPlatform. Only then, users would be able to login to CloudPlatform. With Hollywood release in Citrix CloudPlatform and in Apache CloudStack 4.6, its now possible to link CloudPlatform domains to a Group or OU in LDAP. A new api linkDomainToLdap is used to achieve the same. It can also be called from UI from Domain tab as shown in the screenshot below(Green button higlighted in red).
On clicking the button, you will be presented with a dialog like below.
It gives you options to enter fully qualified name of LDAP group/OU, the account type to use for the imported users and an option Domain Admin username for the domain. On successfully linking the domain, all the LDAP users in the configured group/OU can automatically sign in to CloudPlatform. Any deleted/disabled user in LDAP wont be able to signin and any newly added users can automatically signin without the step of manually importing them.