Users defined in an organization that specifies 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 VMware Cloud Director API Session.

The VMware Cloud Director API login mechanism supports SAML authentication using two types of security assertions:
  • Bearer assertions, which 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.

Prerequisites

Procedure

  1. Acquire the SAML assertion from your organization's identity provider.
  2. Compress the assertion using GZIP.
  3. Encode the compressed assertion using a MIME Base64 encoding, as specified in RFC 1421.
  4. Use the login URL to authenticate to the VMware Cloud Director API.
    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:
    Table 1. 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 the 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 VMware Cloud Director organization. Defaults to org="system" if not specified.
    See 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 request is successful, the server returns HTTP response code 200 (OK) and headers that include: 
      X-VMWARE-VCLOUD-ACCESS-TOKEN: token
X-VMWARE-VCLOUD-TOKEN-TYPE: type
      Use the values of these headers to construct an Authorization header to use in subsequent VMware Cloud Director API requests. For example, if the value of the X-VMWARE-VCLOUD-TOKEN-TYPE is Bearer, then the constructed header would have this form: 
      Authorization Bearer token
    • If the Authorization header is missing from the request, the server returns HTTP response code 403.
    • If the credentials supplied in the Authorization header are invalid, the server returns HTTP response code 401.

Results

A valid request returns a Session element. See Create a Login Session Using a SAML Identity Provider

Example: Create a Login Session Using a SAML Identity Provider

This example shows a SAML login request and response for a user logging in to the Finance organization of a cloud whose API login URL is https://vcloud.example.com/cloudapi/1.0.0/sessions. This example shows two varieties of the request.

Request (bearer token): 
POST https://vcloud.example.com/cloudapi/1.0.0/sessions 
Authorization: Sign token="compressed-encoded-credentials",
org="Finance"
Accept: application/*;version=9.0

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/cloudapi/1.0.0/sessions 
Authorization: Sign token="compressed-encoded-credentials",
org="Finance",
signature="encoded-signature",
signature_alg="SHA256withRSA"
Accept: application/*;version=9.0

The response is the same in both cases.

Response: 
200 OK
...
<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/" />
   <Link
      rel="down:extensibility"
      type="application/vnd.vmware.vcloud.apiextensibility+xml"
      href="https://vcloud.example.com/api/extensibility" />
</Session>
The response includes several Link types, including:
org
A link to your organization. See Retrieve a List of Organizations Accessible to You.
queryList
A link to the set of typed queries the user can run. See Using the Query Service.
entity
A link to the entity resolver. See Retrieve an Object as an Entity.
extensibility
A link to the extensibility framework entry point. See VMware Cloud Director Extension Services.