Connect via OAuth2

Microsoft Platform Guide
Audience
Public
Source Type
Documentation

Purity API 2.0 or later (required for API 2.0 and 2.1)

Note:

For more information on OAuth2, please visit this site.

Note:

The client certificate issued by the array and stored in the ~\.ssh folder of the users home folder is not secured with a passphrase for the private key. If you require a secure private key, you must supply your own certificate.

An OAuth2 connection to a FlashArray using the PowerShell SDK requires a simple 3-Step process. Steps 1 and 2 create the necessary tokens and key, and step 3 creates the connection object.

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

If you already have an API Client defined, 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 REST API 2.0 Authentication Guide for details), or using a Everpure PowerShell SDK 2 REST session.

There are two ways to create an API Client using Everpure PowerShell SDK 2: Using the cmdlets New-Pfa2ApiClient (Option A) or New-Pfa2ArrayAuth (Option B).

Option 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

    Option 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,

  • $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.
  • $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).

Step 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 following options:

Option A - The New-Pfa2ArrayAuth command performed previously.


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

Option B - 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 (by default ~\.ssh):


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

Option C - Use the command pureapiclient list, on the Purity//FA CLI, to list all existing API Clients.

Step 3 - 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 the -Array parameter. The cmdlets will retrieve the FlashArray authentication information from PowerShell session variable.

Example Function for OAuth2 Authentication

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.0.0.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