Functions/Accounts/Get-PASAccountPassword.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
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 UseClassicAPI
Specify the UseClassicAPI to force usage the Classic (v9) API endpoint.

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

.EXAMPLE
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
Get-PASAccount -Keywords root -Safe Prod_Safe | Get-PASAccountPassword -UseClassicAPI

Will retrieve the password value of the account found by Get-PASAccount using the classic (v9) API:

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

.EXAMPLE
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
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
https://pspas.pspete.dev/commands/Get-PASAccountPassword
#>

    [CmdletBinding(DefaultParameterSetName = "10.1")]
    param(
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "ClassicAPI"
        )]
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "10.1"
        )]
        [Alias("id")]
        [string]$AccountID,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "ClassicAPI"
        )]
        [switch]$UseClassicAPI,

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

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "10.1"
        )]
        [string]$TicketingSystem,

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

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

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

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

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

    BEGIN {

    }#begin

    PROCESS {

        #Build Request
        switch ($PSCmdlet.ParameterSetName) {

            "10.1" {

                Assert-VersionRequirement -RequiredVersion $PSCmdlet.ParameterSetName

                #For Version 10.1+
                $Request = @{

                    "URI"    = "$Script:BaseURI/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 | ConvertTo-Json

                }

                break

            }

            "ClassicAPI" {

                #For Version 9.7+
                $Request = @{

                    "URI"    = "$Script:BaseURI/WebServices/PIMServices.svc/Accounts/$($AccountID | Get-EscapedString)/Credentials"

                    "Method" = "GET"

                }

                break

            }

        }

        #Add default Request parameters
        $Request.Add("WebSession", $Script:WebSession)

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

        If ($null -ne $result) {

            switch ($PSCmdlet.ParameterSetName) {

                "ClassicAPI" {

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

                    break

                }

                "10.1" {

                    #Unescape returned string and remove enclosing quotes.
                    $result = $([System.Text.RegularExpressions.Regex]::Unescape($result) -replace '^"|"$', '')

                    break

                }

            }

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

            Add-ObjectDetail -typename psPAS.CyberArk.Vault.Credential

        }

    }#process

    END { }#end

}