Domain level LDAP bindinings

Bug Reference

overall: Unable to render Jira issues macro, execution error.

domain level settings: Unable to render Jira issues macro, execution error.

moveUser API: Unable to render Jira issues macro, execution error.

Branch

What branch is this work being done in

Introduction

Tthe 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.

Purpose

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

Background

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.

Definitions

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.

References

• relevant links

Document History

Glossary

Feature Specifications

• put a summary or a brief description of the feature in question 
• list what is deliberately not supported or what the feature will not offer - to clear any prospective ambiguities
• list all open items or unresolved issues the developer is unable to decide about without further discussion
• quality risks (test guidelines)
  • functional
  • non functional: performance, scalability, stability, overload scenarios, etc
  • corner cases and boundary conditions
  • negative usage scenarios
• specify supportability characteristics:
  • what new logging (or at least the important one) is introduced
  • how to debug and troubleshoot
  • what are the audit events 
  • list JMX interfaces
  • graceful failure and recovery scenarios
  • possible fallback or work around route if feature does not work as expected, if those workarounds do exist ofcourse.
  • if feature depends other run-time environment related requirements, provide sanity check list for support people to run
• explain configuration characteristics:
  • configuration parameters or files introduced/changed
  • branding parameters or files introduced/changed
  • highlight parameters for performance tweaking
  • highlight how installation/upgrade scenarios change
• deployment requirements (fresh install vs. upgrade) if any
• system requirements: memory, CPU, desk space, etc
• interoperability and compatibility requirements:
  • OS
  • xenserver, hypervisors
  • storage, networks, other
• list localization and internationalization specifications 
• explain the impact and possible upgrade/migration solution introduced by the feature 
• explain performance & scalability implications when feature is used from small scale to large scale
• explain security specifications
  • list your evaluation of possible security attacks against the feature and the answers in your design* *
• explain marketing specifications
• explain levels or types of users communities of this feature (e.g. admin, user, etc)

Use cases

put the relevant use case/stories to explain how the feature is going to be used/work

Architecture and Design description

• discussion of alternatives amongst design ideas, their resources/time tradeoffs and limitations. Explain why a certain design idea is chosen over others
• highlight architectural patterns being used (queues, async/sync, state machines, etc)
• talk about main algorithms used
• explain what components are being changed and what the dependent components are
• regarding database: talk about tables being added/modified
• performance implications: what are the improvements or risks introduced to capacity, response time, resources usage and other relevant KPIs
• preferably show class diagrams, sequence diagrams and state diagrams
• if possible, publish signatures of all methods classes and interfaces implement, and the explain the object information of different classes

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

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