Functions/Accounts/Get-PASAccountPassword.ps1

function Get-PASAccountPassword {
    <#
.SYNOPSIS
Returns password for an account.

.DESCRIPTION
Returns password for an account identified by its AccountID.

If using version 9.7+ of the API:
 - Will not return SSH Keys.
 - Cannot be used if a reason for password access must be specified.

If using version 10.1+ of the API:
 - Will return SSH key of an existing account
 - Can be used if a reason and/or ticket ID must be specified.

.PARAMETER AccountID
The ID of the account whose password will be retrieved.

.PARAMETER UseV10API
Specify switch to explicitly use the version 10 api when only providing AccountID.

.PARAMETER Reason
The reason that is required to be specified to retrieve the password/SSH key.
Use of parameter requires version 10.1 at a minimum.

.PARAMETER TicketingSystemName
The name of the Ticketing System.
Use of parameter requires version 10.1 at a minimum.

.PARAMETER TicketId
The ticket ID of the ticketing system.
Use of parameter requires version 10.1 at a minimum.

.PARAMETER Version
The version number of the required password.
If there are no previous versions, the current password/key version is returned.
Use of parameter requires version 10.1 at a minimum.

.PARAMETER ActionType
The action this password will be used for.
Use of parameter requires version 10.1 at a minimum.

.PARAMETER isUse
Internal parameter (for PSMP only).
Use of parameter requires version 10.1 at a minimum.

.PARAMETER Machine
The address of the remote machine to connect to.
Use of parameter requires version 10.1 at a minimum.

.PARAMETER sessionToken
Hashtable containing the session token returned from New-PASSession

.PARAMETER WebSession
WebRequestSession object returned from New-PASSession

.PARAMETER BaseURI
PVWA Web Address
Do not include "/PasswordVault/"

.PARAMETER PVWAAppName
The name of the CyberArk PVWA Virtual Directory.
Defaults to PasswordVault

.PARAMETER ExternalVersion
The External CyberArk Version, returned automatically from the New-PASSession function from version 9.7 onwards.
If the minimum version requirement of this function is not satisfied, execution will be halted.
Omitting a value for this parameter, or supplying a version of "0.0" will skip the version check.

.EXAMPLE
$token | Get-PASAccount -Keywords root -Safe Prod_Safe | Get-PASAccountPassword

Will return the password value of the account found by Get-PASAccount:

Password
--------
Ra^D0MwM666*&U

.EXAMPLE
$token | Get-PASAccount -Keywords root -Safe Prod_Safe | Get-PASAccountPassword -UseV10API

Will retrieve the password value of the account found by Get-PASAccount using the v10 API:

Password
--------
Ra^D0MwM666*&U

.EXAMPLE
$token | Get-PASAccount -Keywords root -Safe Prod_Safe | Get-PASAccountPassword -Reason "Incident Investigation"

Will retrieve the password value of the account found by Get-PASAccount using the v10 API, and specify a reason for access.

Password
--------
Ra^D0MwM666*&U

.INPUTS
All parameters can be piped by property name
Accepts pipeline input from other Get-PASAccount

.OUTPUTS
Outputs Object of Custom Type psPAS.CyberArk.Vault.Credential
SessionToken, WebSession, BaseURI are passed through and
contained in output object for inclusion in subsequent
pipeline operations.

Output format is defined via psPAS.Format.ps1xml.
To force all output to be shown, pipe to Select-Object *

.NOTES
Minimum API version is 9.7 for password retrieval only.
From version 10.1 onwards both passwords and ssh keys can be retrieved.

.LINK
#>

    [Alias("Get-PASAccountCredentials")]
    [CmdletBinding()]
    param(
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true
        )]
        [Alias("id")]
        [string]$AccountID,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [switch]$UseV10API,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [string]$Reason,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [string]$TicketingSystemName,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [string]$TicketId,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [int]$Version,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [ValidateSet("show", "copy", "connect")]
        [string]$ActionType,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [boolean]$isUse,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "v10"
        )]
        [switch]$Machine,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true
        )]
        [ValidateNotNullOrEmpty()]
        [hashtable]$sessionToken,

        [parameter(
            ValueFromPipelinebyPropertyName = $true
        )]
        [Microsoft.PowerShell.Commands.WebRequestSession]$WebSession,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true
        )]
        [string]$BaseURI,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $true
        )]
        [string]$PVWAAppName = "PasswordVault",

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $true
        )]
        [System.Version]$ExternalVersion = "0.0"

    )

    BEGIN {
        $MinimumVersion = [System.Version]"10.1"
    }#begin

    PROCESS {

        #Build Request
        if($($PSCmdlet.ParameterSetName) -eq "v10") {

            Assert-VersionRequirement -ExternalVersion $ExternalVersion -RequiredVersion $MinimumVersion

            #For Version 10.1+
            $Request = @{

                "URI"    = "$baseURI/$PVWAAppName/api/Accounts/$($AccountID |

                Get-EscapedString)/Password/Retrieve"


                "Method" = "POST"

                #Get all parameters that will be sent in the request
                "Body"   = $PSBoundParameters | Get-PASParameter -ParametersToRemove AccountID, UseV10API | ConvertTo-Json

            }

        }

        Else {

            #For Version 9.7+
            $Request = @{

                "URI"    = "$baseURI/$PVWAAppName/WebServices/PIMServices.svc/Accounts/$($AccountID |

                Get-EscapedString)/Credentials"


                "Method" = "GET"

            }

        }

        #Add default Request parameters
        $Request.Add("Headers", $sessionToken)
        $Request.Add("WebSession", $WebSession)

        #splat request to web service
        $result = Invoke-PASRestMethod @Request

        If($result) {

            If($result.GetType().Name -eq "Object[]") {

                $result = [System.Text.Encoding]::ASCII.GetString($result)

            }

            [PSCustomObject] @{"Password" = $result} |

            Add-ObjectDetail -typename psPAS.CyberArk.Vault.Credential -PropertyToAdd @{

                "sessionToken"    = $sessionToken
                "WebSession"      = $WebSession
                "BaseURI"         = $BaseURI
                "PVWAAppName"     = $PVWAAppName
                "ExternalVersion" = $ExternalVersion

            }

        }

    }#process

    END {}#end

}