PowerCLI Reference

Connect-Vmc

Synopsis

This cmdlet establishes a connection to a VMware Cloud on AWS server.

Syntax

Connect-Vmc [-RefreshToken <SecureString>] [-SaveRefreshToken] [-NotDefault] [<CommonParameters>]

Connect-Vmc -Menu [<CommonParameters>]

Related Commands

Online version
Disconnect-Vmc

Detailed Description

This cmdlet establishes a connection to a VMware Cloud on AWS server. Only Open Authorization (OAuth) is supported and a refresh token retrieves an access token, which later makes calls to the server.

There are several parameters of the server session that can be customized by setting any of the following PowerShell variables before invoking the Connect-Vmc command:

- If the $VmcServer variable is set, this changes the DNS name or the IP address of the VMware Cloud on AWS server where the management API calls are directed. If the variable is not set, the default "vmc.vmware.com" value is used. If you want to use the staging instance of VMware Cloud on AWS, set the variable to "stg.vmc.vmware.com".

- If the $VmcAuthenticationUrl variable is set, this changes the URL from which you want to obtain the authentication access tokens (passing the refresh token). If the variable is not set, the default "https://saas.csp.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize" value is used. If you want to use the staging instance of VMware Cloud on AWS, set the variable to "https://stg.csp.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize".

- If the $VmcApiMetadataUrl variable is set, this changes the URL path from which you want to download the metadata that describes the server API. If the variable is not set, the default "https://vmc.vmware.com/rest/com/vmware/vapi/metadata.json" value is used. Currently, the metadata download request is authenticated in the same manner as all the server API calls.

The connect and disconnect operations for a server are using a reference counting mechanism.

PowerCLI supports a list of default servers. When an operation is performed, if the target servers cannot be determined from the specified parameters, the cmdlet runs against the servers in the default server list. They are kept in the $defaultVmcServers variable. The default servers list is managed in the same manner as the other default server lists for the vCenter and vCloud servers.

When running, the cmdlet performs the following steps:
1. If the Menu parameter is specified, a list of the latest connected VMware Cloud on AWS servers appears.
2. If neither the Menu nor the Server parameter is specified, the default "vmc.vmware.com" value is used (the only available VMware Cloud on AWS server).
3. If the RefreshToken parameter is not specified, the local credential store is searched for a previously saved one. If a refresh token is not found, an error report is displayed.
4. When using the Server and RefreshToken parameters, a new access token is requested and is later used for communication with the server. The access token is regularly renewed by using the refresh token while the PowerShell process is running or the server connection is closed with the Disconnect-Vmc cmdlet.

Note: If PowerShell runs in non-interactive mode, you are not prompted for credentials. If the server certificate needs approval and it is not permanently accepted, it is automatically rejected and the cmdlet stops running.

Parameters

NameTypeDescriptionRequired?Pipeline InputDefault Value
MenuSwitchParameterIndicates that you want to select a connection server from a list of recently connected servers. If Menu is set to $true, the cmdlet retrieves a list of the last visited servers and enters a nested command prompt, so that you can select a server from the list.truefalse
NotDefaultSwitchParameterSpecifies that you do not want to save the specified servers as default servers (the $global:defaultVmcServers PowerShell variable).falsefalse
RefreshTokenSecureStringSpecifies the OAuth refresh token you want to use for authentication with the VMware Cloud on AWS server. The token is obtained from the VMware Cloud on AWS server's Web UI portal.falsefalse
SaveRefreshTokenSwitchParameterIndicates that the refresh token that you use for establishing the server session is saved to a local credential store and can be used automatically when connecting again to the same server.falsefalse

Return Type

VMware.VimAutomation.Vmc.Types.V1.VmcServer

Notes

Examples

-------------- Example 1 --------------

Connect-Vmc -RefreshToken $myRefreshToken

Connects to a VMware Cloud on AWS server.

-------------- Example 2 --------------

Connect-Vmc -RefreshToken $script:refreshToken -SaveRefreshToken

Connects to a VMware Cloud on AWS server by specifying the related secure connection token and saving it for later usage.

-------------- Example 3 --------------

$VmcServer = $newVmcServerAddress
$VmcAuthenticationUrl = $newVmcServerAuthenticationUrl
$VmcApiMetadataUrl = $newVmcServerMetaDataUrl
Connect-Vmc -RefreshToken $myNewRefreshToken

Sets the VMware Cloud on AWS server, authentication, and API metadata URL variables and then connects to a VMware Cloud on AWS server by specifying the related secure connection token.


Copyright © VMware, Inc. All rights reserved.