VMware Cloud Director (VCD) v10.4 introduces Service Accounts, as an alternative to user accounts, which allows standalone access for automation and third-party applications/tools (e.g. plugins) to VMware Cloud Director. This feature is built on top of API Token infrastructure which adopts OAuth standards. Service Accounts have access via API only and no UI access.
As a recap look at the API Tokens feature which was previously introduced for users in VCD v10.3.1. (Blogged at Cloud Director API Tokens and explained at Feature Friday – API Tokens).
Advantages of Service Accounts over user accounts:
Without service accounts, automation tools require the creation of dedicated dummy user accounts either as VCD local users or setting them up in IDPs (LDAP).
- System or tenant administrator(s) have better control principals accessing VCD via automation by ensuring credential ownership is exclusive to that principal. Thus, unless service accounts themselves disclose their credentials, they cannot be impersonated by anyone else auditing in VCD identifies service accounts as principals.
- Service Accounts utilize the previously introduced API token infrastructure to authenticate with VCD, with enhanced security measures that rotate their API token upon each use. There is better control for the administrators to verify, grant and if necessary, revoke access to the Service Accounts.
Service accounts can be created either in system or tenant context, however, only the system administrators by default can create them. In case an Organization administrator/user needs the ability to create Service Accounts for their organization, then the following rights can be granted to allow this:
- View Service Accounts
- Manage Service Accounts
Limitations
Because the use of service accounts is aimed at third-party applications, Service Accounts have some limitations. These limitations are for good and better control over who does what.
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
How to Create Service Account:
Step1 – Initial Setup:
Administrators can create Service Accounts either from the UI (User Interface) or using the APIs
UI Option:
- Navigate to Administration > Provider Access Control (or “Access Control” in tenant portals) > Service Accounts.
- To create a Service Account, the administrator provides the following:
- A UUID as the Software ID (UI provides a convenient option to quickly create one, but it is encouraged that one is entered so that it can be managed by the automation systems)
- Service Account Name
- VCD Role
- Additionally, the following metadata about the account being created: Software Version – version of automation’s choosing included for informational purposes
- Client URI – optional URL that is also informational and can serve as contact information
- On the next screen, define quotas for the Service Account.
API Option:
POST https://host_name/oauth/provider/register
Headers:
Accept: application/json;version=37.0
Content-Type: application/json
Authorization: Bearer
Body:
{
“client_name”: “AVS”,
“software_id”: “874df0da-aa5e-401d-aa78-07fcbd784ec5”,
“software_version”: “1.0”,
“client_uri”: “vcdavs.com”,
“scope”: “urn:vcloud:role:System%20Administrator”
}
Step 2 – Created Stage
At this stage, the Service Account is in the Created Stage (The account is in the initial stage after creation).
VCD has assigned a client-id to the account which must be communicated to the tool that intends to use the service account. Client-id is part of the OAuth specifications, upon which their authentication is based.
Step 3 – Requested Stage
In this step, the external application is given access to the service account.
As noted above, the API token ownership is managed such that the custodianship of that token can be guaranteed to only be with the tool that must use it. To accomplish this, VCD implements the Device Authorization code flow as described in RFC 8268.
As per the standard, access grant flow is initiated by the service account. Since the service account and administrator must work in tandem to accomplish this, let’s break down the steps for both:
Service Account Steps (performed by the external application)
POST /oauth/provider/device_authorization call using the given client_id from step 2 to initiate device authorization
- The response provides several pieces of information here that ensure proper coordination between an administrator and the service account.
- device_code: The external application/device retains this and will use it to poll VCD for the API token
- user_code: One-time code to be communicated back to the administrator for approval
- The response also includes expires_in (a timeout in seconds) which is the window of time during which the access enablement process should be completed.
At this stage, the Service Account is in the Requested Stage and is waiting for the administrator’s approval.
Step 4 – Granted Stage
At this stage, the same call will return the API token (refresh_token) for access to VCD. This should be treated as a secret by the service account. An access_token is also included in the response for immediate use.
Administrator steps:
For the administrator to grant access to the external application, the device code from step 3 must be provided by the application/device to the administrator who uses it to lookup the service account, reviews the details and either Grant or Denies the request.
At this stage, the Service Account is in the Granted Stage (An administrator granted an outstanding request and is awaiting the service account polling and fetching of the API token).
Step 5 – Active Stage
At the end of step 3, the external application started to poll VCD for API token. Once the administrator granted access (Step 4) the application finally receives the API token via the same API call POST /oauth/provider/device_authorization.
VCD transmits both access_token (to be used immediately for the current session) and an API token to be used for the next session (via the standard POST/oauth/provider/token?grant_type=refresh_token&refresh_token=<API_token>).
Unlike the regular user API tokens, API tokens granted to service accounts rotate on every use. Each time an access token is retrieved via the refresh token call, a new refresh token is provided in the reply for the next session. The client is obligated to discard the old API Token and store the new token for the next use. The unused service account API tokens never expire unless you revoke the service account. This process follows RFC 6749 section 6.
The Service Account moves into the Active Stage.
The below demonstration uses the API token to fetch the organization information.
Additional Notes
- Any object created using the Service Accounts API Token will show the initiator as the Service Account and the Owner as the Service Account, the same as any other user who creates objects.
- Service accounts are principals, comparable to user accounts. Thus, they can (if granted sufficient privileges), create and own assets like vApps, VMS, catalogs, templates, media, etc.
- Service accounts can enable automation to maintain value add assets as themselves.
- Tasks initiated by service accounts are properly attributed and events will identify them as actors.
- Like any principals, assets may be shared with or Service Account.
- The administrator can manage Service Accounts to change the account role, software ID, software version, client URI, or quota restrictions.
- The administrator can revoke previously granted access (only for Service Account must be in Granted or Active stage). Upon revocation, the Service Account Stage changes to Created and the access grant process described in Step 4 must be redone.
- The administrator can delete the Service Account. Before a Service Account can be deleted make sure that any objects previously created by the Service Account must be manually deleted or transferred to another user.
Thanks to Ankit Shah & Tomas Fojta for their support and collaboration in this effort.
