How-To: Connect to a FlashArray with the PowerShell SDK v2

Connect with Credentials

Purity API 2.2 or later

$FlashArray = Connect-Pfa2Array -EndPoint 10.0.0.1 -Credential (Get-Credential) -IgnoreCertificateError

The below example uses the -Credentialparameter to create a session to the Pure Storage FlashArray at 10.0.0.1 (-EndPoint). The -EndPoint can either be an IP address or a Fully Qualified Domain Name (FQDN). Once connected, the session is stored as a PowerShell Object (PSObject) with the variable name of $FlashArray. The -Credentialparameter is set to use the Windows PowerShell cmdlet Get-Credential which will prompt for a User name and Password.

Once the credentials have been entered and OK clicked, the Connect-Pfa2Array cmdlet will complete the session. 

Note that in the above example the -IgnoreCertificateErroris used as part of the Connect-Pfa2Array cmdlet. This parameter prevents certificate errors such as an unknown certificate issuer or non-matching names from causing the request to fail.

Connect with a username and password

Purity API 2.2 or later

$FlashArray = Connect-Pfa2Array -EndPoint 10.0.0.1 -UserName pureuser -Password (ConvertTo-SecureString -String 'mypassword' -AsPlainText -Force) -IgnoreCertificateError

Connect via OAuth2

Purity API 2.0 or later

To create a PowerShell session to an array using OAuth2, follow the 2 steps bellow:

1. An API Client registration on the array, and an RSA key pair (certificates).

   If you already have an API Client you can proceed to step 2.

   To create a PowerShell Session using OAuth2, you will need an API Client on the FlashArray. You can create an API Client either using the Purity//FA CLI commands (See pureapiclient command in the CLI or this article for details), or using a Pure Storage PowerShell SDK 2 REST session.

   There are two ways to create an API Client using Pure Storage PowerShell SDK 2: Using the cmdlets New-Pfa2ApiClient or New-Pfa2ArrayAuth.

   This article shows the which versions of the API is included with each FlashArray Purity version.To determine exactly what API versions are supported on your array, use your browser and connect to https://<FQDN or IP Address of array>/api/api_version. 

   a. If you want to use your existing RSA key pair, use New-Pfa2ApiClient. Note that you need to be already authenticated with the array, either with an existing API Client or using the API Token (not available with API versions 2.0 or 2.1). If you are not authenticated yet to an array that supports API version 2.2 or later, do so using the Connect-Pfa2Array command as shown previously. Once authenticated, use the command shown below.

   PS C:\>$ApiClient = New-Pfa2ApiClient -Array $Array -MaxRole $MaxRole -Issuer $ArrayIssuer -PublicKey $Certificate -Name $ClientName 
   

   Where,

   • $Array is the PureArray object returned by the Connect-Pfa2Array command.
   • $MaxRole is the maximum role allowed for ID Tokens issued by this API client. Valid values are array_admin, storage_admin, ops_admin, and readonly.
   • $ArrayIssuer is the name of the identity provider that will be issuing ID Tokens for this API client. This can be any arbitrary unique name or specific for audit purposes. Often times this parameter is set the same as the $ClientName.
   • $Certificate is the API Client's PEM formatted (Base64 encoded) RSA public key.
   • $ClientName is the unique name to be used for this API Client.

   API Clients created using New-Pfa2ApiClient are disabled by default. To enable the API Client use the command Update-Pfa2ApiClient:

   PS C:\>Update-Pfa2ApiClient -Array $Array -Name $ClientName -Enabled $true 
   

   b. If you do not want to use your own key pair, the New-Pfa2ArrayAuth command bellow will generate a key pair for you and store it under %USERPROFILE%\.ssh\, or Mac/Linux under ~/.ssh/*. The command will also create the API Client on the FlashArray. Please note that if the API Client already exists, the command will return the existing client.

   PS C:\>$ApiClientAuthInfo = New-Pfa2ArrayAuth -Endpoint $ArrayEndpoint -ApiClientName $Clientname -Issuer $ArrayIssuer -Username $ArrayUsername -Password $ArrayPassword -Force
   

   Where,

   • $ArrayEndpoint is the FlashArray IP or Name.
   • $ClientName is the unique name for this API Client.
   • $ArrayIssuer is the name of the identity provider that will be issuing ID Tokens for this API client. This can be any arbitrary unique name or specific for audit purposes. Often times this parameter is set the same as the $ClientName.
   • $ArrayUsername is the FlashArray username.
   • $ArrayPassword is the FlashArray Password (SecureString Object).

2. Create OAuth2 session using the API client KeyID and ClientID: To create an OAuth2 session this way, you will need the following information from the API Client: $clientID, $keyId, and $privateKeyFile. This information can be retrieved from the response of the New-Pfa2ArrayAuth command performed previously.

   PS C:\>$clientId = $ApiClientAuthInfo.PureClientApiClientInfo.clientId 
   PS C:\>$keyId = $ApiClientAuthInfo.PureClientApiClientInfo.KeyId 
   PS C:\>$privateKeyFile = $ApiClientAuthInfo.pureCertInfo.privateKeyFile
   

   Optionally, if you used the New-Pfa2ApiClient command, $clientID and $keyId can also be retrieved from the response of the New-Pfa2ApiClient command used previously, and $privateKeyFile should be your private key file location:

   PS C:\>$clientId = $ApiClient.Id 
   PS C:\>$keyId = $ApiClient.KeyId 
   PS C:\>$privateKeyFile = "<path to private key file>"
   

   A third option is to use the command pureapiclient list, on the Purity//FA CLI, to list all existing API Clients.  

3. Finally, use the following command to create the OAuth2 session:

   PS C:\>$oauth = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Username $ArrayUsername -Issuer $ArrayIssuer -ApiClientName $Clientname -ClientId $clientId -KeyId $keyId -PrivateKeyFile $privateKeyFile -PrivateKeyPassword $privateKeyPassword -IgnoreCertificateError
   

   Where,

   • $ArrayEndpoint is the FlashArray IP or Name.
   • $ArrayUsername is the FlashArray username.
   • $ArrayIssuer is the name of the identity provider that will be issuing ID Tokens for this API client. This can be any arbitrary unique name or specific for audit purposes. Often times this parameter is set the same as the $ClientName.
   • $ClientName is the unique name for this API Client.
   • $privateKeyPassword is required if the private key was generated using a passphrase. If you created the API Client using the New-Pfa2ArrayAuth command there is no passphrase. This password should be a SecureString object.

   Note: The Connect-Pfa2Array cmdlet caches authentication information for the duration of the PowerShell session. With this, subsequent SDK cmdlets do not need to explicitly provide -Array parameter. The cmdlets will retrieve the FlashArray authentication information from PowerShell session variable.

This is an example function that combines all of the commands and variables necessary for OAuth authentication using a generated Private Key for the user. You could use this function in multiple scripts to eliminate repetitive entries. Optionally, it prints to the screen the $clientID, $keyId, and $privateKeyFile variables for use.

# Define the variables
PS C:\>$ArrayEndpoint = "10.1.1.1" # is the FlashArray IP or Name
PS C:\>$ArrayClientname = "demo" # is the unique name for this API Client
PS C:\>$ArrayIssuer = $ArrayClientname # is the name of the identity provider that will be issuing ID Tokens for this API client
PS C:\>$ArrayPassword = ConvertTo-SecureString "pureuser" -AsPlainText -Force # is the FlashArray Password (SecureString)
PS C:\>$ArrayUsername = "pureuser" # is the FlashArray username
PS C:\>$MaxRole = "array_admin" # The role the user has on the array
PS C:\>$privateKeyPass = ConvertTo-SecureString "Pr1v@teK3y!#" -AsPlainText -Force #is required if the private key was generated using a passphrase. If you created the API Client using the `New-Pfa2ArrayAuth` command there is no passphrase. This password should be a SecureString.

# Remove the comments on the 'Write-Host' lines if you want to variables output to screen.
function ArrayAuth () {
    $fa = New-Pfa2ArrayAuth -MaxRole array_admin -Endpoint $ArrayEndpoint -APIClientName $ArrayClientname -Issuer $ArrayIssuer -Username $ArrayUsername -Password $ArrayPassword
    $clientId = $fa.PureClientApiClientInfo.clientId
    #Write-Host "ClientID: $($clientId)"
    #Write-Host " "
    $keyId = $fa.PureClientApiClientInfo.KeyId
    #Write-Host "KeyID $($KeyId)"
    #Write-Host " "
    $privateKeyFile = $fa.pureCertInfo.privateKeyFile
    #Write-Host "PrivateKey $($privateKeyFile)"
}
ArrayAuth

PS C:\>$array = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Username $ArrayUsername -Issuer $ArrayIssuer -ClientId $clientId -KeyId $keyId -PrivateKeyFile $privateKeyFile -PrivateKeyPassword $privateKeyPass -IgnoreCertificateError -ApiClientName $ArrayClientname