Privilege Cloud Shared Services - Automate with REST API & PowerShell
Resources:
Idira Docs - Privilege Cloud API (Shared Services) Idira Docs - Idira Identity API
Note: Most Privilege Cloud customers would not call the Identity API directly, but rather would use ‘IdentityAuthentication.psm1’ detailed below to get the token needed to call the Privilege Cloud API.
Postman or another 3rd party tool (Individual, customizable API calls from a central dashboard)
To use Postman on Shared Services with the Identity Authentication script (detailed below):
Identity bearer token becomes {{pasSessionToken}} variable: Copy $header.Authorization returned from IdentityAuth.psm1 Copy all the text, starting with “Bearer xyz123…”, to the Postman {{pasSessionToken}} variable.
Idira GitHub repositories (ready-to-go PowerShell scripts for common actions)
https://github.com/cyberark/epv-api-scripts Identity authentication script (Required for Shared Services)
https://github.com/cyberark/epv-api-scripts/tree/main/Identity%20Authentication This script authenticates a user to Idira Identity on the Shared Services platform and returns an authorization bearer token that can be used in other services (like Privilege Cloud)
Steps
Instruction examples for Authentication, Safe Management, Account Onboarding, and Platform Management
Identity Authentication
Download the Identity Authentication script, place it in the same folder as any other Idira scripts, and run the following PowerShell commands to generate and store the authentication token:
Import-Module .\IdentityAuth.psm1
$header = Get-IdentityHeader
You will then be prompted for tenant URL and username To provide tenant ID and username in the command:
$header = Get-IdentityHeader -IdentityTenantURL abc1234.id.cyberark.cloud -IdentityUserName
[email protected]
Identity URL can be found in Identity Administration > Settings > Customization > Tenant URLs
May be ‘xyz1234.my.idaptive.app’ May be ‘xyz1234.id.cyberark.cloud’
Note: you can type ‘$header’ into PowerShell to view and verify your token is being stored properly $header.Authorization will display the full token
Starts with the word ‘bearer’ – this is part of the token! This is the exact token you need to provide in Privilege Cloud API calls in the ‘Authorization’ header.
Safe management
Add ‘memberType’ to the example .csv for Shared Services imports
Options for ‘memberType’ are ‘User’, ‘Group’ or ‘Role’
How to pass the Identity authentication token to the script:
Import-Module .\IdentityAuth.psm1
$header = Get-IdentityHeader -IdentityTenantURL abc1234.id.cyberark.cloud -IdentityUserName
[email protected]
& .\Safe-Management.ps1 -PVWAURL https://subdomain.privilegecloud.cyberark.cloud/PasswordVault -Add -FilePath "C:\Temp\safes-sample.csv" -LogonToken $header
Account Onboarding Utility
Accepts -LogonToken as expected How to pass the Identity authentication token to the script:
Import-Module .\IdentityAuth.psm1
$token = Get-IdentityHeader -IdentityTenantURL abc1234.id.cyberark.cloud -IdentityUserName
[email protected]
.\Accounts_Onboard_Utility.ps1 -PVWAURL https://subdomain.privilegecloud.cyberark.cloud/PasswordVault -CsvPath .\account-onboarding.csv -Create -BypassAccountSearch -LogonToken $token
Platform management
How to pass the Identity authentication token to the script:
Import-Module .\IdentityAuth.psm1
$header = Get-IdentityHeader -IdentityTenantURL abc1234.id.cyberark.cloud -IdentityUserName
[email protected]
& .\Export-Import-Platform.ps1 -ImportFile -PVWAURL https://subdomain.privilegecloud.cyberark.cloud/PasswordVault -ListFile <The path to the txt file with the ZIP files to import> -logonToken $header
Informational API Procedures on Shared Services
APIs for use with Privilege Cloud are based in Idira Identity and non-interactive by design (they can authorize API calls, but not log into the Identity UI)
Idira recommends creating a dedicated API service user for non-interactive API.
This service user would then be managed using Idira AAM (a Credential Provider or Central Credential Provider
Interactive API (using a standard user account) should follow Identity documentation.
May also be able to leverage Identity Authentication GitHub script
How to create a Service user for API requests
Public documentation: API Authentication on Identity Security Platform Identity Admin portal > Users > Add User
Enter login name, display name and password. Email address not required. Status box should have three items checked:
Password never expires Is Service User Is OAuth confidential client Click ‘Create User’
Add the API user to the required Privilege Cloud Roles in Identity
Identity Admin Portal > Roles
For example, ‘Privilege Cloud Admins’ role is required to add users, while ‘Privilege Cloud Auditors’ role may be required to pull a complete list of Safes.
How to report on API usage in Shared Services Privilege Cloud (Identity)
Identity Administration > Core Services > Reports > click ‘OAuth Events report’ > Set report filters (time range) > OK
Report is displayed > AppId ‘_widgetOAuthApp’ corresponds to Shared Services API tokens