VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Authentication with vSphere APIs

This chapter provides an overview of authentication options for vSphere users. You can use either basic or token-based authentication to access vSphere APIs. Because it is the simplest method, this guide uses basic authentication to access vSphere APIs in the following chapters.
You can use both the vSphere Management SDK and the vSphere Automation API to manage your vSphere environment. With both SDKs, you gain access to a wider range of supported automation features. Use the:
  • vSphere Management SDK for host management, virtual machine provisioning, data center monitoring, virtual storage management, and more.
  • vSphere Automation SDK for configuration, authentication, certificate management, tagging, life cycle management, content libraries, Kubernetes cluster management, and more.

Choosing Your Identity Source

To administer vSphere users and groups, you must first choose your identity source. You can either:
Use the vCenter Server built-in identity source
vSphere comes with a built-in identity provider, called vCenter Single Sign-On. By default, vCenter Server uses the
vsphere.local
 domain as the identity source (but you can change this domain during installation). A vCenter Single Sign-On administrator can manage users and groups in the
vsphere.local
 domain from the vSphere Client. You can configure the vCenter Server built-in identity provider to use Active Directory (AD) as its identity source using LDAPS, OpenLDAP, and Integrated Windows Authentication (IWA). Such configurations allow customers to log into vCenter Server using their Active Directory or LDAP accounts.
Use an external identity provider as the identity source
In vSphere 7.0 and later, you can outsource identity management to an external identity provider through federated authentication. You replace vCenter Server as the identity provider and the administration of users and groups occurs on the external identity source. When you configure vSphere to use an external identity provider, the external identity provider interacts with the identity sources on behalf of vCenter Server.
You can federate vCenter Server to the following external identity providers:
  • Active Directory Federated Service (ADFS), starting in vSphere 7.0
  • Okta, starting in vSphere 8.0 Update 1
  • Microsoft Entra AD, starting in vSphere 8.0 Update 2
For more information on vSphere identity sources and identity management, see the topic "Authentication Mechanisms" in the
vSphere Automation REST API Programming Guide
.

Obtaining an Identifier and Unified Session

Before using the API services, principals must first obtain session identifiers for the vSphere Management API and the vSphere Automation API. Valid session identifiers guarantee identity of the principals and establish trust with the API endpoints.
To obtain a session identifier for the vSphere APIs, you can use different authentication mechanisms, as covered below. Once obtained, the session identifier is sent with every HTTPS request, or added to the security context for authentication.
Before vSphere 8.0 Update 3, separate sessions were required for vSphere Management API and for vSphere Automation API. As of vSphere 8.0 U3, unified sessions are supported. Now, developers can re-use a vSphere Management (VIM) session for vSphere Automation (vAPI) calls, and vice-versa. See Unified Management and Automation Session for details and code examples.

Choosing Your Authentication Method

To obtain a session identifier, you can choose among several authentication mechanisms depending on your needs and requirements. Simply stated, these mechanisms can be divided in two major groups: basic authentication and token-based authentication.

Basic Authentication

With basic authentication, you supply your vCenter Server or external provider user name and password when connecting to the vSphere Management or vSphere Automation endpoints.
  • If you use the built-in vCenter Server identity source, you connect with your local domain credentials.
  • With an external identity source, use your identity provider credentials to connect to the vSphere API endpoints. This workflow is possible thanks to the OAuth 2.0 Password grant type.
For more information, see these topics:
  • "Authenticate to vCenter Server with vCenter Single Sign-On Credentials" in the
    VMware vSphere Automation REST API Programming Guide
    .
  • "Authenticate by Using the Password Grant Type" in the
    VMware vSphere Automation REST API Programming Guide
    .
  • "Create a vSphere Automation Session with User Credentials" in the
    VMware vSphere Automation SDKs Programming Guide
    .
VMware encourages you to employ token-based authentication, because it is more secure and flexible.

Token-Based Authentication

With token-based authentication, principals issue a token request to the vCenter Single Sign-On built-in service. In response, vCenter Single Sign-On issues a Security Assertion Markup Language (SAML) token that principals use to obtain session identifiers for the vSphere Management API and the vSphere Automation API.
Obtaining a SAML token
You can obtain a SAML token by using either the
Issue
 service of the vSphere Management API or the
Authentication
Token
 service of the vSphere Automation API. For more information, see these topics:
  • "Authenticate to an AD FS-Federated vCenter Server by Using the Authorization Code Grant Type" in the
    VMware vSphere Automation REST API Programming Guide
    .
  • "Acquiring a SAML Token from a vCenter Single Sign-On Server" in the
    vCenter Single Sign-On Programming Guide
  • "Retrieve a SAML Token" in the
    VMware vSphere Automation SDKs Programming Guide
If you are using an external identity provider as the identity source, you must first obtain a JSON Web Token (JWT) from the identity provider and then exchange it for a SAML token. For more information, see topic "Authenticate to an AD FS-Federated vCenter Server by Using the Authorization Code Grant Type" in the
VMware vSphere Automation REST API Programming Guide
.
Creating a Session with the SAML Token
After you receive the SAML token, you use it to obtain a session identifier from the vSphere API endpoints.
  • For the vSphere Management API, use the
    LoginByToken
     service (in
    SessionManager
    ).
  • For the vSphere Automation API, use the
    CIS
    Session
     service.
Once you have obtained a session identifier, you can use it for authentication in your subsequent calls or in your security context.
Before vSphere 8.0 U3, you had to create separate authentication sessions for the vSphere Management API and the vSphere Automation API. That is, you needed a separate session identifier for each of the APIs. With unified session, this is no longer necessary.
For more information, see chapter "Authentication Mechanisms" in the
VMware vSphere Automation REST API Programming Guide
 and "LoginByToken Example" in the
vCenter Single Sign-On Programming Guide
.

Content feedback and comments