New-VIOAuth2Client Command | Vmware PowerCLI Reference

New-VIOAuth2Client

Creates a new OAuth2 client registration with the vCenter Identity Broker. The VMware Identity Broker is an OAuth2 relay that is used by client applications to authenticate with vCenter using OAuth2.

Syntax

New-VIOAuth2Client
-ClientId < String >
-GrantTypes < String[] >
-Scope < String[] >
[-AccessTokenTimeToLiveMinutes < Int32 > ]
[-Name < String > ]
[-PkceEnforced < Boolean > ]
[-PostLogoutRedirectUris < String[] > ]
[-ProgressAction < ActionPreference > ]
[-PublicClient < Boolean > ]
[-RedirectUris < String[] > ]
[-RefreshTokenIdleTimeToLiveMinutes < Int32 > ]
[-RefreshTokenTimeToLiveMinutes < Int32 > ]
[-RuleSetNames < String[] > ]
[-Secret < SecureString > ]
[-SecretTimeToLiveInMinutes < Int32 > ]
[-Server < VIServer[] > ]
[CommonParameters]

Parameters

Required Parameter Name Type Position Features Description
required
 ClientId String named
OAuth 2.0 Client identifier that the client uses to identify itself during the OAuth 2.0 exchanges. The client ID must contain only alphanumeric (A-Z, a-z, 0-9), period (.), underscore (_), hyphen (-) and at sign (@) characters.
required
 GrantTypes String[] named
Specifies a list of OAuth 2.0 Access Grant Types that are enabled in this OAuth 2.0 Client. Possible values are: password , client_credentials , refresh_token , authorization_code , token , id_token
required
 Scope String[] named
Specifies a list of access request scopes that are allowed by this OAuth 2.0 Client. Available scope options are: admin, user, profile, email, openid, group admin - Admin Level Access user - User Level Access profile - Access to the User's profile (FirstName, LastName, Display Name, Image) email - Access to the User's Email openid - Access to an OpenID token for the User group - Access to the User's groups
optional AccessTokenTimeToLiveMinutes Int32 named
How long in minutes new access tokens issued to this client should live.
optional Name String named
Specifies the user-friendly name that you set for this OAuth 2.0 client. This parameter is available only for vCenter instances of version 8.0 Update 3 and later.
optional PkceEnforced Boolean named
Specifies whether PKCE is enforced for the OAuth2 client. If not specified, the value is 'false'. This parameter is available only for vCenter instances of version 8.0 Update 3 and later.
optional PostLogoutRedirectUris String[] named
Specifies a list of absolute URLs to the OAuth2 Relaying Party. When a logout occurs, the Auth2 Relaying Party might request that the User Agent of the End-User is redirected to one of these absolute URLs. These URLs must contain the https scheme and can also have a port, path, and some query parameters. However, the URLs may also contain the http scheme, provided that the Client Type is confidential. To skip the check for a particular URL section, you can substitute a wildcard character with any string.
optional ProgressAction ActionPreference named
optional PublicClient Boolean named
Specifies whether the OAuth 2.0 client is public or not. A public client is one that does not have a secret. If not specified, the value is 'false'. This parameter is available only for vCenter instances of version 8.0 Update 3 and later.
optional RedirectUris String[] named
Specifies 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 2.0 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 GrantTypes parameter contain an "authorization_code" grant type.
optional RefreshTokenIdleTimeToLiveMinutes Int32 named
Specifies how long in minutes new refresh tokens issued to this client should live. Only applicable and mandatory if the GrantTypes parameter includes "refresh_token".
optional RefreshTokenTimeToLiveMinutes Int32 named
Specifies how long in minutes new refresh tokens issued to this client can be idle. Only applicable and mandatory if GrantTypes includes "refresh_token". Its value should be less than the refresh token TTL value (specified by the parameter RefreshTokenIdleTimeToLiveMinutes).
optional RuleSetNames String[] named
Specifies a list of built in rule set names to associate this client with. Each ruleset, allows the client to call a specific set of tenant APIs. Possible values are: TENANT_ADMIN , IDP_AND_DIRECTORY_ADMIN , READ_ONLY_TENANT_ADMIN TENANT_ADMIN - Allows the client to call all the tenant APIs. READ_ONLY_TENANT_ADMIN - Allows the client to call all the tenant read only APIs (i.e., APIs that do not make any changes). IDP_AND_DIRECTORY_ADMIN - Allows the client to call all the tenant Identity Providers and Directories APIs.
optional Secret SecureString named
Specifies the OAuth 2.0 Client secret. If secret string is not provided, an auto-generated secret will be returned. For additional security, the stored secret will not be returned by the Get-VIOAuth2Client. Public clients will not have any secret auto generated for them while confidential clients will always have a client secret.
optional SecretTimeToLiveInMinutes Int32 named
Specifies after what time in minutes the secret must be rotated. This parameter is available only for vCenter instances of version 8.0 Update 3 and later.
optional Server VIServer[] named
Specifies the vCenter Server systems on which you want to run the cmdlet. If no value is provided or $null value is passed to this parameter, the command runs on the default servers. For more information about default servers, see the description of Connect-VIServer.

Output

VMware.VimAutomation.ViCore.Types.V1.IdentityBroker.OAuth2Client

Examples

Example 1 

PS C:\> New-VIOAuth2Client `
    -ClientId "my-public-oauth-client" `
    -Name "My Public OAuth2 Client" `
    -Scope @("openid", "profile", "user", "group") `
    -GrantTypes @("authorization_code", "refresh_token", "password") `
    -RedirectUris @("http://127.0.0.1:8877/authcode") `
    -RefreshTokenTimeToLiveMinutes 43200 `
    -RefreshTokenIdleTimeToLiveMinutes 43200 `
    -PkceEnforced $true `
    -PublicClient $true

Creates a registration for a public OAuth 2.0 client with the specified client ID, scopes, grant types, and redirect URL. The OAuth2 client must implement the Proof Key for Code Exchange (PKCE) protocol to be registered.

Example 2 

PS C:\> New-VIOAuth2Client `
    -ClientId "my-oauth-client" `
    -Name "My OAuth2 Client" `
    -Secret "<my-random-secure-secret>" `
    -Scope @("openid", "profile", "user", "group") `
    -GrantTypes @("authorization_code", "refresh_token", "password") `
    -RedirectUris @("http://127.0.0.1:8877/authcode") `
    -RefreshTokenTimeToLiveMinutes 43200 `
    -RefreshTokenIdleTimeToLiveMinutes 43200 `
    -PkceEnforced $true

Creates a registration for a public OAuth 2.0 client with the specified client ID, scopes, grant types, and redirect URL. The OAuth2 client must implement the Proof Key for Code Exchange (PKCE) protocol to be registered.

Example 3 

PS C:\> New-VIOAuth2Client `
    -ClientId "powercli-native" `
    -Name "PowerCLI Client" `
    -Scope @("openid") `
    -GrantTypes @("authorization_code", "refresh_token") `
    -RedirectUris @("http://localhost:8844/authcode", "http://127.0.0.1:8844/authcode") `
    -AccessTokenTimeToLiveMinutes 30 `
    -RefreshTokenTimeToLiveMinutes 43200 `
    -RefreshTokenIdleTimeToLiveMinutes 43200 `
    -PkceEnforced $true `
    -Secret "powercli-public-secret"

If the user needs to use PowerCLI to authenticate using OAuth2, PowerCLI must be registered as an OAuth2 public client.

Related Commands

VIOAuth2Client

Creates a new OAuth2 client registration with the VMware Identity Broker.

Deletes a registration for a specified OAuth2 client from the VMware Identity Broker.

Updates the configuration of the OAuth2 client registered with the VMware Identity Broker.

VIOAuth2ClientSecretRotation

Forces an immediate secret rotation for a specific OAuth 2 client.

Initiates a rotation of the secret of an OAuth 2 client.

VIOauth2Client

This cmdlet retrieves the OAuth2 clients available on a vCenter Server system.

VIObjectByVIView

This cmdlet converts a vSphere View object to a VIObject.