Functions/Accounts/Invoke-PASCPMOperation.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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
function Invoke-PASCPMOperation {
    <#
.SYNOPSIS
Marks accounts for CPM Verify, Change or Reconcile operations

.DESCRIPTION
Accounts Can be flagged for immediate verification, change or reconcile
Flags a managed account credentials for an immediate CPM password verification.
CPM Change Options:
Flags a managed account credentials for an immediate CPM password change.
    - The "Initiate CPM password management operations" permission is required.

Sets a password to use for an account's next CPM change.
    - The "Initiate CPM password management operations" & "Specify next password value" permission is required.

Updates the account's password only in the Vault (without affecting the credentials on the target device).
    - The "Update password value" permission is required.

Verify & Reconcile both require "Initiate CPM password management operations"

.PARAMETER AccountID
The unique ID of the account.

.PARAMETER VerifyTask
Initiates a verify task

.PARAMETER ChangeTask
Initiates a change task

.PARAMETER ReconcileTask
Initiates a reconcile task

.PARAMETER ChangeImmediately
Whether or not the password will be changed immediately in the Vault.
Only relevant when specifying a password value for the next CPM change.

.PARAMETER NewCredentials
Secure String value of the new account password that will be allocated to the account in the Vault.
Only relevant when specifying a password value for the next CPM change, or updating the password only in the vault.

.PARAMETER ChangeEntireGroup
Boolean value, dictating if all accounts that belong to the same group should have their passwords changed.
This is only relevant for accounts that belong to an account group.
Parameter will be ignored if account does not belong to a group.
Applicable to immediate change via CPM, and password change in the vault only.

.PARAMETER ImmediateChangeByCPM
Yes/No value, dictating if the account will be scheduled for immediate change.
Specify Yes to initiate a password change by CPM - Relevant for Classic API only.

.PARAMETER ChangeCredsForGroup
Yes/No value, dictating if all accounts that belong to the same group should
have their passwords changed.
This is only relevant for accounts that belong to an account group.
Parameter will be ignored if account does not belong to a group.
Relevant for Classic API only.

.PARAMETER UseClassicAPI
Specify to force verification via Classic API.

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -VerifyTask

Marks an account for verification

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -VerifyTask -UseClassicAPI

Marks an account for verification using the Classic API

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -ImmediateChangeByCPM Yes

Marks an account for immediate change using the Classic API

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -ChangeTask

Marks an account for immediate change

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -ChangeImmediately $true -NewCredentials $SecureString

Marks an account for immediate change to the specified password value

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -NewCredentials $SecureString

Changes the password for the account in the Vault

.EXAMPLE
Invoke-PASCPMOperation -AccountID $ID -ReconcileTask

Marks an account for immediate reconcile

#>


    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', 'ChangeCredsForGroup', Justification = "Parameter does not hold password")]
    [CmdletBinding(SupportsShouldProcess)] # DefaultParameterSetName = "VerifyStandard"
    param(
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true
        )]
        [ValidateNotNullOrEmpty()]
        [Alias("id")]
        [string]$AccountID,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "VerifyClassic"
        )]
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "Verify"
        )]
        [switch]$VerifyTask,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "Password/Update"
        )]
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "SetNextPassword"
        )]
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "Change"
        )]
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "ChangeClassic"
        )]
        [switch]$ChangeTask,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "Reconcile"
        )]
        [switch]$ReconcileTask,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "SetNextPassword"
        )]
        [boolean]$ChangeImmediately,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "SetNextPassword"
        )]
        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "Password/Update"
        )]
        [securestring]$NewCredentials,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "Change"
        )]
        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "Password/Update"
        )]
        [boolean]$ChangeEntireGroup,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "ChangeClassic"
        )]
        [ValidateSet('Yes', 'No')]
        [string]$ImmediateChangeByCPM,

        [parameter(
            Mandatory = $false,
            ValueFromPipelinebyPropertyName = $false,
            ParameterSetName = "ChangeClassic"
        )]
        [ValidateSet('Yes', 'No')]
        [string]$ChangeCredsForGroup,

        [parameter(
            Mandatory = $true,
            ValueFromPipelinebyPropertyName = $true,
            ParameterSetName = "VerifyClassic"
        )]
        [switch]$UseClassicAPI
    )

    Begin {

        #Create hashtable for splatting
        $ThisRequest = @{ }
        $ThisRequest["WebSession"] = $Script:WebSession
        $ThisRequest["Method"] = "PUT"
        #Version Requirements
        $MinimumVersion = [System.Version]"9.10"
        $RequiredVersion = [System.Version]"10.1"

    }#Begin

    Process {

        #Get parameters to include in request body
        $boundParameters = $PSBoundParameters |
        Get-PASParameter -ParametersToRemove ImmediateChangeByCPM, AccountID, VerifyTask, ChangeTask, ReconcileTask

        switch ($PSCmdlet.ParameterSetName) {

            "ChangeClassic" {

                #Classic API CPM Change URI
                $ThisRequest["URI"] = "$Script:BaseURI/WebServices/PIMServices.svc/Accounts/$AccountID/ChangeCredentials"

                #add ImmediateChangeByCPM to header as key=value pair
                $ThisRequest["WebSession"].Headers["ImmediateChangeByCPM"] = $ImmediateChangeByCPM

                #create request body
                $ThisRequest["Body"] = $boundParameters | ConvertTo-Json

            }

            "VerifyClassic" {

                #Classic API CPM Verify URI
                $ThisRequest["URI"] = "$Script:BaseURI/WebServices/PIMServices.svc/Accounts/$AccountID/VerifyCredentials"

                #Empty Body
                $ThisRequest["Body"] = @{ } | ConvertTo-Json

            }

            default {

                #Not using classic API
                #At least version 9.10 required to verify/change/reconcile
                Assert-VersionRequirement -ExternalVersion $Script:ExternalVersion -RequiredVersion $MinimumVersion

                #Use ParameterSet name for required URI
                $ThisRequest["URI"] = "$Script:BaseURI/API/Accounts/$AccountID/$($PSCmdlet.ParameterSetName)"

                #verify/change/reconcile method
                $ThisRequest["Method"] = "POST"

                #deal with NewCredentials SecureString
                If ($PSBoundParameters.ContainsKey("NewCredentials")) {

                    #Specifying next password value, or changing in the vault requires 10.1 or above
                    Assert-VersionRequirement -ExternalVersion $Script:ExternalVersion -RequiredVersion $RequiredVersion

                    #Include decoded password in request
                    $boundParameters["NewCredentials"] = $(ConvertTo-InsecureString -SecureString $NewCredentials)

                }

                #create request body
                $ThisRequest["Body"] = $boundParameters | ConvertTo-Json

            }

        }

        if ($PSCmdlet.ShouldProcess($AccountID, "Initiate CPM $($PSBoundParameters.Keys | Where-Object{$_ -like '*Task'})")) {

            #Send the request to the web service
            Invoke-PASRestMethod @ThisRequest

        }

        If ($ThisRequest["WebSession"].Headers.ContainsKey("ImmediateChangeByCPM")) {

            #Ensure ImmediateChangeByCPM is removed from WebSession Header
            $ThisRequest["WebSession"].Headers.Remove("ImmediateChangeByCPM") | Out-Null

        }

    }#Process

    End { }#End

}