If your vCenter Server is configured with an external identity provider, such as Microsoft Active Directory Federation Services (AD FS) or other external identity provider supported by VMware Identity Service, you can authenticate with PowerCLI by using the OAuth 2.0 Authorization Code grant type.

You can authenticate to a federated vCenter Server by creating a new OAuth security context and then exchanging it for a SAML security context. You create an OAuth security context for PowerCLI by using the New-OAuthSecurityContext cmdlet. One way to do this is to authenticate through the Authorization Code grant type, which is illustrated by this example. This workflow guarantees a substantial degree of security and can be used with multi-factor authentication.

Note: You can use PowerCLI to authenticate with the other OAuth 2.0 grant types as well, such as the Client Credentials, Refresh Token, and Password grant types. For more information, run Get-Help New-OAuthSecurityContext -full.

Connect to a vCenter Server System Configured to Use AD FS for an External Identity Provider

If your vCenter Server is federated to Microsoft Active Directory Federation Services (AD FS), you can authenticate with PowerCLI by using the OAuth 2.0 Authorization Code grant type.

Prerequisites

  • Verify that your vCenter Server system is federated to AD FS. For more information, see Federate vCenter Server to Microsoft Active Directory Federation Services (AD FS) in the VMware vSphere Automation REST API Programming Guide.
  • Create an OAuth client for PowerCLI on the authentication server (AD FS). Configure the OAuth client to do the same token transformation as your vCenter Server system . You must configure a redirect URL according to the requirements in the procedure below. Save the Client ID and Client Secret that are generated by the authentication server. For more information, see the Microsoft documentation.

Procedure

  1. Create an OAuth security context object for PowerCLI.
    In the background, PowerCLI sends an authentication request to the authentication server, AD FS. A web browser opens that prompts the user to authorize the client application's request. On confirmation, PowerCLI interacts with the authentication server to obtain the access and ID tokens (JWT tokens) and creates a new OAuth security context. 
    $oauthSecContext = New-OAuthSecurityContext -TokenEndpointUrl "https://<ad_fs_fqdn>/adfs/oauth2/token/" -AuthorizationEndpointUrl "https://<ad_fs_fqdn>/adfs/oauth2/authorize/" 
-RedirectUrl "http://localhost:8844/auth" -ClientId "powercli-native" -OtherArguments @{ "resource" = "my-vcenter" }
    This script contains the following parameters.
    Parameter Description Example value
    TokenEndpointUrl

    The base URL where the authentication server listens for requests to issue access tokens. You can see this value in the openid-configuration file of the authentication server under token_endpoint key.

    		 https://<ad_fs_fqdn>/adfs/oauth2/token/
    AuthorizationEndpointUrl

    The base URL at the authentication server where users are redirected in order to authenticate. You can see this value in the openid-configuration file under the authorization_endpoint key.

    		 https://<ad_fs_fqdn>/adfs/oauth2/authorize/
    RedirectUrl

    The URL where the user is redirected after he approves the authentication request. This URL must be on a localhost and a free port on the machine where PowerCLI is running. This URL must use the http schema.

    		 http://localhost:8844/auth
    ClientId The ID that you received from the authentication server when you registered the client application. powercli-native
    OtherArguments A hashtable of (String, String) pairs that represent arguments to the server-specific parameters. In the following example, it is used for an AD FS Application Group for vCenter Server with an example ID "my-vcenter". { "resource" = "my-vcenter" }
  2. Exchange the OAuth security context for an SAML security context. 
    $samlSecContext = New-VISamlSecurityContext -VCenterServer 'myVC' -OAuthSecurityContext $oauthSecContext
  3. Connect to your vCenter Server system by using the SAML security context. 
    Connect-VIServer -Server 'myVC' -SamlSecurityContext $samlSecContext

Connect to a vCenter Server System Configured to Use External Identity Providers Supported by VMware Identity Services

With vSphere 8.0 Update 1, VMware Identity Services is a built-in container within vCenter Server that you can use for identity federation to external identity providers. It serves as an independent identity broker within vCenter Server and currently supports Okta, Microsoft Entra ID, and PingFederate as external identity providers. Starting with vSphere 8.0 Update 3, PowerCLI integrates with VMware Identity Services to support the use of external identity providers to authenticate to vCenter Server.

Prerequisites

  • Verify that your vCenter Server system is federated to an identity provider supported by VMware Identity Service. See the Configuring vCenter Server Identity Provider Federation chapter in the vSphere Authentication guide.
  • Verify that you have the vCenter Single Sign-On administrator privileges.

Procedure

  1. Log in as an administrator to vCenter Server.
  2. Create a new OAuth client registration with the VMware Identity Services. 
    New-VIOAuth2Client -ClientId "powercli-native" -Name "PowerCLI Client" -Scope @("openid", "user", "group") -GrantTypes @("authorization_code", "refresh_token") -RedirectUris @("http://localhost:8844/authcode") -AccessTokenTimeToLiveMinutes 30 -RefreshTokenTimeToLiveMinutes 43200 -RefreshTokenIdleTimeToLiveMinutes 28800 -PkceEnforced $true -Secret "<secret_value>"

    The New-VIOAuth2Client cmdlet accepts the following parameters:

    Parameter Description Example
    ClientId The identifier used from the client to identify itself during the OAuth exchanges. The client ID must contain only alphanumeric (A-Z, a-z, 0-9), period (.), underscore (_), hyphen (-) and the at sign (@) characters. "powercli-native"
    Name

    The user-friendly name that you set for this OAuth client.

    		 "PowerCLI Client"
    Scope

    A list of access request scopes that are allowed by this OAuth client.

    Available scope options are: admin, user, profile, email, openid, and group.

    • admin - Provides admin level access.
    • user - Provides user level access.
    • profile - Provides access to the user's profile (first name, last name, display name, and image)
    • email - Provides access to the user's email.
    • openid - Provides access to an OpenID token for the user.
    • group - Provides access to the user's groups.

    The minimal set of values is @("openid", "user", "group")

    		 @("openid", "user", "group")
    GrantTypes A list of OAuth access grant types that are enabled in this OAuth client.

    Possible values are: password, client_credentials, refresh_token, authorization_code, and token, id_token.

    The minimal set of values is @("authorization_code", "refresh_token")

    		 @("authorization_code", "refresh_token")
    RedirectUris A list of absolute URIs of application endpoints that are allowed to receive the authorization code and access token. The redirect URI sent by the application as part of the authorization code grant OAuth flow is verified against this list. A wildcard can be substituted for any string to skip the check for a particular URL section. The field is required if the GrantTypes parameter contains an "authorization_code" grant type.

    This URL must point to localhost and use a free port on the machine where PowerCLI is running. The URL must use the HTTP schema.

    		 @("http://localhost:8844/authcode")
    AccessTokenTimeToLiveMinutes The period of time, in minutes, for which the new access tokens issued to this client should live. 30
    RefreshTokenIdleTimeToLiveMinutes The period of time, in minutes, for which the new refresh tokens issued to this client can be idle. This parameter is only applicable and mandatory if GrantTypes includes "refresh_token". Its value should be less than the value specified by the RefreshTokenTimeToLiveMinutes parameter. 28800
    RefreshTokenTimeToLiveMinutes The period of time, in minutes, for which the new refresh tokens issued to this client should live. Only applicable and mandatory if the GrantTypes parameter includes "refresh_token". 43200
    PkceEnforced

    Specifies whether Proof of Key Code Exchange (PKCE) is enforced for the OAuth client. If not specified, the value is false.

    		 $true
    Secret Specifies the OAuth client secret.

    If a secret string is not provided, an auto-generated secret is returned.

    For additional security, the stored secret is not be returned by the Get-VIOAuth2Client cmdlet.

    Public clients must not have any secret auto generated for them while confidential clients must always have a client secret.

    Note: The secret is required to connect to the vCenter Server and must be distributed to the users of this OAuth client.
    		"<secret_value>"
  3. Create an OAuth security context object for PowerCLII. 
    $oauthSecContext = New-OAuthSecurityContext -TokenEndpointUrl "https://<vcenter_fqdn>/acs/t/CUSTOMER/token" -AuthorizationEndpointUrl "https://<vcenter_fqdn>/acs/t/CUSTOMER/authorize" -RedirectUrl "http://localhost:8844/auth" -ClientId "powercli-native" -ClientSecret "<secret_value>"
    The script contains the following parameters:
    Parameter Description Example
    TokenEndpointUrl The base URL used by the VMware Identity Services to listen for access token requests. https://<vcenter_fqdn>/acs/t/CUSTOMER/token
    AuthorizationEndpointUrl The VMware Identity Services URL used to redirect users to authenticate. https://<vcenter_fqdn>/acs/t/CUSTOMER/authorize
    RedirectUrl The URL where the user is redirected after the approval of the authentication request. This URL must point to localhost and use a free port on the machine where PowerCLI is running. This URL must use the HTTP schema.
    Note: The value of this property must match the value specified with the RedirectUris parameter used for the registration of the OAuth client in step 2.
    		http://localhost:8844/auth
    ClientId The ID of the PowerCLI OAuth client created in step 2. powercli-native
    ClientSecret The client secret of the PowerCLI OAuth client created in step 2. "<secret_value>"
    When this script runs, PowerCLI uses VMware Identity Services to send an authentication request to the authentication server. A Web browser opens and prompts the user to authorize the request of the client application. On confirmation, VMware Identity Services interacts with the authentication server to obtain the access and ID tokens, JSON Web Token (JWT). Based on this output PowerCLI creates a new OAuth security context.
  4. Exchange the OAuth 2.0 security context for a SAML security context. 
    $samlSecContext = New-VISamlSecurityContext -VCenterServer '<vcenter_fqdn>' -OAuthSecurityContext $oauthSecContext
  5. Connect to your vCenter Server system by using the SAML security context. 
    Connect-VIServer -Server '<vcenter_fqdn>' -SamlSecurityContext $samlSecContext

Unattended Logins to a Federated vCenter Server System

Unattended logins to a federated vCenter Server system represent a security threat and must be allowed with great caution.

When you register the vCenter Server OAuth client with the OAuth provider, you can create a configuration that allows password grant type (Resource Owner Password Credentials grant type) for some users. Such users can then perform unattended logins to the federated vCenter Server system.

Note: This flow exposes the user credentials to the client application, PowerCLI, and to vCenter Server. To minimize the security risk, allow access only to service users with limited permissions. For more information, see: https://oauth.net/2/grant-types/password/.
To connect to the vCenter Server system, you can directly use the Connect-VIServer cmdlet in the following way: 
Connect-VIServer -Server '<vcenter_fqdn>' -User '<user_name>' -Password
      '<user_password>'