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.

The vCloud API login mechanism supports Security Assertion Markup Language (SAML) authentication using two types security assertions:

Bearer assertions, which can make no guarantees about message integrity and claimed client identity.

Holder-of-key assertions, which guarantee subject identity by including a signature generated with the subject's private key.

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 Example: 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:

SAML Authorization Header Attributes and Values

Attribute Name

Attribute Value

token

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

signature

Base64 encoded signature of the token XML (the uncompressed identity assertion from your SAML identity provider) generated using client's private key. Required when using holder-of-key subject confirmation.

signature_alg

The algorithm used to generate the signature, expressed as one of the values listed in http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#Signature Required if signature is present.

org

The name of your vCloud Director organization. Defaults to org="system" if not specified.

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. This example shows two varieties of the request.

Request (bearer token):

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

When using a SAML assertion that provides holder-of-key (HOK) subject confirmation, the request header must include signature and signature_alg attributes, as shown in this example, which assumes a signature created with a SHA encoding and RSA encryption algorithms:

Request (holder-of-key token):

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

The response is the same in both cases.

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.6
...
<Session
   xmlns="http://www.vmware.com/vcloud/v1.5"
   userUrn="urn:vcloud:user:fe50b0b5-..." 
   user="bob"
   org="Finance" 
   ... >
  <Link
      rel="down"
      type="application/vnd.vmware.vcloud.org+xml"
      name="System"
      href="https://vcloud.example.com/api/org/5" />
  <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>

Because this user has limited rights, the response includes only a few link types:

org

A link to the user's organization. See Retrieve a List of Organizations Accessible to You.

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.

An administrator would see a more extensive set of links in the returned Session object. See Example: Create a Login Session Using the Integrated Identity Provider.