psPAS: PowerShell Module for the CyberArk API

Use PowerShell to manage CyberArk via the Web Services REST API.

Contains all published methods of the API up to CyberArk v11.7.

Docs: https://pspas.pspete.dev

Module Status

Master Branch	Latest Build	CodeFactor	Coverage	PowerShell Gallery	License

• Usage
  • Authenticate
  • Basic Operations
  • Advanced Examples
  • Sample Scripts
• psPAS Functions
• Installation
  • Prerequisites
  • Install Options
  • Verification
• Sponsorship
• Changelog
• Author
• License
• Contributing
• Acknowledgements

Usage

Authenticate

It all starts with a Logon

New-PASSession is used to send a logon request to the CyberArk API.

On successful authentication psPAS uses the data which was provided for the request & also returned from the API for all subsequent operations.

CyberArk Authentication

• Use a PowerShell credential object containing a valid vault username and password.

$cred = Get-Credential

PowerShell credential request
Enter your credentials.
User: safeadmin
Password for user safeadmin: **********


New-PASSession -Credential $cred -BaseURI https://pvwa.somedomain.com

LDAP Authentication

• Specify LDAP credentials allowed to authenticate to the vault.

$cred = Get-Credential

PowerShell credential request
Enter your credentials.
User: xApprover_1
Password for user xApprover_1: **********


New-PASSession -Credential $cred -BaseURI https://pvwa.somedomain.com -type LDAP

Get-PASLoggedOnUser

UserName    Source UserTypeName AgentUser Expired Disabled Suspended
--------    ------ ------------ --------- ------- -------- ---------
xApprover_1 LDAP   EPVUser      False     False   False    False

RADIUS Authentication

Challenge Mode

$cred = Get-Credential

PowerShell credential request
Enter your credentials.
User: DuoUser
Password for user DuoUser: **********


New-PASSession -Credential $cred -BaseURI https://pvwa.somedomain.com -type RADIUS -OTP 123456

Get-PASLoggedOnUser

UserName Source UserTypeName AgentUser Expired Disabled Suspended
-------- ------ ------------ --------- ------- -------- ---------
DuoUser  LDAP   EPVUser      False     False   False    False

Append Mode

• Some 2FA solutions allow a One Time Passcode to be sent with the password.

  • If an OTP is provided, it is sent to the API with the password, separated by a delimiter: "$Password,$OTP"

$cred = Get-Credential

PowerShell credential request
Enter your credentials.
User: DuoUser
Password for user DuoUser: **********


New-PASSession -Credential $cred -BaseURI https://pvwa.somedomain.com -type RADIUS -OTP 738458 -OTPMode Append

Get-PASLoggedOnUser

UserName Source UserTypeName AgentUser Expired Disabled Suspended
-------- ------ ------------ --------- ------- -------- ---------
DuoUser  LDAP   EPVUser      False     False   False    False

Shared Authentication with Client Certificate

• If IIS is configured to require client certificates, psPAS will use any provided certificate details for the duration of the session.

$Cert = "0E199489C57E666115666D6E9990C2ACABDB6EDB"
New-PASSession -UseSharedAuthentication -BaseURI https://pvwa.somedomain.com -CertificateThumbprint $Cert

Basic Operations

Search

Safes

• Get information relating to Safes you have access to:

Find-PASSafe -search 3_TestSafe_028_XYJ

SafeUrlId          SafeName           Description                  Location
---------          --------           -----------                  --------
3_TestSafe_028_XYJ 3_TestSafe_028_XYJ TestSafe: 3_TestSafe_028_XYJ \

Get-PASSafe -SafeName 3_TestSafe_028_XYJ

SafeName           ManagingCPM     NumberOfDaysRetention NumberOfVersionsRetention Description
--------           -----------     --------------------- ------------------------- -----------
3_TestSafe_028_XYJ PasswordManager                       3                         TestSafe: 3_TestSafe_028_XYJ

Safe Members

• Find Safe Members:

Get-PASSafeMember -SafeName 3_TestSafe_028_XYJ -MemberName ACC-G-3_TestSafe_028_XYJ-Usr

UserName                     SafeName           Permissions
--------                     --------           -----------
ACC-G-3_TestSafe_028_XYJ-Usr 3_TestSafe_028_XYJ @{Add=True; AddRenameFolder=True; BackupSafe=True...}

Users

• Query for Vault Users:

Get-PASUser -Search xap

ID  UserName    Source UserType ComponentUser Location
--  --------    ------ -------- ------------- --------
657 xApprover_A LDAP   EPVUser  False         \psPETE\Users
658 xApprover_1 LDAP   EPVUser  False         \psPETE\Users
659 xApprover_B LDAP   EPVUser  False         \psPETE\Users
660 xApprover_2 LDAP   EPVUser  False         \psPETE\Users
661 xApprover_C LDAP   EPVUser  False         \psPETE\Users
662 xApprover_3 LDAP   EPVUser  False         \psPETE\Users

Accounts

• Return Account data:

Get-PASAccount -filter "SafeName eq 3_TestSafe_028_XYJ" -search sbwudlov

AccountID                 : 286_4
Safe                      : 3_TestSafe_028_XYJ
address                   : SOMEDOMAIN.COM
userName                  : sbwudlov
name                      : Operating System-Z_WINDOMAIN_OFF-SOMEDOMAIN.COM-sbwudlov
platformId                : Z_WINDOMAIN_OFF
secretType                : password
platformAccountProperties : @{LogonDomain=SOMEDOMAIN}
secretManagement          : @{automaticManagementEnabled=True; lastModifiedTime=1559864222}
createdTime               : 06/06/2019 23:37:02

Classic API

• There is a limitation of only returning details of the first found account when using the Classic API.
  • The keywords & safe parameters of Get-PASAccount force use of the Classic API:

Get-PASAccount -Safe 3_TestSafe_028_XYJ
WARNING: 2 matching accounts found. Only the first result will be returned

AccountID          : 286_3
Safe               : 3_TestSafe_028_XYJ
Folder             : Root
Name               : Operating System-Z_WINDOMAIN_OFF-SOMEDOMAIN.COM-kmgrsebf
UserName           : kmgrsebf
PlatformID         : Z_WINDOMAIN_OFF
DeviceType         : Operating System
Address            : SOMEDOMAIN.COM
InternalProperties : @{CreationMethod=PVWA}

• More results can be returned by specifying alternative parameters and avoiding the Classic API:

PS>Get-PASAccount -filter "SafeName eq 3_TestSafe_028_XYJ"

AccountID                 : 286_3
Safe                      : 3_TestSafe_028_XYJ
address                   : SOMEDOMAIN.COM
userName                  : kmgrsebf
name                      : Operating System-Z_WINDOMAIN_OFF-SOMEDOMAIN.COM-kmgrsebf
platformId                : Z_WINDOMAIN_OFF
secretType                : password
platformAccountProperties : @{LogonDomain=SOMEDOMAIN}
secretManagement          : @{automaticManagementEnabled=True; lastModifiedTime=1559864221}
createdTime               : 06/06/2019 23:37:01

AccountID                 : 286_4
Safe                      : 3_TestSafe_028_XYJ
address                   : SOMEDOMAIN.COM
userName                  : sbwudlov
name                      : Operating System-Z_WINDOMAIN_OFF-SOMEDOMAIN.COM-sbwudlov
platformId                : Z_WINDOMAIN_OFF
secretType                : password
platformAccountProperties : @{LogonDomain=SOMEDOMAIN}
secretManagement          : @{automaticManagementEnabled=True; lastModifiedTime=1559864222}
createdTime               : 06/06/2019 23:37:02

Administration

Add An Account

• Add an account to manage:

#Convert Password to SecureString
$Password = ConvertTo-SecureString -String "Secret1337$" -AsPlainText -Force

#Additional account details
$platformAccountProperties = @{
  "LOGONDOMAIN"="domain.com"
  "Notes"="Demo Account. Owner:psPete"
  "Classification"="1F"
}

#Add Account
Add-PASAccount -secretType Password -secret $Password -SafeName "YourSafe" -PlatformID "YourPlatform" `
-Address "domain" -Username SomeUsername -platformAccountProperties $platformAccountProperties

Create Safes

• Simple safe creation:

Add-PASSafe -SafeName NewSafe -Description "New Safe" -ManagingCPM PasswordManager -NumberOfVersionsRetention 10

SafeName ManagingCPM     NumberOfDaysRetention NumberOfVersionsRetention Description
-------- -----------     --------------------- ------------------------- -----------
NewSafe  PasswordManager                       10                        New Safe

Add Safe Members

• Consistent safe membership:

Add-PASSafeMember -SafeName NewSafe -MemberName NewMember -UseAccounts $false -ListAccounts $true `
-RetrieveAccounts $false -ViewAuditLog $true -ViewSafeMembers $true

MemberName SearchIn SafeName Permissions
---------- -------- -------- -----------
NewMember  vault    NewSafe  @{Add=True; AddRenameFolder=True; BackupSafe=True...}

Update Accounts

• Update values for individual account properties:

Set-PASAccount -AccountID 286_4 -op replace -path /address -value NEWDOMAIN.COM

AccountID                 : 286_4
Safe                      : 3_TestSafe_028_XYJ
address                   : NEWDOMAIN.COM
userName                  : sbwudlov
name                      : Operating System-Z_WINDOMAIN_OFF-SOMEDOMAIN.COM-sbwudlov
platformId                : Z_WINDOMAIN_OFF
secretType                : password
platformAccountProperties : @{LogonDomain=SOMEDOMAIN}
secretManagement          : @{automaticManagementEnabled=True; lastModifiedTime=1559864222}
createdTime               : 06/06/2019 23:37:02

Set-PASAccount -AccountID 286_4 -op replace -path /platformAccountProperties/LogonDomain -value NEWDOMAIN

AccountID                 : 286_4
Safe                      : 3_TestSafe_028_XYJ
address                   : NEWDOMAIN.COM
userName                  : sbwudlov
name                      : Operating System-Z_WINDOMAIN_OFF-SOMEDOMAIN.COM-sbwudlov
platformId                : Z_WINDOMAIN_OFF
secretType                : password
platformAccountProperties : @{LogonDomain=NEWDOMAIN}
secretManagement          : @{automaticManagementEnabled=True; lastModifiedTime=1559864222}
createdTime               : 06/06/2019 23:37:02

CPM Operations

Verify

• Verify passwords

# immediate verification
Invoke-PASCPMOperation -AccountID $ID -VerifyTask

Change

• Change passwords for accounts or account groups

# immediate change
Invoke-PASCPMOperation -AccountID $ID -ChangeTask

# immediate change to a specific password value
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -ChangeImmediately $true -NewCredentials $SecureString

# change password in the Vault only
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -NewCredentials $SecureString

# change password for account group
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -ChangeEntireGroup $true

# change password for account group to a specific password value
Invoke-PASCPMOperation -AccountID $ID -ChangeTask -ChangeEntireGroup $true -NewCredentials $SecureString

Reconcile

• Reconcile passwords

# immediate reconcile
Invoke-PASCPMOperation -AccountID $ID -ReconcileTask

Import a Connection Component

• Import Custom Connection Components:

Import-PASConnectionComponent -ImportFile C:\Temp\ConnectionComponent.zip

Platforms

• Import & Export of CPM Platforms:

#Import a Platform
Import-PASPlatform -ImportFile C:\Temp\Platform.zip

#Export a Platform
Export-PASPlatform -PlatformID "Some-SSH-Platform" -Path C:\Temp

Pipeline Operations

• Work with the PowerShell pipeline:

#Find directory groups assigned to safes
Get-PASSafe -query JXW | Get-PASSafeMember |
Where-Object{ Get-PASGroup -search $_.UserName -filter 'groupType eq Directory' }

UserName                     SafeName           Permissions
--------                     --------           -----------
ACC-G-1_TestSafe_049_JXW-Usr 1_TestSafe_049_JXW @{Add=True; AddRenameFolder=True; BackupSafe=True...}
ACC-G-1_TestSafe_049_JXW-Adm 1_TestSafe_049_JXW @{Add=True; AddRenameFolder=True; BackupSafe=True...}
ACC-G-2_TestSafe_049_JXW-Usr 2_TestSafe_049_JXW @{Add=True; AddRenameFolder=True; BackupSafe=True...}
ACC-G-2_TestSafe_049_JXW-Adm 2_TestSafe_049_JXW @{Add=True; AddRenameFolder=True; BackupSafe=True...}
ACC-G-3_TestSafe_049_JXW-Usr 3_TestSafe_049_JXW @{Add=True; AddRenameFolder=True; BackupSafe=True...}
ACC-G-3_TestSafe_049_JXW-Adm 3_TestSafe_049_JXW @{Add=True; AddRenameFolder=True; BackupSafe=True...}

• Multiple psPAS commands can be used together, along with standard PowerShell CmdLets:

#Add all "admin" users in the root location to the PVWAMonitor group
Get-PASUser -UserType EPVUser -Search Admin | Where-Object{ $_.location -eq "\" } |
Add-PASGroupMember -GroupName PVWAMonitor

#Find an account, then find the members of the account's safe.
Get-PASAccount -id 330_5 | Get-PASSafe | Get-PASSafeMember

UserName             SafeName    Permissions
--------             --------    ---------- -
Master               ApproveTest @{Add=True; AddRenameFolder=True; BackupSafe=True...}
Batch                ApproveTest @{Add=True; AddRenameFolder=True; BackupSafe=True...}
Backup Users         ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=True...}
Auditors             ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=False...}
Operators            ApproveTest @{Add=True; AddRenameFolder=True; BackupSafe=True...}
DR Users             ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=True...}
Notification Engines ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=False...}
PVWAGWAccounts       ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=False...}
PasswordManager      ApproveTest @{Add=False; AddRenameFolder=True; BackupSafe=False...}
SafeAdmin            ApproveTest @{Add=True; AddRenameFolder=True; BackupSafe=True...}
SafeAdmin1           ApproveTest @{Add=True; AddRenameFolder=True; BackupSafe=True...}
zApprover_1          ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=False...}
xReq                 ApproveTest @{Add=False; AddRenameFolder=False; BackupSafe=False...}

Advanced Examples

Bulk Operations

The standard features of PowerShell which allow creation of and iterations through collections of objects, can be used to perform bulk operations:

Example 1 - On-board Multiple Accounts

$Accounts = Import-Csv -Path C:\Temp\Accounts.csv

New-PASSession -Credential $creds -BaseURI https://your.pvwa.url

foreach($Account in $Accounts){

    $Password = ConvertTo-SecureString -String $Account.Password -AsPlainText -Force

    Add-PASAccount -secretType Password `
    -secret $Password `
    -platformAccountProperties @{"LOGONDOMAIN"=$Account.LogonDomain} `
    -SafeName $Account.SafeName `
    -PlatformID $Account.PlatformID `
    -Address $Account.Address `
    -Username $Account.Username

}

Close-PASSession

Example 2 - Delete Multiple Safes

#Specify Vault Logon Credentials
$LogonCredential = Get-Credential

#Logon
New-PASSession -Credential $LogonCredential -BaseURI https://your.pvwa.url

$Safes = Get-PASSafe -query TestSafe

#Delete Safes
foreach ($Safe in $Safes){

  Remove-PASSafe -SafeName $Safe -WhatIf

}

#Logoff
Close-PASSession

Example 3 - Move a List of Users to a New Location

#Vault Logon Credentials
$LogonCredential = Get-Credential

#Logon
New-PASSession -Credential $LogonCredential -BaseURI https://your.pvwa.url

#get list of users
$users = Get-Content .\userlist.txt

#move users
$users | foreach{

  Set-PASUser -UserName $_ -Location "\New\Location\Path" -WhatIf

}

#Logoff
Close-PASSession

Safe Permissions

• Define Safe Roles and assign to safe members:

$Role1 = [PSCustomObject]@{
  UseAccounts                            = $true
  ListAccounts                           = $true
  ViewAuditLog                           = $false
  ViewSafeMembers                        = $false
}

$Role2 = [PSCustomObject]@{
  UseAccounts                            = $false
  ListAccounts                           = $true
  RetrieveAccounts                       = $false
  AddAccounts                            = $true
  UpdateAccountContent                   = $true
  UpdateAccountProperties                = $true
  InitiateCPMAccountManagementOperations = $true
  SpecifyNextAccountContent              = $false
  RenameAccounts                         = $true
  DeleteAccounts                         = $true
  UnlockAccounts                         = $true
  ManageSafe                             = $true
  ManageSafeMembers                      = $true
  BackupSafe                             = $false
  ViewAuditLog                           = $true
  ViewSafeMembers                        = $true
  RequestsAuthorizationLevel             = $false
  AccessWithoutConfirmation              = $true
  CreateFolders                          = $true
  DeleteFolders                          = $true
  MoveAccountsAndFolders                 = $true
}

$Role1 | Add-PASSafeMember -SafeName NewSafe -MemberName User23 -SearchIn Vault

MemberName SearchIn SafeName Permissions
---------- -------- -------- -----------
User23     Vault    NewSafe  @{Add=False; AddRenameFolder=False; BackupSafe=False...}

$Role2 | Add-PASSafeMember -SafeName NewSafe -MemberName SafeAdmin1 -SearchIn Vault

MemberName SearchIn SafeName Permissions
---------- -------- -------- -----------
SafeAdmin1 Vault    NewSafe  @{Add=True; AddRenameFolder=True; BackupSafe=True...}

PSM Sessions

Terminate all Active PSM Sessions on a PSM Server

#Find Active Sessions for a PSM Server IP
#Terminate the Sessions
Get-PASPSMSession | Where-Object{
  ($_.RawProperties.ProviderID -eq $(Get-PASComponentDetail -ComponentID SessionManagement |
    Where-Object{$_.ComponentIP -eq "192.168.60.20"} |
    Select -ExpandProperty ComponentUserName))
  -and ($_.IsLive) -and ($_.CanTerminate)} | Stop-PASPSMSession

Updating Multiple Properties of an Account

• Multiple updates can be performed in a single request:

[array]$operations += @{"op"="remove";"path"="/platformAccountProperties/LogonDomain"}
[array]$operations += @{"op"="replace";"path"="/name";"value"="SomeNewName"}
[array]$operations += @{"op"="replace";"path"="/address";"value"="domain.co.uk"}

Set-PASAccount -AccountID 286_4 -operations $operations

AccountID        : 286_4
Safe             : 3_TestSafe_028_XYJ
address          : domain.co.uk
userName         : sbwudlov
name             : SomeNewName
platformId       : Z_WINDOMAIN_OFF
secretType       : password
secretManagement : @{automaticManagementEnabled=True; lastModifiedTime=1559864222}
createdTime      : 06/06/2019 23:37:02

Using Methods

Methods present on objects returned from psPAS functions can be leveraged to get the data you need with ease.

• The psPAS.CyberArk.Vault.Safe object returned by Get-PASSafe has a ScriptMethod (SafeMembers()), which will run a query for the members of the safe:

#List all safes where AppUser is not a member
Get-PASSafe | Where-Object{ ($_.safemembers() | Select-Object -ExpandProperty UserName) -notcontains "AppUser"}

• Retrieved credentials can be immediately converted into Secure Strings:

(Get-PASAccount -id 330_5 | Get-PASAccountPassword).ToSecureString()

API Sessions

• If actions are required to be performed under the context of different user accounts, it is possible to work with different authenticated sessions:

#Start first session
$VaultAdmin = Get-Credential

PowerShell credential request
Enter your credentials.
User: VaultAdmin
Password for user VaultAdmin: **********


New-PASSession -Credential $VaultAdmin -BaseURI https://pvwa.somedomain.com

Get-PASLoggedOnUser

UserName   Source   UserTypeName AgentUser Expired Disabled Suspended
--------   ------   ------------ --------- ------- -------- ---------
VaultAdmin Internal EPVUser      False     False   False    False

#Save first session data
$FirstSession = Get-PASSession

#Start second session
$SafeAdmin = Get-Credential

PowerShell credential request
Enter your credentials.
User: SafeAdmin
Password for user SafeAdmin: **********


New-PASSession -Credential $SafeAdmin -BaseURI https://pvwa.somedomain.com

Get-PASLoggedOnUser

UserName  Source   UserTypeName AgentUser Expired Disabled Suspended
--------  ------   ------------ --------- ------- -------- ---------
SafeAdmin Internal EPVUser      False     False   False    False

#Save second session data
$SecondSession = Get-PASSession

#Switch back to first session
Use-PASSession -Session $FirstSession

Get-PASLoggedOnUser

UserName   Source   UserTypeName AgentUser Expired Disabled Suspended
--------   ------   ------------ --------- ------- -------- ---------
VaultAdmin Internal EPVUser      False     False   False    False

#End first session
Close-PASSession

#Switch to second session
Use-PASSession -Session $SecondSession

Get-PASLoggedOnUser

UserName  Source   UserTypeName AgentUser Expired Disabled Suspended
--------  ------   ------------ --------- ------- -------- ---------
SafeAdmin Internal EPVUser      False     False   False    False

#End second session
Close-PASSession

Sample Scripts

A selection of psPAS sample scripts can be found in the psPAS-Examples repository.

psPAS Functions

Your version of CyberArk determines which functions of psPAS will be supported.

Check the below table to determine what is available for you to use.

The CyberArk Version listed is the minimum required to use the function.

The module will attempt to confirm that your version of CyberArk meets the minimum

version requirement (if you are using version 9.7+, and the function being invoked

requires version 9.8+).

Check the output of Get-Help for the psPAS functions for further details of available parameters and version requirements.

Click the below dropdown to view the current lis of psPAS functions and their minimum version requirements:

Installation

Prerequisites

• Powershell v5 (minimum), or PowerShell Core
• CyberArk PAS REST API/Web Service
• A user with which to authenticate, with appropriate Vault/Safe permissions.

Install Options

Use one of the following methods:

Option 1: Install from PowerShell Gallery

PowerShell 5.0 or above must be used

This is the simplest & preferred method for installation of the module.

To install the module from the PowerShell Gallery, from a PowerShell prompt, run:

Install-Module -Name psPAS -Scope CurrentUser

Option 2: Manual Install

You can manually copy the module files to one of your powershell module folders.

Find your PowerShell Module Paths with the following command:

$env:PSModulePath.split(';')

The module files should be placed in a folder named psPAS in one of the listed locations.

More: about_PSModulePath

There are multiple options for downloading the module files:

PowerShell Gallery

• Download from the module PowerShell Gallery:
  • Run the PowerShell command Save-Module -Name psPAS -Path C:\temp
  • Copy the C:\temp\psPAS folder to your "Powershell Modules" directory of choice.

psPAS Release

• Download the latest release
  • Unblock & Extract the archive
  • Rename the extracted psPAS-v#.#.# folder to psPAS
  • Copy the psPAS folder to your "Powershell Modules" directory of choice.

psPAS Branch

• Download the master branch
  • Unblock & Extract the archive
  • Copy the psPAS (\<Archive Root>\psPAS-master\psPAS) folder to your "Powershell Modules" directory of choice.

Verification

Validate Install:

Get-Module -ListAvailable psPAS

Import the module:

Import-Module psPAS

List Module Commands:

Get-Command -Module psPAS

Get detailed information on specific commands:

Get-Help New-PASUser -Full

Sponsorship

Please support continued psPAS development; consider sponsoring @pspete on GitHub Sponsors

Changelog

All notable changes to this project will be documented in the Changelog

Author

• Pete Maan - pspete

License

This project is licensed under the MIT License.

Contributing

Any and all contributions to this project are appreciated.

See the CONTRIBUTING.md for a few more details.

Acknowledgements

Hat Tips:

Assaf Miron (AssafMiron) For the JSON formatting assistance.

Warren Frame (RamblingCookieMonster) for Add-ObjectDetail.ps1.

Joe Garcia (infamousjoeg) for the unofficial API documentation.

Chapeau!