The VMware Cloud Director 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 VMware Cloud Director 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 VMware Cloud Director API objects to which you have access rights.

VMware Cloud Director supports several forms of authentication to the VMware Cloud Director 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 VMware Cloud Director 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 VMware Cloud Director API Session.
  • Basic HTTP authentication, as specified in RFC 2617. LDAP users and local users are defined by the VMware Cloud Director integrated identity provider, and must include credentials in the form required by Basic HTTP authentication in the request to create a VMware Cloud Director API Session.
All organizations are created with implicit support for the VMware Cloud 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 in Your VMware Cloud Director.

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.
    • For system administrators:
      POST https://vcloud.example.com/cloudapi/1.0.0/sessions/provider 
Authorization: auth-type credentials
Accept: application/*;version=api-version
    • For tenants:
      POST https://vcloud.example.com/cloudapi/1.0.0/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 VMware Cloud Director 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