New-OAuthSecurityContext Command | Vmware PowerCLI Reference

New-OAuthSecurityContext

Creates an OAuth2 security context object that you can use to authenticate to any system that is configured to trust the specified authentication server.For more information about security contexts, see the about_security_context article.To use this command, you need to create an OAuth client in the authentication server. Take a note of the client ID and secret generated by the server as you need to pass them to the command. Some authentication servers might not require a client secret in some cases.To use this command, you need to know the URLs where the authentication server is listening for requests. You can find these in the openid-configuration file of your server or in the documentation for your server. The system that you try to login might also be able to provide these URLs or the URL to the openid-configuration file. For example, if a vCenter server is configured to trust an Open ID server, you can see the required URLs in the vCenter server configuration user interface. For Microsoft Active Directory Federation Service, the openid-configuration file is located at https://.../adfs/.well-known/openid-configuration.Some authentication servers might require you to pass additional parameters that are not specified in the OAuth2 specification but are custom for your particular server. You should check the documentation of the authentication server for information about these. You can use the OtherArguments parameter to pass the additional parameters. For example, if you work with the Microsoft Active Directory Federation Service and the Application Group, you must use the "resource" custom parameter to pass the Application Group identifier.This command supports the following authentication options: - authorization_code grant type: authenticate as a user by using the web browser. For this flow, you need to create an OAuth2 client with a redirect URL on localhost and a free port. See example 1.- client_credentials grant type: authenticate as a service that is identified by the client ID. For this flow, you need to create an OAuth2 client that has a client secret. See example 2.- refresh_token grant type: authenticate as a user by using a refresh token from a previous authentication. For this flow, you need to have access to a refresh token and the client credentials of the OAuth2 client that this token was given to.- password grant type: authenticate as a user by using the user's credentials. For this flow, you need to create an OAuth2 client that can use the password grant type. See example 3.

Syntax

New-OAuthSecurityContext
-AuthorizationEndpointUrl < Uri >
-ClientId < String >
-RedirectUrl < Uri >
-TokenEndpointUrl < Uri >
[-ClientSecret < SecureString > ]
[-DisablePKCE ]
[-IgnoreSslValidationErrors ]
[-OtherArguments < Hashtable > ]
[-ProgressAction < ActionPreference > ]
[-Scope < String > ]
[CommonParameters]

Parameters

Required Parameter Name Type Position Features Description
required
AuthorizationEndpointUrl Uri named
Specifies 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.
required
ClientId String named
Specifies the ID of the OAuth client registered in the authentication server.
required
RedirectUrl Uri named
Specifies the Redirect URL associated with this OAuth client. This URL must be on localhost and a free port on the machine where PowerCLI is running. This URL must use the http schema.
required
TokenEndpointUrl Uri named
Specifies the 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 the token_endpoint key.
optional ClientSecret SecureString named
Specifies the client secret for this OAuth client (if the server requires a client secret).
optional DisablePKCE SwitchParameter named
If specified, the authorization code exchange is not protected using the Proof Key for Code Exchange by OAuth Public Clients (https://tools.ietf.org/html/rfc7636). You can use this if the server cannot process the additional parameters introduced by PKCE.
optional IgnoreSslValidationErrors SwitchParameter named
If specified, you can force the connection even if the SSL certificate of the server is not valid.
optional OtherArguments Hashtable named
Specifies the hashtable of (string, string) pairs that represent arguments to the server-specific parameters.
optional ProgressAction ActionPreference named
optional Scope String named
Specifies the OAuth2 scope of the access tokens that would be generated by this security context.
New-OAuthSecurityContext
-ClientId < String >
-ClientSecret < SecureString >
-TokenEndpointUrl < Uri >
[-IgnoreSslValidationErrors ]
[-OtherArguments < Hashtable > ]
[-ProgressAction < ActionPreference > ]
[-Scope < String > ]
[CommonParameters]

Parameters

Required Parameter Name Type Position Features Description
required
ClientId String named
Specifies the ID of the OAuth client registered in the authentication server.
required
ClientSecret SecureString named
Specifies the client secret for this OAuth client (if the server requires a client secret).
required
TokenEndpointUrl Uri named
Specifies the 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 the token_endpoint key.
optional IgnoreSslValidationErrors SwitchParameter named
If specified, you can force the connection even if the SSL certificate of the server is not valid.
optional OtherArguments Hashtable named
Specifies the hashtable of (string, string) pairs that represent arguments to the server-specific parameters.
optional ProgressAction ActionPreference named
optional Scope String named
Specifies the OAuth2 scope of the access tokens that would be generated by this security context.
New-OAuthSecurityContext
-ClientId < String >
-Password < SecureString >
-TokenEndpointUrl < Uri >
-Username < String >
[-ClientSecret < SecureString > ]
[-IgnoreSslValidationErrors ]
[-OtherArguments < Hashtable > ]
[-ProgressAction < ActionPreference > ]
[-Scope < String > ]
[CommonParameters]

Parameters

Required Parameter Name Type Position Features Description
required
ClientId String named
Specifies the ID of the OAuth client registered in the authentication server.
required
Password SecureString named
Specifies the password of the user.
required
TokenEndpointUrl Uri named
Specifies the 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 the token_endpoint key.
required
Username String named
Specifies the username of the user.
optional ClientSecret SecureString named
Specifies the client secret for this OAuth client (if the server requires a client secret).
optional IgnoreSslValidationErrors SwitchParameter named
If specified, you can force the connection even if the SSL certificate of the server is not valid.
optional OtherArguments Hashtable named
Specifies the hashtable of (string, string) pairs that represent arguments to the server-specific parameters.
optional ProgressAction ActionPreference named
optional Scope String named
Specifies the OAuth2 scope of the access tokens that would be generated by this security context.
New-OAuthSecurityContext
-ClientId < String >
-RefreshToken < SecureString >
-TokenEndpointUrl < Uri >
[-ClientSecret < SecureString > ]
[-IgnoreSslValidationErrors ]
[-OtherArguments < Hashtable > ]
[-ProgressAction < ActionPreference > ]
[-Scope < String > ]
[CommonParameters]

Parameters

Required Parameter Name Type Position Features Description
required
ClientId String named
Specifies the ID of the OAuth client registered in the authentication server.
required
RefreshToken SecureString named
Specifies the refresh token issued for this OAuth client.
required
TokenEndpointUrl Uri named
Specifies the 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 the token_endpoint key.
optional ClientSecret SecureString named
Specifies the client secret for this OAuth client (if the server requires a client secret).
optional IgnoreSslValidationErrors SwitchParameter named
If specified, you can force the connection even if the SSL certificate of the server is not valid.
optional OtherArguments Hashtable named
Specifies the hashtable of (string, string) pairs that represent arguments to the server-specific parameters.
optional ProgressAction ActionPreference named
optional Scope String named
Specifies the OAuth2 scope of the access tokens that would be generated by this security context.

Output

VMware.VimAutomation.Common.Types.V1.Authentication.GenericOAuth2SecurityContext

Examples

Example 1

$oauthCtx = New-OAuthSecurityContext `
    -TokenEndpointUrl "https://<ADFS FQDN>/adfs/oauth2/token/" `
    -AuthorizationEndpointUrl "https://<ADFS FQDN>/adfs/oauth2/authorize/" `
    -RedirectUrl "http://localhost:8844/auth" `
    -ClientId "powercli-native" `
    -OtherArguments @{ "resource" = "my-vcenter" }

Creates an OAuth2 security context object by authenticating through the authorization server using a browser. In this example, the authentication server is Microsoft Active Directory Federation Service. There is an Application Group with the ID of "my-vcenter". There is also a native client in that group with the ID of "powercli-native" and a redirect URL of "http://localhost:8844/auth".

Example 2

$oauthCtx = New-OAuthSecurityContext `
    -TokenEndpointUrl "https://<ADFS FQDN>/adfs/oauth2/token/" `
    -ClientId "powercli-service" `
    -ClientSecret "...." `
    -OtherArguments @{ "resource" = "my-vcenter" }

Creates an OAuth2 security context object by authenticating as a service application using the client ID and secret. In this example, the authentication server is Microsoft Active Directory Federation Service. There is an Application Group with the ID of "my-vcenter". There is also a native client in that group with the ID of "powercli-service" and a client secret.

Example 3

$oauthCtx = New-OAuthSecurityContext `
    -TokenEndpointUrl "https://<ADFS FQDN>/adfs/oauth2/token/" `
    -ClientId "powercli-native" `
    -Username "[email protected]" `
    -Password "the password" `
    -OtherArguments @{ "resource" = "my-vcenter" }

Creates an OAuth2 security context object by authenticating as the user using his credentials. In this example, the authentication server is Microsoft Active Directory Federation Service. An Application Group is created with the ID of "my-vcenter". There is also a native client in that group with the ID of "powercli-native".

Related Commands

OAuthSecurityContext

Creates an OAuth2 security context object that you can use to authenticate to any system that is configured to trust the specified authentication server.