Apply Access Controls to a VDC

Upon creation, an organization VDC grants full access to all members of the containing organization. An administrator can use the vCloud API access control mechanism to restrict access to specific users.

Organization VDCs implement a subset of the access control features described in Controlling Access to vApps and Catalogs. To restrict access to a VDC, you first apply access controls that deny use of the VDC to all users. After you do that, you can make exceptions to grant access to up to 128 individual users. You apply VDC access controls using a controlAccess request and ControlAccessParams request body. Values of certain elements in the request body have special meanings when applied to a VDC.

IsSharedToEveryone	The value of this element specifies whether the VDC imposes any access controls. If it is set to `false`, access is denied to all users except the ones references in the AccessSettings element. If it is set to `true`, no access controls apply even if you have defined them in AccessSettings.
AccessLevel	A value of ReadOnly grants the subject all rights to use the VDC. In this release, ReadOnly is the only legal VDC AccessLevel for a user.

Prerequisites

This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights.

Procedure

1	Retrieve the XML representation of the VDC. Use a request like this one: GET https://vcloud.example.com/api/vdc/130
2	Examine the AdminVdc element to find the controlAccess links that it contains.
3	Create a ControlAccessParams element request body that specifies the details of the update. See Example: Apply Access Controls to a VDC.
4	PUT the ControlAccessParams element to the action/controlAccess link that you retrieved in Step 2.

Example: Apply Access Controls to a VDC

This request updates the access controls of a VDC to grant access to two external users defined in an OAuth identity provider.. The request body, a ControlAccessParams element, specifies a value of false for the IsSharedToEveryone element, which denies access to all users. It also includes an AccessSetting element for each user to whom access is granted. Each of these users is identified by an ExternalSubject element. An ExternalSubject identifies a user account defined in a supported OAuth or SAML identity provider. See About Federation and Single Sign-On. In this element, the SubjectId is the user name with which the user logs in to the identity provider whose type is specified in IdpType. The user must be a member of the organization that owns the VDC.

Request:

PUT https://vcloud.example.com/api/vdc/130/action/controlAccess
Content-Type: application/vnd.vmware.vcloud.controlAccess+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1.5">
   <IsSharedToEveryone>false</IsSharedToEveryone>
   <AccessSettings>
      <AccessSetting>
         <ExternalSubject>
            <SubjectId>user1@example.com</SubjectId>
            <IsUser>true</IsUser>
            <IdpType>OAUTH</IdpType>
         </ExternalSubject>
         <AccessLevel>ReadOnly</AccessLevel>
      </AccessSetting>
      <AccessSetting>
         <ExternalSubject>
            <SubjectId>user2@example.com</SubjectId>
            <IsUser>true</IsUser>
            <IdpType>OAUTH</IdpType>
         </ExternalSubject>
         <AccessLevel>ReadOnly</AccessLevel>
      </AccessSetting>
   </AccessSettings>
</ControlAccessParams>

A user defined in the integrated identity provider is not considered external. To specify users who are defined by the integrated identity provider, use Subject, not ExternalSubject, as shown in this fragment.

<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1.5">
   <IsSharedToEveryone>false</IsSharedToEveryone>
   <AccessSettings>
      <AccessSetting>
        <Subject
            type="application/vnd.vmware.admin.user+xml"
            href="https://vcloud.example.com/api/admin/user/45"/>
         <AccessLevel>ReadOnly</AccessLevel>
      </AccessSetting>
    </AccessSettings>
</ControlAccessParams>

The response, a subset of which appears here, echoes the request.

Response:

200 OK
Content-Type: application/vnd.vmware.vcloud.controlAccess+xml
...
<ControlAccessParams
   xmlns="http://www.vmware.com/vcloud/v1.5">
   <IsSharedToEveryone>false</IsSharedToEveryone>
   <AccessSettings>
      ...
   </AccessSettings>
</ControlAccessParams>