Bug Reference

overall: CLOUDSTACK-10117 - Getting issue details... STATUS

domain level settings: CLOUDSTACK-10118 - Getting issue details... STATUS

moveUser API: CLOUDSTACK-10121 - Getting issue details... STATUS


The current LDAP plugin implementation ties the full CloudStack infrastructure to a LDAP (OU) and creates an CloudStack account for every UID found. A user might want to have a customer create it's own ldap tree and/or add users to a shared account. Thus a user (i.e. domain admin) would be able to organise access to CloudStack using the OU/UID in their ldap.

In this feature multi tenancy is created and account to LDAP group binding. as a result each domain can have their own LDAP implementation and can define accounts for certain purposes, managing those accounts in their LDAP server.


The purpose of the document to specify the functionality of the domain level binding to an LDAP tree, allowing per customer administration.



The auto-import functionality which currently exists maps an LDAP group or OU to a CloudStack domain.  If a user who does not have a CloudStack account logs in (they must give the correct domain) a new account is created in the linked CloudStack domain with that user in it. If an admin has two users it wants in the same account, the current implementation gives no way to do that by administrating them in LDAP.



The following definitions are used in describing the use case of this feature:

D1) User:

  • A “user” refers to a unique username, e.g. using the UID or any other attribute guaranteed to be unique in the global LDAP directory.
  • This attribute is defined in the “ldap.username.attribute” global setting in CloudStack at the moment, but might be different from domain to domain, and thus must get a domain scope.
  • A “user” is a username or login name as used to log in to CloudStack
  • A user i.e. a username can exist in multiple groups. If this is the case the users are considered different. This needs to be allowed to allow for multiple mappings in different domain but should be disallowed by CloudStack if it occurs in the same domain.

D2) Group:

  • A group is an LDAP record of a group type that can contain membership references.
  • For the scope of this change membership will be of users only. Groups will not be members of groups as one would expect in NIS/YP.

The group name is any attribute of the group that is unique within the scope of the mapping, i.e. both within the CloudStack domain and below the defined basedn.

user workflow

S1             The root-admin defines a domain to map ldap-accounts to.

S2             The root-admin creates CloudStack account(s) to be used as roles or organisational units with the required rights for the class of user to be added to that account.

S3             The domain admin links account(s) to the desired LDAP group(s).

S4             A new user attempts log in. If they exist in any mapped group, they are created as a user in the linked CloudStack account. This can be split into several use cases:

  1. The user exists in one of the mapped groups for the domain they are trying to log in to, which would lead to the trivial adding of a CloudStack user of type LDAP, as exists now for mapped domains. Notable difference is that no account will be created per user as we are processing a mapped account in this case.
  2. The unique user exist in more than one of the mapped groups in the same CloudStack domain. In this case one of several things could happen and a choice is made between the following actions:
    1. Display an error referring the user to their LDAP management team. This Solution has preference and will be implemented.
    2. Add the user to the first group found by an algorithm to be decided, most simply being the order in which the mapping is entered in a list.
      In any case a manual import must be possible if for nothing else for problem solving after the fact
  3. The unique user exist in more than one mapped group, with each group mapped to accounts in different CloudStack domains. As the user logs on using a domain, only the user for the group mapped to that domain will be added to CloudStack.

S5             A user exists and logs on and their username can now be found in multiple groups due to new LDAP entries having been added. In addition to the authentication an additional check is to be carried out, checking that the multiple users returned are not contained in groups mapped to accounts in the same CloudStack domain. If this check returns that the same user exist multiple times in the same CloudStack domain then an error is thrown, indicating this is undesired. The behaviour will be hidden behind a configuration option. The default will be to check and not allow logon in case of containment in more than one group. If the check option is set to false no check on number of group containments will be done. Nothing will happen in this case from a CloudStack point of view, i.e. the oldest group containment will remain active.

S6             An admin removes a user from LDAP. As the user logs on his account will be checked and found not to exist in LDAP anymore. It will be checked if the user exists in any other of the mapped accounts for this domain. As the user was removed none will be found after which the user in CloudStack will be marked as removed. (Please note: if the remove was an error and should have been a move, this will lead to problems. In this case manual changes need to be done to restore the user and preserve his keys)

S7             An admin would move a user from one mapped LDAP group to another , thereby effectively removing them from the old. As in scenario S5, a check will be made to see if it exists in any of the other mapped accounts. In this case the user will be moved as it is found in another group-mapped-to-account.

S8              An admin moved a user into two distinct groups mapped to two different accounts in the same domain. The user will be refused logging in as in scenario S4. No move will be done. An error stating the situation and deferring to the LDAP admin will be returned. The user will not be removed but marked disabled, so a move can still be done after the issue is resolved.

Proposed solution

It will be possible to add an ldap configuration for a specific domain. the domain id field will be optional to maintain backwards compatibility. Specific accounts can be linked to LDAP groups. This will be done by an account level property that has no global default value. (ldap.mapped.group)

domain level settings

The configuration mechanism will be extended to include domain level configuration items for LDAP. The basedn and bind attributes would be domain level attributes. For the use-cases described this is not strictly necessary but for users providing public offerings or large enterprise installations, this will improve the usability of the feature. The extra work involved will be not just adding the needed settings but also the enabling of settings on a domain level, which does not exist at the moment of writing.

A user is imported in a linked account if such account exists in the used CloudStack domain, and a user with the username entered is the found as the userid defined for an LDAP user. That means the users ldap group must be defined as the linked group on the account settings of an account.

move user

For the initial use-case, when an already imported LDAP user is moved from one LDAP Group to another, it will be need to be moved in CloudStack as well. As multiple LDAP groups are linked to the same CloudStack domain, when such as user tries to authenticate the LDAP auth plugin will detect and update the account-id of an already imported user. This will allow for a user to be dynamically updated from LDAP. This functionally will be available to admins directly but not 'users'.

A move API that allows admins to move a user from one account to another will be implemented to support other complex scenarios. The service level call will have to be made so creating the API will be trivial and a useful tool.

A moveUser API will be added in favour of extending updateUser API for security, as users have access to updateUser API.


prior ldap work has been done in these FSs.

This specification is about tying an ldap per domain (multi tenant) and an account per ldap group including auto moving and deleting of accounts as they are moved or deleted in ldap.

Web Services APIs

list changes to existing web services APIs and new APIs introduced with signatures and throughout documentation

UI flow

  • either demonstrate it visually here or link to relevant mockups

IP Clearance

  • what dependencies will you be adding to the project?
  • are you expecting to include any code developed outside the Apache CloudStack project?

Usage Impact

  • Are there any entities being created that require usage reporting for billing purposes? 

  • Does this change any existing entities for which usage is being tracked already?


Appendix A:

Appendix B:

  • Simply changing the account_id of a user in CloudStack will move the user to an alternate account and thereby change their permissions (and resources), but also retaining their API keys.
  • As long as LDAP.nested.groups.enable is true and the OU hierarchy is OK, then moving a user from one CloudStack account to another does not prevent authentication.  The actual nested LDAP OU that the user is in has no effect on authentication

  • No labels