Functions/Accounts/Add-PASAccount.ps1
|
function Add-PASAccount { <# .SYNOPSIS Adds a new privileged account to the Vault Uses either the API present from 10.4 onwards, or the version 9 API endpoint. .DESCRIPTION Adds a new privileged account to the Vault. Parameters are processed to create request object from passed parameters in the required format. .PARAMETER name The name�of the account. A version 10.4 onward specific parameter .PARAMETER secretType The type of password. A version 10.4 onward specific parameter .PARAMETER secret The password value A version 10.4 onward specific parameter .PARAMETER platformAccountProperties key-value pairs to associate with the account, as defined by the account platform. These properties are validated against the mandatory and optional properties of the specified platform's definition. A version 10.4 onward specific parameter .PARAMETER automaticManagementEnabled Whether CPM Password Management should be enabled A version 10.4 onward specific parameter .PARAMETER manualManagementReason A reason for disabling CPM Password Management A version 10.4 onward specific parameter .PARAMETER remoteMachines For supported platforms, a list of remote machines the account can connect to. A version 10.4 onward specific parameter .PARAMETER accessRestrictedToRemoteMachines Whether access is restricted to the defined remote machines. A version 10.4 onward specific parameter .PARAMETER SafeName The safe where the account will be created .PARAMETER PlatformID The CyberArk platform to assign to the account .PARAMETER Address The Address of the machine where the account will be used .PARAMETER AccountName The name of the account Relevant for CyberArk versions earlier than 10.4 .PARAMETER Password The password value as a secure string Relevant for CyberArk versions earlier than 10.4 .PARAMETER Username Username on the target machine .PARAMETER DisableAutoMgmt Whether or not automatic management wll be disabled for the account Relevant for CyberArk versions earlier than 10.4 .PARAMETER DisableAutoMgmtReason The reason why automatic management wll be disabled for the account Relevant for CyberArk versions earlier than 10.4 .PARAMETER GroupName A groupname with which the account will be associated Relevant for CyberArk versions earlier than 10.4 .PARAMETER GroupPlatformID Group platform to base created group ID on, if ID doesn't exist Relevant for CyberArk versions earlier than 10.4 .PARAMETER Port Port number over which the account will be used Relevant for CyberArk versions earlier than 10.4 .PARAMETER ExtraPass1Name Logon account name Relevant for CyberArk versions earlier than 10.4 .PARAMETER ExtraPass1Folder Folder where logon account is stored Relevant for CyberArk versions earlier than 10.4 .PARAMETER ExtraPass1Safe Safe where logon account is stored Relevant for CyberArk versions earlier than 10.4 .PARAMETER ExtraPass3Name Reconcile account name Relevant for CyberArk versions earlier than 10.4 .PARAMETER ExtraPass3Folder Folder where reconcile account is stored Relevant for CyberArk versions earlier than 10.4 .PARAMETER ExtraPass3Safe Safe where reconcile account is stored Relevant for CyberArk versions earlier than 10.4 .PARAMETER DynamicProperties Hashtable of name=value pairs Relevant for CyberArk versions earlier than 10.4 .EXAMPLE Add-PASAccount -address ThisServer -userName ThisUser -platformID UNIXSSH -SafeName UNIXSafe -automaticManagementEnabled $false Using the version 10 API, adds an account which is disabled for automatic password management .EXAMPLE Add-PASAccount -safe Prod_Access -PlatformID WINDOMAIN -Address domain.com -Password $secureString -username domainUser Using the "version 9" API, adds account domain.com\domainuser to the Prod_Access Safe using the WINDOMAIN platform. The contents of $secureString will be set as the password value. .INPUTS All parameters can be piped by property name .OUTPUTS None for v9 v10.4 outputs the details of the created account. .LINK https://pspas.pspete.dev/commands/Add-PASAccount #> [CmdletBinding()] param( [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [string]$name, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [string]$address, [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [string]$userName, [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [Alias("PolicyID")] [string]$platformID, [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [ValidateNotNullOrEmpty()] [Alias("safe")] [string]$SafeName, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [ValidateSet("Password", "Key")] [string]$secretType, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [securestring]$secret, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [hashtable]$platformAccountProperties, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [boolean]$automaticManagementEnabled, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [string]$manualManagementReason, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [string]$remoteMachines, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V10" )] [boolean]$accessRestrictedToRemoteMachines, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [string]$accountName, [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [securestring]$password, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [boolean]$disableAutoMgmt, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [string]$disableAutoMgmtReason, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [string]$groupName, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [string]$groupPlatformID, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [int]$Port, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [ValidateNotNullOrEmpty()] [string]$ExtraPass1Name, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [string]$ExtraPass1Folder, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [ValidateNotNullOrEmpty()] [string]$ExtraPass1Safe, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [ValidateNotNullOrEmpty()] [string]$ExtraPass3Name, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [string]$ExtraPass3Folder, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [ValidateNotNullOrEmpty()] [string]$ExtraPass3Safe, [parameter( Mandatory = $false, ValueFromPipelinebyPropertyName = $true, ParameterSetName = "V9" )] [hashtable]$DynamicProperties ) BEGIN { $MinimumVersion = [System.Version]"10.4" #The (version 9 API) Add Account JSON object requires specific formatting. #Different parameters are contained within the JSON at different depths. #Programmatic processing is required to format the JSON as required. #V9 baseparameters are contained in JSON object at the same depth $baseParameters = @("Safe", "PlatformID", "Address", "AccountName", "Password", "Username", "DisableAutoMgmt", "DisableAutoMgmtReason", "GroupName", "GroupPlatformID") #V10 parameters are nested under JSON object properties $remoteMachine = @("remoteMachines", "accessRestrictedToRemoteMachines") $SecretMgmt = @("automaticManagementEnabled", "manualManagementReason") }#begin PROCESS { #Get all parameters that will be sent in the request $boundParameters = $PSBoundParameters | Get-PASParameter #declare empty array to hold keys to remove from bound parameters [array]$keysToRemove = @() if ($PSCmdlet.ParameterSetName -eq "V10") { Assert-VersionRequirement -ExternalVersion $Script:ExternalVersion -RequiredVersion $MinimumVersion #Create URL for Request $URI = "$Script:BaseURI/api/Accounts" #deal with "secret" SecureString If ($PSBoundParameters.ContainsKey("secret")) { #Include decoded password in request $boundParameters["secret"] = $(ConvertTo-InsecureString -SecureString $secret) } $remoteMachinesAccess = @{ } $boundParameters.keys | Where-Object { $remoteMachine -contains $_ } | ForEach-Object { #add key=value to hashtable $remoteMachinesAccess[$_] = $boundParameters[$_] } $secretManagement = @{ } $boundParameters.keys | Where-Object { $SecretMgmt -contains $_ } | ForEach-Object { #add key=value to hashtable $secretManagement[$_] = $boundParameters[$_] } $boundParameters["remoteMachinesAccess"] = $remoteMachinesAccess $boundParameters["secretManagement"] = $secretManagement $body = $boundParameters | Get-PASParameter -ParametersToRemove @($remoteMachine + $SecretMgmt) | ConvertTo-Json -depth 4 } if ($PSCmdlet.ParameterSetName -eq "V9") { #Create URL for Request $URI = "$Script:BaseURI/WebServices/PIMServices.svc/Account" #deal with Password SecureString If ($PSBoundParameters.ContainsKey("password")) { #Include decoded password in request $boundParameters["password"] = $(ConvertTo-InsecureString -SecureString $password) } #Process for required formatting - fix V10 specific parameter names $boundParameters.remove("SafeName") $boundParameters.remove("userName") $boundParameters["safe"] = $SafeName $boundParameters["username"] = $userName #declare empty hashtable to hold "non-base" parameters $properties = @{ } #Get "non-base" parameters $boundParameters.keys | Where-Object { $baseParameters -notcontains $_ } | ForEach-Object { #For all "non-base" parameters except "DynamicProperties" if ($_ -ne "DynamicProperties") { #Add key/Value to "properties" hashtable $properties[$_] = $boundParameters[$_] } Else { #for DynamicProperties key=value pairs #Enumerate DynamicProperties object $boundParameters[$_].getenumerator() | ForEach-Object { #add key=value to "properties" hashtable $properties[$_.name] = $_.value } } #add the "non-base" parameter key to array $keysToRemove = $keysToRemove + $_ } #Add "non-base" parameter hashtable as value of "properties" on boundparameters object $boundParameters["properties"] = @($properties.getenumerator() | ForEach-Object { $_ }) #Create body of request $body = @{ #account node does not contain non-base parameters "account" = $boundParameters | Get-PASParameter -ParametersToRemove $keysToRemove #ensure nodes at all required depths are included in the JSON object } | ConvertTo-Json -Depth 4 } #send request to PAS web service $result = Invoke-PASRestMethod -Uri $URI -Method POST -Body $Body -WebSession $Script:WebSession if ($PSCmdlet.ParameterSetName -eq "V10") { if ($result) { #Return Results $result | Add-ObjectDetail -typename "psPAS.CyberArk.Vault.Account.V10" } } }#process END { }#end } |