Defer to Identity Provider Role in vCloud Director

Besides traditional roles (Org Administrator, vApp Author, …) there is already for some time (as of vCloud Director 8.0) the possibility to assign to vCloud Director organization users a role called ‘Defer to Identity Provider’.

I am going to show how this role can be used to manage assignments of organization roles centrally from within the Identity Provider (IdP) and not from vCloud Director at the Organization level. Central management might be beneficial in cases where there are many Organizations (and vCloud Director instances) associated with single IdP and one user might have access to multiple Organizations. With the traditional approach the user (or his group) would have to be imported into each Organization where he/she should have access and assigned a role.

By deferring to identity provider we rely on the IdP to provide the user’s role just in time when the user is logging in. The feature works both with SAML and OAuth identity providers. In my example I am going to be using the SAML IdP provided by Active Director Federation Services federated with vCloud Director as described in my older blog post.

The set up:

  • Active Directory is used to manage all the users (with exception of local user for onboarding or troubleshooting purposes). The AD can be owned by the Service Provider or the tenant, it depends on the use case.
  • AD FS has been deployed and integrated with vCloud Director Organizations. Note that each Organization must be federated with AD FS specifically. And the federation must be refreshed every year by regeneration of new certificate. In SP use case some level of automation is essential. For details refer to the blog article linked above.
  • AD users who should have access to vCloud Director organization will be part of AD group <Tenant_X>.
  • Role association will be achieved by assigning the AD users to specific AD groups: Organization Administrator, vApp Author, …
  • For each role we will need to add new Transform Claim Rule in AD FS.
    1. On the existing relaying party trust click Edit Claim Rules
    2. Click Add Rule
    3. Select Send Group Membership as a Claim template
    4. Name the rule (e.g. vApp Author)
    5. Browse to the User’s group that represents the role membership (vApp Author group)
    6. In Outgoing claim type select Role.
    7. In Outgoing claim value type the vCloud Director role name (vApp Author).
  • In vCloud Director Organization we need to do following:
    1. As already mentioned each Org needs to be federated with AD FS
    2. In Members > Groups import the <Tenant X> group from Source: SAML with Role: Defer to Identity Provider.
    3. With vCloud API specify RoleAttributeName in OrgFederationSettings. The name for AD FS should be:

Now the users can start logging in with their AD accounts and they will be automatically imported as users with Defer to IdP role. If needed, you can still directly import SAML users and specifically give them role which will take precedence over the IdP role.


vCloud Director 8.20: Granular Role Based Access Control

vCloud Director 8.20 introduces the possibility to create granular roles at tenant and system level. This is important for service providers who want to differentiate which tenants have access to specific features (for example advanced networking services). This also gives opportunity to tenants to create their own roles that correspond to their team structure (e.g. network administrator). And lastly, system administrator can create additional roles in system context with access to subset of features.

A role is a set of rights which can be assigned to a user or a group. There are many new rights in vCloud Director 8.20. A few examples:

Access to Distributed Firewall:

  • Enable / Disable Distributed Firewall

Gateway Advanced Services

  • Configure IPSEC VPN
  • Configure Load Balancer
  • Configure BGP Routing
  • Configure OSPF Routing
  • Configure SSL VPN
  • Configure Firewall
  • Configure DHCP
  • Configure NAT
  • Configure L2 VPN
  • Configure Static Routing

Or system level rights like:


  • Upgrade Host
  • Repair Host
  • Migrate Host VMs
  • Open a Host in vSphere
  • Enable / Disable a Host
  • Prepare / Unprepare a Host
  • View Host

Prior vCloud Director 8.20

  • Only global roles could be created by system administrator next to handful of predefined roles (vApp Author, Organization Administrator, …).
  • Every organization would have access to the global and predefined roles.
  • Organization administrator could assign the roles to organization users.
  • Service provider could not differentiate access to features among different tenants.
  • There was only one system administrator role with access to everything.

vCloud Director 8.20

  • Roles are no longer global, but instead are organization specific.
  • Former global and predefined roles become role templates.
  • Service provider can create new role templates.
  • Role templates are used to instantiate organization specific roles.
  • Service provider can selectively grant rights to specific organizations.
  • Organization administrator can create own organization specific roles from subset of granted rights.
  • New roles can be created in the system context from subset of system administrator rights.

The transition from pre-vCloud Director 8.20 role management happens during upgrade to 8.20. Existing roles are transferred to role templates and each organization gets its own roles instantiation based on the role templates. The UI has changed and now includes Organization column and filter. A new System organization is added with default System Administrator role.

vCloud Director 8.10 UI
vCloud Director 8.20 UI

Tenant Rights and Role Management

When a new organization is created it will have access to all rights that are used in role templates. System administrator can grant additional rights to the organization with vCloud API only:

GET /api/admin … get references to all rights in VCD instance

GET /api/admin/org/<org-id>/rights … get references to all rights in the organization

PUT /api/admin/org/<org-id>/rights edit rights in the organization

System administrator or Organization Administrator can create new roles in its organization with vCloud API only:

POST /admin/org/<org-id>/roles

Note: While system administrator can edit tenant roles in the UI, editing of a role based on role template would change the role template and thus change it for all organizations (more below).

How to Create Global Role

The UI no longer allows creation of global roles, only organization specific roles can be created that way.

However, there is a way to create global role (actually role template) with the legacy API (e.g. version 9.0, 20.0 but not 27.0). Here is an example:

POST /api/admin/roles
Accept: application/*;version=9.0
Content-Type: application/vnd.vmware.admin.role+xml


<?xml version="1.0" encoding="UTF-8"?>
<Role xmlns="" name="New Global Role">
	<Description>My new global role</Description>
		<RightReference href="" name="General: Administrator View" type="application/vnd.vmware.admin.right+xml"/>
		<RightReference href="" name="Group / User: View" type="application/vnd.vmware.admin.right+xml"/>
		<RightReference href="" name="General: Administrator Control" type="application/vnd.vmware.admin.right+xml"/>

Note: Using above API call with API version 27.0 would create the role in the system organization.

How to Edit Global Roles?

Again with legacy vCloud API we can list all global (template) and system organization roles:

GET /api/admin
Accept: application/*;version=9.0
	<RoleReference href="" name="User Admin" type="application/vnd.vmware.admin.role+xml"/>

After finding the right role reference we can delete the role template with the following call:

DELETE /api/admin/role/<role-id>
Accept: application/*;version=9.0

Addition and removal of rights from a role template:

  • In UI add/remove the right from the role which is based on role template from any organization.
  • To add a new right, the organization needs to have access to the right. If it does not have, add it first with the API calls mentioned above.
  • Adding or removing rights to a role based on role template will affect all other organizations.
    • Adding right: other organizations will see the new right if their instance of role template has been granted the right. If the organization did not have access to the right, the right will not be added!
    • Removing right: in other organizations the right will be removed from the role based on the role template


The post was written with kind support of John Kilroy.