...

Ticket to track the feature implementation: https://issues.apache.org/jira/browse/CLOUDSTACK-5920

Note: IAM feature cannot be put in to current 4.5 codebase due to API gap and limitations found and documented here: https://cwiki.apache.org/confluence/display/CLOUDSTACK/API+changes

Architecture and Design description

...

Other than that, customer should be able to define customized policies by grant or deny permission to customize permissions for the group. So far, for cross-account permission grant, we are currently supporting the following 3 types of granting/denying:

• Grant by Domain and Resource and Entity Type: grant permissions to all resources of the given entity type under the given domain.
• Grant by Account and Entity Type: grant permissions to all resources of the given resource entity type under the given domain.
• Grant by Account and Resource Type: grant permissions to all resources of the given resource type under the given account.
• account.
• Grant by individual resource: grant permission to an individual resource.

Entity Type

Here are list of entity types supported by IAM model:

• VirtualMachine
• Volume
• ResourceTag
• Account
• AffinityGroup
• AutoScalePolicy
• AutoScaleVmProfile
• AutoScaleVmGroup
• Condition
• Vpc
• VpcGateway
• VMSnapshot
• VirtualMachineTemplate
• StaticRoute
• Snapshot
• Site2SiteVpnGateway
• Site2SiteCustomerGateway
• Site2SiteVpnConnection
• SecurityGroup
• RemoteAccessVpn
• ProjectInvitation
• Network
• IPAddress
• InstanceGroup
• GlobalLoadBalancerRule
• FirewallRule
• PortForwardingRule
• EventGrant by individual resource: grant permission to an individual resource.

Permission

A policy consists of set of Permissions. A Permission is a way of defining access control.
Using Permission, customer defines what actions are allowed or denied, on what resources, under which account or domain.

...

/**
* QuerySelector returns granted domain, or account or resources for caller.
*/
public interface QuerySelector extends Adapter {

...

/**
* List granted domains for the caller, given a specific entity type.
*
* @param caller account to check against.
* @param entityType entity type
* @param accessType access type
* @return list of domain Ids granted to the caller account.
*/
List<Long> getAuthorizedDomains(Account caller, String entityType, AccessType accessType);

/**
* List granted accounts for the caller, given a specific entity type.
*
* @param caller account to check against.
* @param entityType entity type
* @param accessType access type
* @return list of account Ids granted to the caller account.
*/
List<Long> getAuthorizedAccounts(Account caller, String entityType, AccessType accessType);


/**
* List granted resources for the caller, given a specific entity type.
*
* @param caller account to check against..
* @param entityType entity type
* @param entityTypeaccessType entityaccess type
* @return list of resource Ids granted to the caller account.
*/
List<Long> getAuthorizedResources(Account caller, String entityType, AccessType accessType);

/**
 * Check if this account is associated with a policy with scope of ALL
 * @param caller account to check
 * @param action action.
 * @param accessType access type
 * @return true if this account is attached with a policy for the given action of ALL scope.
 */
boolean isGrantedAll(Account caller, String action, AccessType accessType);

/**
 * List of IAM group the given account belongs to
 * @param accountId account id.
 * @return IAM group names
 */
List<String> listIAMGroupsByAccount(long accountId); 

...

Currently CloudStack provides different response views for Root admin and non-root user, some response fields are only visible to root admin. Basically we have provided two static response views (Full view and Restricted view), domain admin will also have a User view. With new IAM service introduced, we should ideally also allow customers to be able to specify what view should be applied to each API when they are granting each API action to an IAM policy. To achieve that, we will implement as follows:

1. For those APIs listed in previous Response View (Column Filter) section, when user grants them to a policy, we should allow them to pick one of two static response views (Full view and Restricted view) that are pre-defined. Note that in this release, we are not going to support full-fledged column filter (that is, allowing users to pick arbitrary columns to be see for each API) . We are only supporting static view association at the API leveland only support static view association at the API level. In this release, support for granting with response view is not supported, and we still maintain the current cloudstack behavior where only root admin can see the Full view. This step will be delayed to Phase II.

2. We will separate all current both admin and user allowed API commands to two classes: API for admin and API for user. For example, previous ListVMsCmd will be splitted into two classes: ListVMsCmdByAdmin and ListVMsCmd.

   Code Block

   @APICommand(name = "listVirtualMachines", description = "List the virtual machines owned by the account.", responseObject = UserVmResponse.class, responseView = ResponseView.Restricted, entityType = { IAMEntityType.VirtualMachine }) public class ListVMsCmd extends BaseListTaggedResourcesCmd { ...... } @APICommand(name = "listVirtualMachines", description = "List the virtual machines owned by the account.", responseObject = UserVmResponse.class, responseView = ResponseView.Full) public class ListVMsCmdByAdmin extends ListVMsCmd { ///////////////////////////////////////////////////// //////////////// API parameters ///////////////////// ///////////////////////////////////////////////////// @Parameter(name=ApiConstants.HOST_ID, type=CommandType.UUID, entityType=HostResponse.class, description="the host ID") private Long hostId; @Parameter(name=ApiConstants.POD_ID, type=CommandType.UUID, entityType=PodResponse.class, description="the pod ID") private Long podId; @Parameter(name=ApiConstants.STORAGE_ID, type=CommandType.UUID, entityType=StoragePoolResponse.class, description="the storage ID where vm's volumes belong to") private Long storageId; }

   Note that ListVMsCmdByAdmin and ListVMsCmd are sharing the same API name "listVirtualMachines". From client perspective, this is transparent to them, CloudStack API client will still just invoke previous listVirtualMachine API, and CloudStack API server will internally consult with IAM plugin to determine the group associated with the invoking user and then determine which internal Cmd class to be invoked. There is a new attribute "responseView" introduced for @APICommand annoation, which can be used to instruct CloudStack to generate different response view. By separating the command class into admin cmd class and user cmd class, we can also restrict valid input parameters for different account. For example, in this case, when Admin invokes listVirtualMachine api, he/she can pass hostId, podId and storageId, which parameters are not applicable for end user.

...

iam_group_policy_map

...

...

• Find all groups the user belongs to: groupIDs = 1
• Find all 'Effective' policies the groups are associated to: policies = 1, 6
• If any policy 'Allows' the startVirtualMachine API for this Vm Id, grant permission to make this call: Policy Id 6 1 and Permission Id 3 allow the API to be invoked for this user.
• In this case, since this is a regular user and the user is the owner the VM belongs to the "ACCOUNT" scope of the VMuser, then he is granted access using policy Id 61.

A Domain Admin 'domainAdmin' calls this command for a VM in his domain:

...

• Find all groups the user belongs to: groupIDs = 2
• Find all 'Effective' policies the groups are associated to: policies = 2
• Policy Id 3 2 and Permission Id 1 allow 'startVirtualMachine' access for ALL VMs .

...

For this release, creating a custom policy/group is supported through API only.  For further releases, we can provide either a UI or a config file + policy language mechanism to facilitate the custom policy/group creation.

Presentation at CloudStack Collaboration Conference

ApachIAM.pptx