7.2.2 OAuth Authentication
OAuth simplifies user access management especially in federated multi vCloud Director environments.
Typical workflow:
1. The system administrator enables vCloud Director organization for OAuth authentication
2. User access to the organization and roles are managed in central identity provider (for example LDAP).
3. A user who wants to access a given organization must first be authenticated by the central identity provider. The identity provider will issue a bearer OAuth2 token which gives access to the specific resource to anyone who has the token.
4. The OAuth token consists of three base64 encoded text string sections delimited by a dot (‘.’). The first part is JWS (JSON Web Signature) header, the second part is claims set, and the third part is the signature.
5. The claims set section must contain authz field which provides information to which organizations the user has access and under which role.
6. The user makes vCloud API call to vCloud Director passing the OAuth token in the Authorization header of the HTTP API request together with the vCloud Director organization name.
Authorization = Bearer <Base64 encoded OAuth Token>;org=<organization name>
7. vCloud Director extracts the token and performs expiration and signature validation and retrieves the role information to set the users security context. A vCloud authorization token (x-vcloud-authorization) is issued, which can be used for subsequent API requests or for browser portal access if stored as a vcloud_session_id cookie.
8. If the user does not exist in the vCloud Director organization, it is automatically imported.
9. The requested API call is performed in the proper user security context.
Note The API call does not need to be login session request (POST /api/sessions). It can be any API request. For example, GET /api/session would return a session object containing the user name and URL link to the user’s organization object.
Table 10. OAuth Token Claims
Claim | Description | Notes |
jti | OAuth token id | A new session is created if no session exists already associated with jti |
sub | User ID of the user being logged in | Universal identifier for the subject of the token |
email | User’s email | |
uname | User name/UPN that the user logs in as | Unique, 1:1 with User ID |
cid | tenant/company/customer id that the user belongs to | Not used |
tvr | OAuth token version | vCloud Director supports only 2.0 |
iat | Token issuance time, in seconds | Token must be presented at or after this time |
exp | Token expiration time in seconds. | Token must be presented before this time |
iss | Token issuer ID | Used to verify that the token is issued by the configured issuer |
authz | Represents the set of roles for each specific service instance | |
instances | Service instances | Organization IDs |
roles | User role | vCloud Director user role |
The authz section must have the following format:
"authz" : {
"com_vmware_vchs_compute" : {
"instances": {
"34691574-7ccd-4fc1-b940-0bd2388bf3a5": {
"roles" : [
"Organization Administrator"
]
},
"48df38a4-aec8-4a34-b25a-b8f372bd8c33": {
"roles": [
"Organization Administrator"
]
}
}
}
}
Where 34691574-7ccd-4fc1-b940-0bd2388bf3a5 and 48df38a4-aec8-4a34-b25a-b8f372bd8c33 represent Organization IDs where the user has Organization Administrator role access.
Note The com_vmware_vchs_compute string is mandatory.
The following are OAuth authentication design considerations:
• While a vCloud Director organization can use multiple identity providers at the same time, an organization user can be associated with only single identity provider. For example, it is not possible for the same user to log in through OAuth and integrated LDAP authentication.
• The service provider can use OAuth authentication for federation of multiple vCloud Director instances with the central identity provider, while the tenant can still use SAML authentication to federate tenant users with their company Active Directory (with Active Directory Federation Services). The SAML users will not exist in the provider’s central identity directory.
• External tools that use vCloud API (such as vRealize Automation) and that rely on basic authentication do not work with OAuth authentication. To enable OAuth, the service provider must implement the following process:
a. Intercept API authentication calls (POST /api/sessions and /api/login).
b. Get the Authorization header. If it is not basic authentication, pass it to the vCloud API endpoint.
c. If it is basic authentication parse and Base64, decode the header to get <username>@<org>:<password> values.
d. Use the credential values to authenticate against provider’s central identity provider.
e. Retrieve the OAuth token and replace the Authorization header of the original request with the Base64 encoded OAuth header (Bearer <OAuth-token>;org=<org>).
f. Forward the request to the vCloud API endpoint.