Create a Session Using SAML Authentication

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 vCloud API Session.

The vCloud 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

■	Verify that you know the API 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.

Procedure

Acquire the SAML assertion from your organization's identity provider.

Compress the assertion using GZIP.

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

Use the login URL to authenticate to the vCloud 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:

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 vCloud Director organization. Defaults to `org="system"` if not specified.

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

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 a header of the form:

x-vcloud-authorization: token

This header, including the token, must be included in each subsequent vCloud API request.

■

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.

A valid request returns a Session element. See Example: 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/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/*;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/api/sessions 
Authorization: Sign token="compressed-encoded-credentials",
org="Finance",
signature="encoded-signature"
signature_alg="SHA1withRSA"
Accept: application/*;version=9.0

The response is the same in both cases.

Response:

200 OK
x-vcloud-authorization: cn9uYmd...
...
<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 the re-usable x-vcloud-authorization header and these Link types:

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 vCloud Director Extension Services.

Related tasks

Logging In