You can automate the access of third-party applications to VMware Cloud Director by using service accounts.

Sharing

Starting with VMware Cloud Director 10.4.1, if you want to limit the service account information that users can see, you can grant to certain roles only the Limited Service Accounts View right. When a user with the Limited Service Accounts View right makes a GET request on the service account, in the response, the softwareId, softwareVersion, uri, and status of the service account appear as null.

Implementation

To provide automated access to VMware Cloud Director, service accounts use API tokens . Service accounts are intended for API-based access only. Once you grant access to a service account, the authenticated client application receives their API Token, which is an OAuth refresh token, and an access token, representing its first VMware Cloud Director session, for immediate use. Applications need the API tokens for authenticating with VMware Cloud Director. Access tokens are VMware Cloud Director session tokens (JWT tokens), that applications use to make API requests using the service account. The service accounts for applications use API tokens and thus, have the same restrictions as user API tokens in VMware Cloud Director.

Service accounts are granted access using the "Request Service Account Authorization". This guarantees that only the application that must use the token has sole access to the token and can use it. No other actor can access the token. You, as an administrator, manage the access to the service account. However, even administrators do not have access to the actual token that grants access. VMware Cloud Director gives the token only to the service account. To accomplish this, VMware Cloud Director relies on a well-known standard. To ensure that you and the application to which you are granting the token are in sync through the grant and token transmission, you can only initiate the API token grant process by knowing the user code for the application.

Unlike user API tokens, API tokens granted to service accounts rotate on every use, as per RFC 6749 section 6. Unused service account API tokens never expire unless you revoke them.

Service accounts can have only one role. In OAuth-compliant APIs, the role is communicated through the scope field as a URL-encoded Uniform Resource Name (URN) with the name of the role. The URN format is urn:vcloud:role:[roleName]. See RFC 8141 that describes URN encoding.

Note: The device endpoint is unauthenticated. Consider configuring special throttling rules at your load balancer.
Table 1. Service Account Statuses
Status Description
Created The account is in the initial state after creation.
Requested There are one or more outstanding requests for access that a requester initiated using a device authorization request.
Granted An administrator granted an outstanding request and is awaiting the service account polling and fetching of the API token.
Active The service account fetched the API token and can access VMware Cloud Director using the token.

Limitations

Because the use of service accounts is aimed at third-party applications, service accounts have some limitations.

When using service accounts, applications cannot perform certain tasks.
  • Perform user management tasks
  • Create API tokens
  • Manage other service accounts
When accessing VMware Cloud Director by using a service account, applications have only view rights for the following resources.
  • User
  • Group
  • Roles
  • Global roles
  • Rights bundles
Applications accessing VMware Cloud Director by using a service account do not have the following rights.
  • Token: Manage
  • Token: Manage All

Multisite

Starting with VMware Cloud Director 10.4.1, service accounts can manage and monitor multiple, geographically distributed VMware Cloud Director installations or server groups and their organizations as single entities by using the multisite feature. For more information, see Configuring and Managing Multisite Deployments. If a service account is making a request to a different organization from the one that it is authenticated to, verify that the service account exists on the associated organization and that it has the same name and software ID. You must also include a X-VMWARE-VCLOUD-AUTH-CONTEXT header that specifies the name of the organization that must fulfill your request. See the information for configuring and managing multisite deployments in the VMware Cloud Director API Programming Guide.

Create a Service Account

You can create an account for automated access to VMware Cloud Director by using the Service Provider Admin Portal.

Procedure

  1. From the top navigation bar, select Administration.
  2. In the left panel, under Provider Access Control, select Service Accounts.
  3. Click New.
  4. Enter a name for the service account.
  5. From the Assign Role drop-down menu, select a role for the service account.
    The list of available roles comprises the local system organization roles or if in a tenant organization, the global roles published to the organization in addition to any local roles in the tenant.
  6. Enter a software ID for the service account or generate and enter one using the Generate Software ID button.

    Service accounts must have software IDs which are unique identifiers, in UUID format, representing the software that is connecting to VMware Cloud Director. This ID would be the same for all versions and instances of a piece of software.

    For larger solutions, to retain control over the identity of your service accounts, do not use the Generate Software ID option, and generate your own software ID.

  7. (Optional) Enter the software version of the system using the service account.
    The software version is an optional vendor-specified informational piece of metadata associated with the service account. To track when a piece of software changes, VMware Cloud Director uses the software version . The software version might be useful for identifying a service account.
  8. (Optional) Enter a client URI.
    The client Uniform Resource Identifier (URI) is a URL to the webpage of the vendor and provides information about the client.
  9. Click Next.
  10. (Optional) Add quotas on the resources you want the service account to manage.
    These quotas limit the service account's ability to consume storage and compute resources.
  11. Review the service account information, and click Finish.

Results

The service account appears on the Service Accounts page with status Created.

Example

You can create a service account also by using the VMware Cloud Director API. The API request uses the same API endpoint as creating a user API token, but the presence of the software_id field indicates the intent to create a service account.

Sample request: 
POST /oauth/provider/register 

Accept:application/json

Content-Type:application/json

Authorization:Bearer eyJhbGciOiJSUzI...7g7rA 

Body: { 

    "client_name": "exampleServiceAccount", 

    "software_id": "bc2528fd-35c4-44e5-a55d-62e5c4bd9c99", 

    "scope": "urn:vcloud:role:System%20Administrator", 

    "client_uri": "https://www.companyname.com", 

    "software_version": "1.0" 

}
Sample response: 
{ 

"client_name": "exampleServiceAccount", 

"client_id": "734e3845-1573-4f07-9b6c-b493c9042187", 

"grant_types": [ 

"urn:ietf:params:oauth:grant-type:device_code" 

], 

"token_endpoint_auth_method": "none", 

"client_uri": "https://www.company_name.com", 

"software_id": "bc2528fd-35c4-44e5-a55d-62e5c4bd9c99", 

"software_version": "1.0", 

"scope": "urn:vcloud:role:System%20Administrator" 

}

What to do next

Copy the client ID that appears in the service account details. To grant access to the service account, you must use the client ID.

Grant Access to a Service Account

After you create a service account and the application requests authorization to receive an access token, you can grant the token by using the VMware Cloud Director Service Provider Admin Portal.

Note: If the timeout period expires during this procedure, the service account status in the Service Provider Admin Portal changes back to Created, and you must start the procedure again.

Prerequisites

  1. Copy the client ID from the service account details in the Service Provider Admin Portal.
  2. Verify that the application requesting the account makes an OAuth 2.0 Device Authorization Grant RFC-compliant request to the https://site.cloud.example.com/oauth/provider/device_authorization API endpoint. For more information on device authorization requests, see RFC 8628 section 3.1.
    Key Value
    client_ID Generated_Client_ID

    Once the application requests access, the service account status in the Service Provider Admin Portal changes to Requested. The application receives the device code, user code, and some additional information.

    Sample request: 
    POST /oauth/provider/device_authorization
Accept:application/json 
Content-Type: application/x-www-form-urlencoded
Body:
client_id=734e3845-1573-4f07-9b6c-b493c9042187
    Sample response: 
    {
"device_code": "tkhZ0uoUMy5xgjJqRJblIq3-g44xy2Ms6TEpv3Z_fKw",
"user_code": "3VL8-SQVJ",
"verification_uri": "https://[VCD]/provider/administration/access-control/service-accounts",
"expires_in": 3600,
"interval": 60
}

    The device must poll at the frequency specified in the above response (in seconds) /oauth/provider/token as per the RFC. The device must use the device code until it receives the tokens from VMware Cloud Director, or the request times out.

    Sample request: 
    POST: /oauth/provider/token
Accept:application/json 
Content-Type: application/x-www-form-urlencoded
Body:
client_id= 734e3845-1573-4f07-9b6c-b493c9042187&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=tkhZ0uoUMy5xgjJqRJblIq3-g44xy2Ms6TEpv3Z_fKw
    Sample response before granting: 
    {
    "error": "authorization_pending",
    "error_description": "Device authorization request pending",
    "error_uri": null,
    "minorErrorCode": "authorization_pending",
    "message": "Device authorization request pending",
    "stackTrace": null
}
    Sample response after granting: 
    {
    "access_token": "eyJhbGciOiJSU…HqJaDud1sVA",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "refresh_token": "SsybukUed8SBP2p1AaFiGJhrntQNWZVX"
}

    If you do not confirm or deny an access request, the user code times out. The timeout period appears in the response of the device authorization request.

    VMware Cloud Director grants a primary API token to the application only if the application and the administrator use the device code and user code corresponding to each other.

  3. Get the user code from the application. You must enter the code in step 4.

Procedure

  1. From the top navigation bar, select Administration.
  2. In the left panel, under Provider Access Control, select Service Accounts.
  3. Click Review Access Requests.
  4. Enter the user code for the application that you obtained in prerequisite 3, click Lookup, and verify the requested access details.
  5. Grant access to the application.
    If you deny access to the application, the service account status in the Service Provider Admin Portal changes back to Created.

Results

The service request status changes to Granted. VMware Cloud Director grants the application linked to the service account its primary API token in the form of an API token. Included in the response, as required by the RFC, is an OAuth access token representing a user session for immediate use by the service account. If the application does not use the OAuth access token immediately, the session times out as per the configured idle session timeout. The service account might also explicitly log out, which is recommended not only for security reasons, but also provides a good test run for the service account to make an API call to VMware Cloud Director. Once the application fetches the API token, the status changes to Active.

What to do next

  • To change the assigned service account role, software ID, software version, client URI, or quota restrictions, select a service account and click Edit a Service Account. The changes take effect at the next token refresh.
  • To revoke service account access so that the granted API token granted becomes invalid, click Revoke. VMware Cloud Director terminates all active sessions. Revoking an API token does not delete the service account, however, the status of the account changes to Created. If the application has already requested access again, the status of the service account changes to Requested. You must once again follow the procedure to grant access to the service account for the account to become Active.