The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs from which that user can begin browsing. Users who authenticate to a SAML identity provider must acquire and process a security assertion from that identity provider, then submit the processed assertion to the vCloud API login URL.

Note

This procedure assumes that you are logging in with credentials managed by a SAML identity provider. Users whose credentials are managed by the vCloud Director integrated identity provider must follow a different login workflow.

Verify that you know the login URL. See Retrieve the Login URL and List of Supported API Versions

Verify that you are logging in as a user whose identity is managed by the SAML identity provider defined by your organization.

1

Acquire the SAML assertion from your identity provider.

The system administrator must use the vSphere SSO Service as the identity provider.

2

Compress the assertion using GZIP.

3

Encode the compressed assertion a MIME Base64 encoding, as specified in RFC 1421.

4

Use the login URL to authenticate to the cloud.

POST a request to this URL. The request must include an Authorization header that specifies SIGN as the authorization method and has the following attributes:

Authorization Header Attributes and Values

Attribute Name

Attribute Value

token

The compressed, encoded identity assertion from your SAML identity provider.

org

The name of your vCloud Director organization.

See Example: Create a Login Session Using a SAML Identity Provider.

5

Examine the response.

The response code indicates whether the request succeeded, or how it failed.

If the authentication header is missing, the server returns HTTP response code 403.

If the credentials supplied in the authentication header are invalid, the server returns HTTP response code 401.

If the request is successful, the server returns HTTP response code 200 (OK) and headers that include an authorization header of the form:

x-vcloud-authorization: token

This header must be included in each subsequent vCloud API request.

The Session element returned from a successful login contains one or more URLs from which you can begin browsing.

The list of URLs in the Session object is based on the role and privileges of the authenticated user. 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.

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

This example shows a login request and response for a user of a SAML identity provider logging in to the Finance organization of a cloud whose login URL is https://vcloud.example.com/api/sessions. The user name is included in the encoded credentials.

Request:

POST https://vcloud.example.com/api/sessions 
Authorization: SIGN token="compressed-encoded-credentials",org="Finance"
Accept: application/*+xml;version=5.1

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/vnd.vmware.vcloud.session+xml
...
<Session
   xmlns="http://www.vmware.com/vcloud/v1.5"
   user="bob"
   org="Finance" 
   ... >
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.orgList+xml"
      href="https://vcloud.example.com/api/org"/>
   <Link
      rel="down"
      type="application/vnd.vmware.admin.vcloud+xml"
      href="https://vcloud.example.com/api/admin"/>
   <Link
      rel="down"
      type="application/vnd.vmware.admin.vmwExtension+xml"
      href="https://vcloud.example.com/api/admin/extension"/>
  <Link
      rel="down"
      type="application/vnd.vmware.vcloud.query.queryList+xml"
      href="https://vcloud.example.com/api/query" />
   <Link
      rel="entityResolver"
      type="application/vnd.vmware.vcloud.entity+xml"
      href="https://vcloud.example.com/api/entity/" />
</Session>

This response includes the following link types:

orgList

A link to the list of organizations that you can access. See Retrieve a List of Organizations Accessible to You.

vcloud

A link to administrative objects and operations. See Creating and Managing Organizations

vmwExtension

A link to the vCloud API extensions, accessible to a system administrator. See Managing and Monitoring a Cloud.

queryList

A link to the set of typed queries you can run. See Using the Query Service.

entity

A link to the entity resolver. See Retrieve an Object as an Entity.