Cloud Director API Token

VMware Cloud Director 10.3.1 introduced API Tokens. This allows a user to generate API tokens for programmatic access to VCD. It works for both, provider, and tenant users. An automation script or 3^rd-party solution can then use the API token to make API requests to Cloud Director on behalf of the user.

These steps are used to create API tokens:

The provider propagates the right to use and manage API token to the tenant
The Cloud Director user (provider as well as tenant user) creates an API token
An API client (e.g. an automation script) uses the API token to make requests
(If needed) The user revokes the API token

Preparation

As for most new features, fine-grained access control through rights bundles is possible. To enable a tenant to use API token, the provider must publish a rights bundle to the tenant. Privileges can be defined for a user to manage the user’s own tokens, and to manage all Organization user’s token (for example for an Organization Administrator).

Cloud Director Rights Bundles

Create the API Token

As provider or tenant user with proper privileges you can use the “User Preferences” menu to create the API token. Each token can be labeled with a name. Be aware that the actual token key is only visible once in the creation wizard and cannot be retrieved afterwards.

Cloud Director User Preferences Cloud Director New Api Token

Cloud Director Generate API Token

Revoke the API Token

API tokens do not expire, but existing API tokens can be revoked. This also invalidates active API client sessions that used the token to authenticate. All users can revoke their own tokens. Administrators (those with ‘manage all user’s API tokens’ right) can revoke other user’s tokens. Tenant administrators can do so within their own Organization, while system administrators can do so for any user.

Cloud Director Revoke API Token

Use the API Token

Semantically the API token usage follows the OAuth 2.0 specification (RFC 6749, section 6).

The API token can then be used by a 3^rd-party solution or custom API client to access the VCD API as the user, without the need to authenticate with username and password credentials.

API Client Example

Request the bearer token for subsequent calls using the API token:

POST https://host_name/oauth/provider/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Body:
grant_type=refresh_token&refresh_token=Generated_API_Token

Security note: It’s recommended to send the API Token as part of the request body (and not as part of the URL, even if that technically works for x-www-form-urlencoded type requests), to avoid it being logged in transit.

Response containing the Bearer token:

HTTP/1.1 200 OK
Content-Type: application/json
Body:
{
“access_token”:”Generated_Access_Token”,
“token_type”:”Bearer”,
“expires_in”:86400,
“refresh_token”:null
}

Subsequent API call now can use the returned Bearer token in the “access_token” field as usual. There is no need for any changes in the client code.

Subsequent Call using the Bearer token:

GET https://host_name/api/org
Accept: application/*+xml;version=36.1
Authorization: Bearer Generated_Access_Token

Notes

The session expiration can be configured in the provider portal under General > Timeouts.

Cloud Director Session Timeout Settings

The VCD Provider for Terraform for example supports API Token authentication as of version 3.5:

provider “vcd” {
user = “none”
password = “none”
auth_type = “api_token”
api_token = Generated API token
sysorg = “System”
…

For security reasons, certain tasks are not possible when authenticated through an API token:

Change the user password
Perform user management tasks
Create more tokens
View or revoke other tokens

When accessing VMware Cloud Director by using an API access token, applications have only view rights for the following resources.

User
Group
Roles
Global roles
Rights bundles

The API Token feature in VMware Cloud Director offers a secure way for automation solutions to access its API, even in environments that enforce Multi-factor Authentication for user logins.