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 thevsphere.localdomain as the identity source (but you can change this domain during installation). A vCenter Single Sign-On administrator can manage users and groups in thevsphere.localdomain 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 theVMware vSphere Automation REST API Programming Guide.
- "Authenticate by Using the Password Grant Type" in theVMware vSphere Automation REST API Programming Guide.
- "Create a vSphere Automation Session with User Credentials" in theVMware 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 theIssueservice of the vSphere Management API or theAuthenticationTokenservice 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 theVMware vSphere Automation REST API Programming Guide.
- "Acquiring a SAML Token from a vCenter Single Sign-On Server" in thevCenter Single Sign-On Programming Guide
- "Retrieve a SAML Token" in theVMware 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 theVMware 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 theLoginByTokenservice (inSessionManager).
- For the vSphere Automation API, use theCISSessionservice.
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
.