The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs from which that user can begin browsing objects in an organization. Users must submit their credentials in the form required by the identity provider that their organization specifies.

The vCloud API does not have a login request. To begin using the API, you request the system to create a Session object, supplying your credentials in an Authorization header of the form prescribed by the identity provider that your organization uses. The response includes a JSON Web Token (JWT), as defined in RFC 7519, and a Session element whose Link elements reference the vCloud API objects to which you have access rights.

vCloud Director supports several forms of authentication to the vCloud API.

■

OAuth authentication, as defined in RFC 6749. Users defined in an OAuth identity provider must acquire an OAuth token from that identity provider and include it in the request to create a vCloud API Session.

■

SAML (Security Assertion Markup Language) authentication, as defined in RFC 6595. Users defined in a SAML identity provider must acquire and process a security assertion from that identity provider and include the processed assertion and other attributes in the request to create a vCloud API Session.

■

Basic HTTP authentication, as specified in RFC 2617. LDAP users and local users are defined by the vCloud Director integrated identity provider, and must include credentials in the form required by Basic HTTP authentication in the request to create a vCloud API Session.

All organizations are created with implicit support for the vCloud Director integrated identity provider. Organizations can be configured to add support for a SAML or OAUTH identity provider.

Important

Regardless of the authentication protocol your organization uses, the JWT token returned with a Session object is supported for use in the Authorization header of all requests, and is required for requests that span associations of organizations or sites. See Configuring and Managing Multisite Deployments.

A Session object can be deleted by its owner or an administrator. After your Session expires or is deleted, you are not authenticated.

A Session object expires after a configurable interval of client inactivity. To change the length of this client inactivity timeout, a system administrator can change the value of SessionTimeoutMinutes in the system's GeneralSettings. See Retrieve or Update System Settings.

All requests to create a login session include a similar set of steps.

Procedure
1

Make an API versions request to retrieve the list of supported API versions and the login URL for each version.

The request has this form: 

GET http://vcloud.example.com/api/versions

You do not need to be authenticated to make a versions request.

2

POST a request to the login URL, supplying your credentials in the request's Authorization header.

These requests have the following form: 

POST https://vcloud.example.com/api/sessions 
Authorization: auth-type credentials
Accept: application/*;version=api-version

The value of auth-type depends on the protocol you are using. Each authentication protocol has its own requirements for credentials and other attributes.

Basic

Specifies Basic HTTP authentication. Requires your user name, organization name, and password in a MIME Base64 encoding.

Bearer

Used with OAuth authentication. Requires an OAuth token and your organization name.

Sign

Used with SAML authentication. Requires a compressed, encoded SAML assertion and other attributes.

3

Examine the response to retrieve the authorization token and links to objects that you have rights to access.

A successful request returns a Session element and headers that include: 

X-VMWARE-VCLOUD-ACCESS-TOKEN: token
X-VMWARE-VCLOUD-TOKEN-TYPE: type

Use the values of these headers to construct a JWT Authorization header to use in subsequent vCloud API requests. For example, if the value of the X-VMWARE-VCLOUD-TOKEN-TYPE is Bearer, then the constructed JWT header would have this form: 

Authorization Bearer token
Note

A successful login request also returns a header of the form: 

x-vcloud-authorization: token

Use of this header for authorization is deprecated as of API version 30.0.

Subtopics