Page History

...

• Annotations use in the API
• CloudStack API Coding Guidelines
• CloudStack general Coding conventions
• CloudStack Identity and Access Management (IAM) Plugin
  
  

How to set API permissions

What happens to commands.properties and @APICommand(authorized=) annotation after adding the IAM feature? No changes, they work as they used to.

• Use the commands.properties and 'authorized' mechanism to specify who can invoke the API.
• IAM service will read these permissions from both inputs and load it to the DB, So any change to commands.properties file should take effect on a restart as it used to be.
• However remember both of them allow setting permissions for CloudStack's default policies only. (User/Resource Domain Admin/Domain Admins/Root Admin Policy)
• Custom Policies: While IAM feature will support creating custom policies, the permissions for these custom policies need to be set separately using the IAM APIs

IAM for the API and Service layer (entity permissions)

Following guidelines should be followed while adding a new API to CloudStack inorder to ensure correct access control is weaved into the logic for all the entities involved.

...

With IAM, one should use the correct AccessType in the @ACL annotation or at service layer to specify what kind of access is needed for the entity while invoking this API.

AccessType

• Until 4.4, CloudStack did not distinguish between a read-only access Vs read-and-use access Vs operate access. 
• CloudStack access control layer always checked if the caller is owner of the entity and granted all types of access based on that. 
• With IAM feature following are the types of entity access one can specify:
  1. ListEntry  (read only access)
  2. UseEntry  (read and use access)
  3. OperateEntry (operate/execute access)

Example: A domainAdmin registers a template T and allows a regular user of the domain to launch a VM using that template.

Entity: TemplateT
Principal1:  domainAdmin, Access allowed: OperateEntry   (operate access since he can invoke delete/updatepermissions operations on the template)
Principal2: normal domain user, Access allowed: UseEntry  (the user can only list the template and use it for launching VM)

IAM At API layer: use @ACL

• For the primary ID API parameter which identifies the entity being operated on, put annotation  @ACL(accessType = AccessType.OperateEntry)
• For all other entities putting @ACL or @ACL(accessType = AccessType.UseEntry) should suffice. This will make sure the caller can 'list and use' the entity for the desired operation.
• By default the annotation uses AccessType.UseEntry

...

• create APIs : one needs @ACL(accessType = AccessType.UseEntry) on all the entities required to be used for creating the desired new entity
• update/delete APIs: These modify or operate on an entity and change its state. @ACL(accessType = AccessType.OperateEntry) should be used in these APIs on the parameter that identifies the main entity being modified.

Example:

• DeployVMCmd 
  
  • This is a create API
  • Add @ACL(accessType = AccessType.UseEntry access for all entities like template, network
• Start/Stop/Reboot/Destroy/AttachXXXTOVM :
  
  • These are the update/delete APIs
  •  Add @ACL(accessType = AccessType.OperateEntry) access for VM ID parameter that identifies the VM entity being operated on

IAM At Service Layer:

CS Service layer logic uses  "accountManager.checkAccess" to invoke the SecurityCheckers to do access control. Instead, one should try to use @ACL annotation on the API parameters that have to be checked for access.

...