If your vCenter Server is federated to an enterprise identity provider, such as Active Directory Federation Services (AD FS), you can authenticate your client applications by using the OAuth 2.0 Authorization Code grant type.

You can use the Authorization Code grant type if you want to authenticate client apps to vCenter Server through multifactor authentication (MFA). This grant type is applicable for regular web applications that involve a human user interacting with a server.

Figure 1. Authentication to an AD FS-Federated vCenter Server Through the Authorization Code Grant Type
The seven-step process of authenticating a principal to vCenter Server through the Authorization Code grant type.

A principal authenticates to vCenter Server through the Authorization Code grant type as follows.

Prerequisites

  • Verify that your vCenter Server is federated to AD FS. For more information, see Federate vCenter Server to Active Directory Federation Services (AD FS).

  • You must have an AD FS account and user credentials with the necessary permissions to view and manage vCenter Server.

  • You must register an OAuth client for your application on the authorization server (AD FS).

Procedure

  1. The user clicks Login within the client application.
  2. The client application constructs a request to the AD FS authorization endpoint.

    To retrieve the authorization endpoint, you must query the AD FS discovery endpoint at, for example, https://<your_adfs_server.com>/adfs/.well-known/openid-configuration.

    The client application's request must include the application's client ID and a redirect URI that tells the authorization server where to redirect the user after approving the request.

    As a result, the authorization server opens a prompt page asking the user to authorize the client application's request.

  3. The user confirms the request.

    The browser is redirected back to the client application with an authorization code in the query string.

  4. The client application sends a request to the AD FS token endpoint with the authorization code, client ID, and secret.

    The authorization server verifies the request and sends an access token and an ID token (JWT tokens).

  5. The client application sends the JWT tokens to vCenter Single Sign-On by using the Token interface of the com.vmware.vcenter.authentication package.
    1. Create an object of type TokenTypes.IssueSpec with the following modifiers.
      Method Value
      setSubjectTokenType urn:ietf:params:oauth:token-type:access_token
      setSubjectToken <ACCESS_TOKEN>
      setActorTokenType urn:ietf:params:oauth:token-type:id_token
      setActorToken <ID_TOKEN>
      setGrantType urn:ietf:params:oauth:grant-type:token-exchange
      setRequestedTokenType urn:ietf:params:oauth:token-type:saml2
    2. Call the issue(TokenTypes.IssueSpec) method

    vCenter Single Sign-On returns a SAML token.

  6. The client application calls the Common Infrastructure Services (CIS) Session service.
    By using the CIS Session service, principals can manage session tokens - including creation and deletion of session identifiers, and obtaining information about sessions.
    1. Base-64 decode the SAML token, compress it, and then Base-64 encode it again.
    2. Call the session.create() method with the SAML token.

    On success (status code 201), the vSphere Automation endpoint returns a session identifier in the response.

  7. To authenticate, the client application uses the session identifier in subsequent API calls to the vSphere Automation API endpoints.