Escolar Documentos
Profissional Documentos
Cultura Documentos
PASWS-009-5-0-1
Table of Contents
Table of Contents
Whats New?
Introduction
3
4
API Commands
5
5
CyberArk Authentication
Logon
Logoff
Managing Accounts
Add Account
Get Account
Delete Account
Change Credentials
Update Account Details
Safe Methods
Add Safe
Update Safe
Delete Safe
Safe Members
Add Safe Member
Update Safe Member
Delete Safe Member
Policy/ACL Methods
List Policy/ACL
Add Policy/ACL
Delete Policy/ACL
Account/ACL Methods
List Account/ACL
Add Account/ACL
Delete Account ACL
Applications
List Applications
List a Specific Application
Add Application
List all Authentication Methods of a Specific Application
Add Authentication
Delete a Specific Application
Delete a Specific Authentication
Usage Examples
Example 1: Adding an ACL
Example 2: Adding an Application/Authentication
Troubleshooting
7
7
8
9
9
13
15
16
18
23
23
26
29
30
30
33
39
40
40
42
44
45
45
47
50
51
51
53
55
58
59
63
64
65
65
70
75
Whats New?
Managing Accounts
Update Account Details - You can update an existing account's details. For more
information refer to Update Account Details, page 18.
Introduction
The PAS Web Services is a RESTful API that enables users to create, list, modify and
delete entities in Privileged Account Security solution from within programs and scripts.
The main purpose of the PAS Web Services is to automate tasks that are usually
performed manually using the UI, and to incorporate them into system and accountprovisioning scripts.
The PAS Web Services are installed as part of the PVWA installation, and can be used
immediately without any additional configuration.
This chapter includes the following sections:
SDK Supported Platforms
Using the PAS Web Services SDK
API Commands
This chapter introduces you to the Privileged Account Security API commands which
enable you to implement CyberArks Web Services SDK. It describes how to use them
and gives samples that show typical implementations.
It includes the following sets of API commands:
CyberArk Authentication
Managing Accounts
Safe Methods
Safe Members
Policy/ACL Methods
Account/ACL Methods
Note: For every Web Services call except for Logon, the request must include an HTTP header
field named Authorization, containing the value of a session token received from the Logon
activity
CyberArk Authentication
Logon
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/auth/
Cyberark/CyberArkAuthenticationService.svc/Logon
Note: Make sure there are no spaces in the URL.
HTTP Method:
POST
Parameters:
{
"username":"<user_name>",
"password":"<password>"
}
The Logon syntax has these parts:
Result:
Parameter
Type
Description
Default
username
string
None
password
string
None
{
"CyberArkLogonResult":"<Session_Token>"
}
Parameter
Type
Description
Default
CyberArkLogonResult
string
None
API Commands
Logoff
Description:
URL
http://<IIS_Server_Ip>/PasswordVault/WebServices/auth/
Cyberark/CyberArkAuthenticationService.svc/Logoff
Note: Make sure there are no spaces in the URL.
HTTP Method:
POST
Header Input:
Type
Description
Valid Values
Authorization
String
The token
that
identifies the
session.
A session token
that was returned
from the Logon
method.
Parameters:
Result:
{
}
Status Code: 200
Description: OK
Managing Accounts
Add Account
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Account
Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
Type
Description
Valid Values
Authorization
String
API Commands
Parameters:
{
"account" : {
"safe":"<Safe name>",
"platformID": "<Existing Platform ID>",
"address": "<Target address >",
"accountName": "<Object name (leave empty to auto generate)>",
"password": "<Password>",
"username": "<Target username>",
"disableAutoMgmt": "<true to disable account management by the CPM,
false to permit automatic management>",
"disableAutoMgmtReason": "<The reason for disabling CPM
management>",
"groupName":"<Name of the group with which the account will be
associated>",
"groupPlatformID":"<Group platform to base created group ID on, if ID
doesn't exist>",
"properties":
[
{"Key":"Port", "Value": "<port>"},
{"Key":"ExtraPass1Name", "Value": "Logon account name"},
{"Key":"ExtraPass1Folder", "Value": "Full pathname"},
{"Key":"ExtraPass1Safe", "Value": "Safename"},
{"Key":"ExtraPass3Name", "Value": "Reconcile account name"},
{"Key":"ExtraPass3Folder", "Value": "Full pathname"},
{"Key":"ExtraPass3Safe", "Value": "Safename"},
{"Key":"ParamName", "Value":"Parameter value"}
]
}
}
10
11
Parameter
Type
Description
safe
String
Safe name
platformID
String
Platform
ID
address
String
Machine
name or
address
account Name
String
Account
name
password
String
Password
username
String
User name
on the
target
machine
groupName
String
Group
name
groupPlatformID
String
Group
platform ID
disableAutoMgmt
Boolean
true/false
Default=false
disable AutoMgmt
Reason
String
dynamic
Properties
List
API Commands
Parameter
Type
Description
Valid
Values
ExtraPass1Name
String
Logon
account
ExtraPass1Folder
String
Folder
Default="Root"
ExtraPass1Safe
String
Safe name
ExtraPass3Name
String
Reconcile
account
ExtraPass3Folder
String
Folder
Default="Root"
ExtraPass3Safe
Result:
String
{
}
Status Code: 201
Description: Account was added successfully
Safe name
12
13
Get Account
Description:
This method returns information about an account. If more than one account
meets the search criteria, only the first account will be returned, although the
Count output parameter will display the number of accounts that were found.
Only the following users can access this account:
Users who are members of the Safe where the account is stored.
Users who have access to this specific account. For more information
about object level access control, refer to Object Level Access Control
in the Privileged Account Security Implementation Guide.
The user who runs this web service requires the following permission in
the Safe:
Retrieve account
Notes:
This method does not display the actual password.
If ten or more accounts are found, the Count Output parameter will show
10.
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Accounts
Note: Make sure there are no spaces in the URL.
HTTP
Method:
GET
Header
Input:
Query
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
The following parameters can be specified in the URL to filter the result:
Parameter
Type
Description
Valid
Values
Keywords
String
Multiple
keywords.
Maximum
of 500
characters.
Safe
String
Maximum
of 28
characters
API Commands
Result:
{
"Count: <the number of accounts that were found,>,
"accounts":[
{
"AccountID":"<ID of Account1>",
"Properties":
[
{"Key":"Safe", "Value": "<Account1s safe name>"},
{"Key":"Folder", "Value": "<Account1s folder name>"},
{"Key":"Name", "Value": "<The name of Account1>"}
]
}
]
}
Status Code: 200
The following table explains the output parameters:
Parameter
Type
Description
Count
Integer
AccountID
Integer
Safe
String
Folder
String
Name
String
14
15
Delete Account
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Accounts/{AccountID}
The following information is required to replace {AccountID}:
Valid
Values
Parameter
Type
Description
AccountID
Number
Account
ID
HTTP
Method:
DELETE
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
{
}
Result:
{
}
Status Code:200
Description: Account was deleted successfully
API Commands
Change Credentials
Description:
URL:
HTTP Method:
Header Input:
Parameters:
Valid
Values
Parameter
Type
Description
AccountID
Number
The unique
account ID of the
account to
change. This is
retrieved by the
Get Account web
service.
Account
ID
Type
Description
Authorization
String
The token
that
identifies
the session.
Valid
Values
A session
token that
was returned
from the
Logon
method.
{
ImmediateChangeByCPM
ChangeCredsForGroup
}
The Change Credential syntax has these parts
16
17
Parameter
Type
Description
ImmediateChange
ByCPM
String
Whether or
not the
account will
be
immediately
changed by
the CPM.
Valid
Values
Yes/No
Specify Yes
to initiate a
password
change by
the CPM.
ChangeCredsFor
Group
String
Whether or
not to
change the
password in
all accounts
that belong
to the same
group.
This
parameter is
only
relevant for
accounts
that belong
to an
account
group.
If this
parameter
does not
belong to a
group then it
will be
ignored.
Default =
Yes
Result:
{
}
Status Code 200
Yes/No
API Commands
URL:
http://<IIS_Server_IP>/PasswordVault/WebServices/
PIMServices.svc/Accounts/{AccountID}/
Note: Make sure there are no spaces in the URL.
The following information is required to replace AccountID:
Parameter
Type
Description
Valid
Values
AccountID
Number
Account
ID
HTTP
Method:
PUT
18
19
Header
Input:
Type
Description
Valid Values
Authorization
String
API Commands
Query
Parameters:
Type
Description
Valid Values
Folder
String
Folder name
AccountName
String
Account name
String
Device type
Different device
types require
different
parameters. For
more information,
refer to Appendix A:
Account Properties
in the Privileged
Account Security
Implementation
Guide.
PlatformID
String
The Platform ID of
the new platform to
assign to this
account. Make sure
you specify all
required
parameters.
Different platforms
require different
parameters. For
more information,
refer to Appendix A:
Account Properties
in the Privileged
Account Security
Implementation
Guide.
Platform ID
20
21
Parameter
Type
Description
Valid Values
Address
String
Machine name
or address
UserName -
String
User name on
the target
machine
GroupName
String
Account group
name
To create a new
group, specify the
group platform ID in
the
GroupPlatformID
property, then
specify the group
name. The group
will then be created
automatically.
GroupPlatformID
String
GroupPlatformID is
required when you
want to move an
account to a new
group.
Group
platform ID
Properties
List
List of name=value
pairs.
Property name
and value
API Commands
Example:
In the following example all properties were sent with the original
value except for the account address, which will be updated from
1.1.1.1 to 10.10.10.10:
{
"Accounts":
{
Folder: Root,
AccountName: Operating System-WinDesktopLocal1.1.1.1-Administrator,
PlaformID":WinDesktopLocal,
DeviceType":Operating System",
Address: 10.10.10.10,
UserName:Administrator
}
}
22
23
Result:
{
}
Status Code: 200
Description: Account was updated successfully
Safe Methods
Add Safe
Description:
Add Safes
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Safes
Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
Type
Description
Valid Values
Authorization
String
API Commands
Parameters:
{
"safe" : {
"SafeName":"<Safe name>",
"Description": "<Description>",
"OLACEnabled": <true/false>,
"ManagingCPM": "<CPM user>",
"NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>
}
}
The Add syntax has these parts:
Parameter
Type
Description
SafeName
String
Valid
Values
New Safe
name
Specify up to 28
characters.
The following characters
arent allowed: \/:*<>".|
Do not start a Safe name
with a space.
Description
String
Up to 100
characters.
OLAC
Enabled
Boolean
true/false
Managing
CPM
String
An existing
CPM user or
to prevent
the CPM
from
managing
the Safe.
NumberOf
Versions
Retention
Numeric
1-999
24
25
Parameter
Type
Description
NumberOf
Days
Retention
Numeric
Valid
Values
1-3650
Result:
{
"safe":{
"SafeName":"<The name of the new Safe>",
"Description":"<Description for the new Safe>",
"OLACEnabled":<true/false>,
"ManagingCPM":<Name of CPM user managing the Safe>,
"NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>,
}
}
Status Code: 201
Description: Safe was added successfully.
API Commands
Update Safe
Description:
This method updates a single Safe in the Vault. The user who runs this web
service requires the following permission in the Vault:
Manager Safe
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Safes/{SafeName}
The following information is required to replace {SafeName}:
Valid
Values
Parameter
Type
Description
SafeName
String
Safe name
HTTP
Method:
PUT
Header
Input:
Type
Description
Valid Values
Authorization
String
26
27
Parameters:
{
"Safes":{
"SafeName":"<The name of the Safe>",
"Description":"<Description of the Safe>",
"OLACEnabled":<true/false>,
"ManagingCPM":<Name of CPM user managing the Safe>,
"NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>,
}
}
Parameter
Type
Description
Valid
Values
SafeName
String
Safe
name.
Specify up to 28
characters.
The following characters
arent allowed: \/:*<>".|
Do not start a Safe name
with a space.
Description
String
Up to100
characters
OLACEnabled
Boolean
true/false
Managing
CPM
String
An
existing
CPM user
or to
prevent
the CPM
from
managing
the Safe.
NumberOf
Versions
Retention
Numeric
1-999
API Commands
Parameter
Type
Description
NumberOf
Days
Retention
Numeric
Valid
Values
1-3650
Result:
{
"Safes":{
"SafeName":"<The name of the Safe>",
"Description":"<Description for the Safe>",
"OLACEnabled":<true/false>,
"ManagingCPM":<Name of CPM user managing the Safe>,
"NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>,
}
}
Status Code: 200
28
29
Delete Safe
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Safes/{SafeName}
The following information is required to replace {SafeName}:
Parameter
Type
Description
Valid Values
SafeName
String
Safe name
HTTP
Method:
DELETE
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
{
}
Result:
{
}
Status Code 200
API Commands
Safe Members
Add Safe Member
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Safes/{SafeName}/Members
The following information is required to replace {SafeName}:
Parameter
Type
Description
Valid
Values
Safe name
String
Safe
name
HTTP
Method:
POST
Header
Input:
Type
Description
Valid Values
Authorization
String
30
31
Parameters:
{
"member":{
"MemberName":"<The name of the user to add as a Safe member>",
"SearchIn":"<Search for the member in the Vault or Domain>",
" MembershipExpirationDate:<MM\DD\YY or empty if there is no
expiration date>,
"Permissions":<Users permissions in the Safe>
[
{"Key": "UseAccounts", "Value": <true/false>},
{"Key": "RetrieveAccounts", "Value": <true/false>},
{"Key": "ListAccounts", "Value": <true/false>},
{"Key": "AddAccounts", "Value": <true/false>},
{"Key": "UpdateAccountContent", "Value": <true/false>},
{"Key": "UpdateAccountProperties", "Value": <true/false>},
{"Key": "InitiateCPMAccountManagementOperations", "Value":
<true/false>},
{"Key": "SpecifyNextAccountContent", "Value": <true/false>},
{"Key": "RenameAccounts", "Value": <true/false>},
{"Key": "DeleteAccounts", "Value": <true/false>},
{"Key": "UnlockAccounts", "Value": <true/false>},
{"Key": "ManageSafe", "Value": <true/false>},
{"Key": "ManageSafeMembers", "Value": <true/false>},
{"Key": "BackupSafe", "Value": <true/false>},
{"Key": "ViewAuditLog", "Value": <true/false>},
{"Key": "ViewSafeMembers", "Value": <true/false>},
{"Key": "RequestsAuthorizationLevel", "Value": <0/1/2>},
{"Key": "AccessWithoutConfirmation", "Value": <true/false>},
{"Key": "CreateFolders", "Value": <true/false>},
{"Key": "DeleteFolders", "Value": <true/false>},
{"Key": "MoveAccountsAndFolders", "Value": <true/false>},
]
}
The Add syntax has these parts
Parameter
Type
Description
Valid Values
MemberName
String
Vault or domain
user.
SearchIn
String
Vault or the
domains that
are defined in
the Vault.
API Commands
Parameter
Type
Description
Valid Values
Membership
Expiration
Date
String
Date format
MM/DD/YY
Result:
Permissions
specified in the
following table
{
"member":{
"MemberName":"<The name of the Safe member who has just been
added>",
"MembershipExpirationDate": <MM\DD\YY> or empty if there is no
expiration date
"Permissions":
{
"UseAccounts": <true/false>
"RetrieveAccounts": <true/false>
"ListAccounts": <true/false>
"AddAccounts": <true/false>
"UpdateAccountContent": <true/false>
"UpdateAccountProperties": <true/false>
"InitiateCPMAccountManagementOperations": <true/false>
"SpecifyNextAccountContent": <true/false>
"RenameAccounts": <true/false>
"DeleteAccounts": <true/false>
"UnlockAccounts": <true/false>
"ManageSafe": <true/false>
"ManageSafeMembers": <true/false>
"BackupSafe": <true/false>
"ViewAuditLog": <true/false>
"ViewSafeMembers": <true/false>
"RequestsAuthorizationLevel": <0/1/2>
"AccessWithoutConfirmation": <true/false>
"CreateFolders": <true/false>
"DeleteFolders": <true/false>
"MoveAccountsAndFolders": <true/false>
}
}
}
Status Code: 201
32
33
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Safes/{SafeName}
/Members/{MemberName}
The following parameters should pass as input in the URL:
Parameter
Type
Description
SafeName
String
MemberName
String
HTTP
Method:
PUT
Header
Input:
Type
Description
Valid Values
Authorization
String
A session
token that was
resumed from
the `Logon
method`.
API Commands
Parameters:
{
"members":{
" MembershipExpirationDate:<MM\DD\YY or empty for no expiration>,
"Permissions":<Users permissions in the Safe>
[
{"Key": "UseAccounts", "Value": <true/false>},
{"Key": "RetrieveAccounts", "Value": <true/false>},
{"Key": "ListAccounts", "Value": <true/false>},
{"Key": "AddAccounts", "Value": <true/false>},
{"Key": "UpdateAccountContent", "Value": <true/false>},
{"Key": "UpdateAccountProperties", "Value": <true/false>},
{"Key": "InitiateCPMAccountManagementOperations", "Value":
<true/false>},
{"Key": "SpecifyNextAccountContent", "Value": <true/false>},
{"Key": "RenameAccounts", "Value": <true/false>},
{"Key": "DeleteAccounts", "Value": <true/false>},
{"Key": "UnlockAccounts", "Value": <true/false>},
{"Key": "ManageSafe", "Value": <true/false>},
{"Key": "ManageSafeMembers", "Value": <true/false>},
{"Key": "BackupSafe", "Value": <true/false>},
{"Key": "ViewAuditLog", "Value": <true/false>},
{"Key": "ViewSafeMembers", "Value": <true/false>},
{"Key": "RequestsAuthorizationLevel", "Value": <0/1/2>},
{"Key": "AccessWithoutConfirmation", "Value": <true/false>},
{"Key": "CreateFolders", "Value": <true/false>},
{"Key": "DeleteFolders", "Value": <true/false>},
{"Key": "MoveAccountsAndFolders", "Value": <true/false>},
]
}
}
The List syntax has these parts:
Parameter
Type
Description
MembershipExpirationDate
String
Defines when
the user`s Safe
membership
expires. Specify
for no
expiration date.
Permissions
User permission
in the Safe.
Valid
Values
Permissions
specified in
the following
table.
34
35
Valid
Values
Parameter
Type
Description
UseAccounts
Boolean
true/false
RetrieveAccounts
Boolean
true/false
ListAccounts
Boolean
true/false
AddAccounts
Boolean
true/false
Boolean
true/false
UpdateAccount
Properties
Boolean
true/false
InitiateCPM
Boolean
true/false
Account
Initiate password
management
Management
Operations
such as changing
passwords,
verifying and reconciling
passwords. When this
parameter
is set to false, the
SpecifyNext
AccountContent
is automatically set to
false.
API Commands
Parameter
Type
Description
Valid
Values
SpecifyNext
AccountContent
Boolean
true/false
RenameAccounts
Boolean
Rename existing
accounts in the Safe.
true/false
DeleteAccounts
Boolean
Delete existing
passwords in the Safe
true/false
UnlockAccounts
Boolean
true/false
ManageSafe
Boolean
Perform administrative
tasks
true/false
Boolean
true/false
Boolean
true/false
Boolean
Log
ViewSafe
Members
true/false
true/false
36
37
Parameter
Type
Description
Requests
Authorization
Numeric
Requests Authorization
Level.
Level
Valid
Values
0/1/2
0 cannot authorize
1 authorization level
1
2 authorization level
2
Access
Boolean
Without
Confirmation
true/false
Boolean
true/false
DeleteFolders
Boolean
true/false
MoveAccounts
AndFolders
Boolean
true/false
API Commands
Result:
{
"member":{
"MemberName":"<The name of the Safe member >",
"MembershipExpirationDate": <MM\DD\YY or empty for no expiration
date>
"Permissions":
{
"UseAccounts": <true/false>
"RetrieveAccounts": <true/false>
"ListAccounts": <true/false>
"AddAccounts": <true/false>
"UpdateAccountContent": <true/false>
"UpdateAccountProperties": <true/false>
"InitiateCPMAccountManagementOperations": <true/false>
"SpecifyNextAccountContent": <true/false>
"RenameAccounts": <true/false>
"DeleteAccounts": <true/false>
"UnlockAccounts": <true/false>
"ManageSafe": <true/false>
"ManageSafeMembers": <true/false>
"BackupSafe": <true/false>
"ViewAuditLog": <true/false>
"ViewSafeMembers": <true/false>
"RequestsAuthorizationLevel": <0/1/2>
"AccessWithoutConfirmation": <true/false>
"CreateFolders": <true/false>
"DeleteFolders": <true/false>
"MoveAccountsAndFolders": <true/false>
}
}
}
Status Code: 201
38
39
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Safes/{SafeName}/Members/
{MemberName}
The following URL parameters are required:
Valid
Values
Parameter
Type
Description
SafeName
String
Safe name
Member
Name
String
Vault user
or domain
user.
HTTP
Method:
DELETE
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
{
}
Result:
{
}
Status Code: 200
API Commands
Policy/ACL Methods
List Policy/ACL
Description:
This method gets a list of the privileged commands (OPM rules) associated
with this policy.
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands
The following mandatory information is required to replace {PolicyID}:
Parameter
Type
Description
PolicyID
String
HTTP
Method:
GET
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
Type
Description
PolicyId
text
Valid
Values
Not empty
40
41
Result:
{
"ListPolicyPrivilegedCommandsResult":
[
{"Command":"<command>",
"CommandGroup":"<true/false>",
"Id":"<number>",
"Type":"<Policy/Account>",
"IsGroup":"<true/false>",
"PermissionType":"<Allow/Deny>",
"PolicyId":"<policyID>",
"Restrictions":"<restrictions string, delimited by ;>",
"UserName":"<userName>"},
{},
{}
]
}
Status Code: 200
Description: OK
API Commands
Add Policy/ACL
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands
The following mandatory information is required to
replace {PolicyID}:
Parameter
Type
Description
PolicyID
String
HTTP Method:
PUT
Header Input:
Type
Description
Valid Values
Authorization
String
The token
that
identifies
the session.
A session token
that was
returned from the
Logon method.
42
43
Parameters:
{
"Command":"<Command>",
"CommandGroup":<true/false>,
"PermissionType":"<Allow/Deny>",
"Restrictions":"<Restrictions>",
"UserName":"<UserName>"
}
The Add syntax has these parts:
Parameter
Type
Description
Valid Values
Command
text
The
command.
Not empty
Command
Group
bool
Whether or
not this is a
command
group.
True/False
Permission
text
Allow or
Deny
command.
Allow/Deny
PolicyId
text
The Policy
Id, provided
in the URL.
Not empty
Restrictions
text
A
restrictions
string.
<restrictionName>
The user
this rule
applies to.
Type
UserName
Result:
text
=
<Value>;< or
empty
{
"AddPolicyPrivilegedCommandResult":
{
"Command":"<command>",
"CommandGroup":"<true/false>",
"Id":"<number>",
"IsGroup":"<true/false>",
"Type":"<Policy/Account>",
"PermissionType":"<Allow/Deny>",
"PolicyId":"<policyID>",
"Restrictions":"<restrictions string, delimeted by ;>",
"UserName":"<userName>"}
}
Status Code: 201
Description: Policy ACL was added successfully
API Commands
Delete Policy/ACL
Description:
This method deletes all privileged commands rules associated with the
policy.
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands/{Id}
The following mandatory information is required to replace {PolicyID} and
{Id}:
Parameter
Type
Description
PolicyID
String
Id
String
HTTP
Method:
DELETE
Header Input:
Parameters:
Result:
Parameter
Type
Description
Valid Values
Authorization
String
Parameter
Type
Description
PolicyId
text
Not empty
Id
number
Not empty
44
45
Account/ACL Methods
List Account/ACL
Description:
This method gets a list of the privileged commands (OPM rules) associated
with this account.
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Account/{AccountAddress}|
{AccountUserName}|{AccountPolicyId}/PrivilegedCommands
The following mandatory information is required to replace
{AccountAddress}, {AccountUserName} and {AccountPolicyID}:
Parameter
Type
Description
Account
Address
String
Account
UserName
String
Account
PolicyId
String
HTTP
Method:
GET
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
Parameter
Type
Description
AccountPolicyId
text
AccountAddress
text
Not
empty
AccountUser
Name
text
Not
empty
API Commands
Result:
{
"ListAccountPrivilegedCommandsResult":
[
{"Command":"<command>",
"CommandGroup":"<true/false>",
"Id":"<number>",
"Type":"<Policy/Account>",
"IsGroup":"<true/false>",
"PermissionType":"<Allow/Deny>",
"PolicyId":"<policyID>",
"Restrictions":"<restrictions string, delimeted by ;>",
"UserName":"<userName>"},
{},
{}
]
}
Status Code: 200
Description: OK
46
47
Add Account/ACL
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Account/{AccountAddress}|
{AccountUserName}|{AccountPolicyId}/PrivilegedCommands
The following mandatory information is required to replace
{AccountAddress}, {AccountUserName} and {AccountPolicyID}:
Parameter
Type
Description
Account
Address
String
Account
UserName
String
Account
String
PolicyId
Note: Make sure there are no spaces in the URL.
HTTP
Method:
PUT
Header
Input:
Type
Description
Valid Values
Authorization
String
API Commands
Parameters:
{
"Command":"<Command>",
"CommandGroup":<true/false>,
"PermissionType":"<Allow/Deny>",
"Restrictions":"<Restrictions>",
"UserName":"<UserName>"
}
The Add syntax has these parts:
Parameter
Type
Description
Account
PolicyId
text
Account
Address
text
Not empty
Account
UserName
text
Not empty
Command
text
The command.
Not empty
Command
Group
bool
True/False
PermissionType
text
Allow or Deny
command.
Allow/Deny
Restrictions
text
A restrictions string.
<restrictionName>=
<Value>;< or
empty
UserName
text
Valid Values
48
49
Result:
{
"AddAccountPrivilegedCommandResult":
{
"Command":"<command>",
"CommandGroup":"<true/false>",
"Id":"<number>",
"IsGroup":"<true/false>",
"Type":"<Policy/Account>",
"PermissionType":"<Allow/Deny>",
"PolicyId":"<policyID>",
"Restrictions":"<restrictions string, delimeted by ;>",
"UserName":"<userName>"}
}
Status Code: 201
Description: Policy ACL added successfully.
API Commands
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands/{Id}
The following mandatory information is required to replace {PolicyID} and
{Id}:
Parameter
Type
Description
PolicyID
String
Id
String
HTTP
Method:
DELETE
Header Input:
Parameters:
Result:
Parameter
Type
Description
Valid Values
Authorization
String
Parameter
Type
Description
Account
PolicyId
text
Account
Address
text
Not
empty
Account
UserName
text
Not
empty
Id
number
Not
empty
50
51
Applications
List Applications
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Applications/
Note: Make sure there are no spaces in the URL.
HTTP Method:
GET
Header
Input:
Parameter
Type
Description
Valid Values
Authorization
String
The token
that
identifies
the session.
A session token
that was returned
from the Logon
method.
API Commands
Query Parameters:
Type
Description
Valid
Values
AppID
String
Application
name.
Not
empty
Location
String
Location of
the
application
in the Vault
hierarchy.
Default=\
Location
IncludeSublocations
Boolean
Whether or
not the
search will
be
performed in
sublocations
of the
specified
location.
Default=true
true/false
For example:
/PasswordVault/WebServices/PIMServices.svc/Applications?
Location=%5CApplications&AppID=App-1
Result:
{
"application": [
{
AccessPermittedFrom : <string>,
AccessPermittedTo : <string>,
"AllowExtendedAuthenticationRestrictions": <bool>,
AppID": <string>,
BusinessOwnerEmail : <string>,
BusinessOwnerFName : <string>,
BusinessOwnerLName : <string>,
BusinessOwnerPhone : <string>,
Description: <string>,
Disabled : <bool>,
ExpirationDate : <string>,
Location: <string>
}]
}
Status Code: 200
52
53
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Applications/{AppID}
The following information is required to replace {AppID}:
Parameter
Type
Description
AppID
String
Note:
HTTP
Method:
GET
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
{
}
API Commands
Result:
{
"application": [
{
AccessPermittedFrom : <string>,
AccessPermittedTo : <string>,
"AllowExtendedAuthenticationRestrictions": <bool>,
AppID": <string>,
BusinessOwnerEmail : <string>,
BusinessOwnerFName : <string>,
BusinessOwnerLName : <string>,
BusinessOwnerPhone : <string>,
Description: <string>,
Disabled : <bool>,
ExpirationDate : <mm/dd/yyyy>,
Location: <string>
}
]
}
Status Code: 200
54
55
Add Application
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Applications/
Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
Type
Description
Valid Values
Authorization
String
API Commands
Parameters:
{
"application":{
"AppID":"<application Name>",
"Description":"<description of the application>",
"Location":<existing location from the Vault>,
"AccessPermittedFrom":<the hour that access is permitted to the
application>,
"AccessPermittedTo":<the hour that access is permitted to the
application>,
"ExpirationDate":<expiration date of the application>,
"Disabled":"<whether the application is disabled>",
"BusinessOwnerFName":"<business owner first name>",
"BusinessOwnerLName":"<business owner last name >",
"BusinessOwnerEmail":"<business owner email >",
"BusinessOwnerPhone":"<business owner phone>",
}
}
The Add syntax has these parts:
Parameter
Type
Description
AppID
String
Application name.
Notes:
Valid
Values
Not
empty
String
Description of the
application.
Note: Specify up to 29
characters.
Location
String
AccessPermitted
From
Integer
0-23
56
57
Valid
Values
Parameter
Type
Description
AccessPermitted
Integer
0-23
ExpirationDate
String
mm-ddyyyy
Disabled
Boolean
true/false
BusinessOwner
String
To
FName
Note: Specifies up to 29
characters.
BusinessOwner
String
String
String
Business
Note: Specifies up to 24
characters.
Phone
LName
BusinessOwner
Email
BusinessOwner
Phone
Result:
{
}
Status Code: 201
Description: Application added successfully.
Owner
API Commands
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Applications/{AppID}/Authentications
The following information is required to replace {AppID}:
Parameter
Type
Description
AppID
String
HTTP
Method:
GET
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
{
}
Result:
{
"authentication": [
{
AllowInternalScripts : <bool>,
AppID": <string>,
AuthID": <authID>,
AuthType : <machineAddress/osUser/path/hashValue>,
AuthValue : <string>,
Comment : <string in case of hash authentication, else null>,
IsFolder : <string in case of path authentication, else null>,
}
]
}
Status Code: 200
58
59
Add Authentication
Description:
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Applications/{AppID}/Authentications/
The following information is required to replace {AppID}:
Parameter
Type
Description
AppID
String
HTTP
Method:
POST
Header
Input:
Type
Description
Valid Values
Authorization
String
API Commands
Parameters:
Type
Description
Valid Values
AuthType
String
The type of
authentication.
machineAddress
/osUser/path/
hashValue
This parameter
is required.
AuthValue
String
The content of
the
authentication.
This parameter
is required.
IsFolder
Boolean
Relevant for
Path
authentication
only.
Default=false
true/false
AllowInternalScripts
Boolean
Relevant for
Path
authentication
only.
Default=false
true/false
60
61
Type
Description
Valid Values
AuthType
String
The type of
authentication.
machineAddress/osUser/path/
hashValue
This
parameter is
required.
AuthValue
String
The content of
the
authentication.
This
parameter is
required.
Comment
String
Relevant for
Hash
authentication
only.
Text
Type
Description
Valid Values
AuthType
String
The type of
authentication.
machineAddress/osUser/path/
hashValue
This
parameter is
required.
API Commands
Parameter
Type
Description
AuthValue
String
The content of
the
authentication.
Valid Values
This
parameter is
required.
Type
Description
Valid Values
AuthType
String
The type of
authentication.
machineAddress/osUser/path/
hashValue
This
parameter is
required.
AuthValue
String
The content of
the
authentication.
This
parameter is
required.
Result:
{
}
Status Code: 201
Description: Authentication was added successfully
62
63
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Applications/{AppID}/
The following information is required to replace {AppID}:
Parameter
Type
Description
AppID
String
HTTP Method:
DELETE
Header Input:
Parameters:
Parameter
Type
Description
Authorization
String
The token
that
identifies
the session.
{
}
Result:
{
}
Status Code: 200
Valid
Values
A session
token that
was
returned
from the
Logon
method.
API Commands
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Applications/{AppID}/Authentications/{AuthID}
The following mandatory information is required to replace {AppID} and
{AuthID}:
Parameter
Type
Description
AppID
String
AuthID
Integer
HTTP
Method:
DELETE
Header
Input:
Parameters:
Parameter
Type
Description
Valid Values
Authorization
String
{
}
Result:
{
}
Status Code: 200
64
65
Usage Examples
Example 1: Adding an ACL
The following example shows how the PAS Web Services Access SDK can be
implemented in C# to add an ACL.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Web.Script.Serialization;
namespace ConsoleApplication4
{
class OpmRestExmpl
{
static void Main(string[] args)
{
// Consts
//=======
const string JSON_CONTENT_TYPE
=
"application/json";
const string VERB_METHOD_POST
= "POST";
const string VERB_METHOD_GET
= "GET";
const string JSON_SESSION_TOKEN_HEADER =
"CyberArkLogonResult";
const string JSON_GET_ACCOUNT_RES_HEADER =
"ListAccountPrivilegedCommandsResult";
const string HTTP_SESSION_TOKEN_HEADER =
"Authorization";
// PIM Fields
const string POLICY_ID = "UnixSSH";
const string ACCOUNT_ADDRESS = "10.10.10.10";
const string ACCOUNT_USERNAME = "root";
const string ACCOUNT_USERNAME = "root";
const string ACCOUNT_ID = ACCOUNT_ADDRESS + "|" +
ACCOUNT_USERNAME + "|" + POLICY_ID;
// Uri
const string PVWA_WS_URI
=
@"https://myServ.org.com/PasswordVault/WebServices";
const string LONGON_AUTHENTICATION_URI
= PVWA_
WS_URI + @"/auth/cyberark/CyberArkAuthenticationService.svc/logon";
const string LOGOFF_AUTHENTICATION_URI
= PVWA_
WS_URI +
@"/auth/cyberark/CyberArkAuthenticationService.svc/logoff";
const string ACCOUNT_ACL_URI
= PVWA_
WS_URI + @"/PIMServices.svc/Account/" + ACCOUNT_ID +
"/PrivilegedCommands";
// Variables
//===========
// HTTP objects
WebRequest restRequest;
API Commands
WebResponse restResponse;
// For JSON serialization
JavaScriptSerializer
jsonSerializer = new
JavaScriptSerializer();
// Workflow objects
string sessionToken = null;
object[] AccountAcls;
// Workflow
//===========
// 0. Get Credentials from user:
Console.WriteLine("Enter Username:");
string user = Console.ReadLine();
string user = Console.ReadLine();
Console.WriteLine("Enter Password:");
string pass = Console.ReadLine();
string connectionString = "{\"username\":\"" + user +
"\",\"password\":\"" + pass + "\"}";
// 1. Get the token
try
{
restRequest = WebRequest.Create(LONGON_
AUTHENTICATION_URI); // the uri.
restRequest.Method = VERB_METHOD_POST;
// We
post the user&pass to retrieve the token, so we declare it.
restRequest.ContentType = JSON_CONTENT_TYPE;
//
set to json - necessary for serialization & deserialization of the
content
// add the user&pass to packet data.
using (Stream requestStream =
restRequest.GetRequestStream())
{
byte[] inputStringBytes = Encoding.UTF8.GetBytes
(connectionString);
requestStream.Write(inputStringBytes, 0,
inputStringBytes.Length);
}
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
// Read the response stream from the http
header.
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonSessionToken = rdr.ReadToEnd();
// verify that it returned a result.
if (string.IsNullOrEmpty(rawJsonSessionToken))
throw new Exception("session token was not
created");
// deserialize the json and take the value
from it.
deserializedJsonDictionary =
66
67
(Dictionary<string, object>)jsonSerializer.DeserializeObject
(rawJsonSessionToken);
sessionToken = (string)
deserializedJsonDictionary[JSON_SESSION_TOKEN_HEADER];
// verify that the result isnt empty.
if (string.IsNullOrEmpty(sessionToken))
throw new Exception("session token was not
created");
}
}
}
{
Console.WriteLine("An error occurred on Logon");
HandleError(ex);
return;
}
// 2. Make the request (for instance, retrieve all
account acls)
// note that GET operations do not hold their data
inside the content section
// but rather pass it via the uri.
try
{
restRequest = WebRequest.Create(ACCOUNT_ACL_URI); //
the uri.
restRequest.Method = VERB_METHOD_GET;
// We
want to get all the acls so we use this verb (to add, we use
"PUT").
restRequest.ContentType = JSON_CONTENT_TYPE;
//
set to json - necessary for serialization & deserialization of the
content
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER] =
sessionToken;
// we add the session token to each request.
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
// Read the response stream from the http
header.
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonResult = rdr.ReadToEnd();
// verify that it returned a result.
if (string.IsNullOrEmpty(rawJsonResult))
throw new Exception("json result was not
created");
// deserialize the json and take the value
from it.
deserializedJsonDictionary =
(Dictionary<string, object>)jsonSerializer.DeserializeObject
(rawJsonResult);
AccountAcls = (object[])
API Commands
deserializedJsonDictionary[JSON_GET_ACCOUNT_RES_HEADER];
foreach (Dictionary<string, object> command in
AccountAcls)
{
Console.WriteLine("PrivilegedCommand: {0},
{1}, {2}",
command["Command"],
command["PermissionType"],
command["UserName"]);
}
}
}
}
catch (Exception ex)
{
Console.WriteLine("An error occured while getting
Acls");
HandleError(ex);
}
// 3. logoff
try
{
restRequest = WebRequest.Create(LOGOFF_
AUTHENTICATION_URI); // the uri.
restRequest.Method = VERB_METHOD_POST;
// We
want to get all the acls, so we use this verb (to add, we use
"PUT").
restRequest.ContentType = JSON_CONTENT_TYPE;
//
set to json - necessary for serialization & deserialization of the
content
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER] =
sessionToken;
// we add the session token to each request.
using (Stream requestStream =
restRequest.GetRequestStream())
{
byte[] inputStringBytes = Encoding.UTF8.GetBytes
("");
requestStream.Write(inputStringBytes, 0,
inputStringBytes.Length);
}
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
// Read the response stream from the http
header.
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonResult = rdr.ReadToEnd();
}
}
catch (Exception ex)
68
69
{
Console.WriteLine("An error occurred while
performing Logoff");
HandleError(ex);
}
private static void HandleError(Exception ex)
{
if (ex is WebException)
{
WebException wex = ex as WebException;
HttpWebResponse res = ((HttpWebResponse)
(wex.Response));
switch (res.StatusCode)
{
case HttpStatusCode.Forbidden:
Console.WriteLine("An Authentication error
occurred: " + res.StatusDescription);
break;
case HttpStatusCode.InternalServerError:
default:
Console.WriteLine("An error occurred: " +
res.StatusDescription);
break;
}
}
else
{
Console.WriteLine("An error occurred: " + ex.Message);
}
}
}
}
API Commands
70
71
API Commands
restRequest = WebRequest.Create(AIM_WS_ONE);
restRequest.Method = VERB_METHOD_POST;
restRequest.ContentType= JSON_CONTENT_TYPE;
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER]=
SessionToken;
string APPIDRequest = "{\"application\":{\"AppID\":\"" +
APPID + "\"}}";
using (Stream requestStream =
restRequest.GetRequestStream())
{
byte[] inputStringBytes = Encoding.UTF8.GetBytes
(APPIDRequest);
requestStream.Write(inputStringBytes, 0,
inputStringBytes.Length);
}
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
StreamReader rdr = new StreamReader
(responseStream,Encoding.UTF8);
string response = rdr.ReadToEnd();
}
}
}
catch (Exception ex)
{
Console.WriteLine("Error occured creating
AppID");
HandleError(ex);
}
//List of existing AppIDs
try
{
restRequest = WebRequest.Create(AIM_WS_ONE);
restRequest.Method = VERB_METHOD_GET;
restRequest.ContentType = JSON_CONTENT_TYPE;
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER] =
SessionToken;
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonResult = rdr.ReadToEnd();
if (string.IsNullOrEmpty(rawJsonResult))
throw new Exception("Json result was
72
73
not created");
deserializedJsonDictionary =
(Dictionary<string, object>)jsonSerializer.DeserializeObject
(rawJsonResult);
ApplicationIds =
(object[])deserializedJsonDictionary[JSON_GET_
ACCOUNT_RES_HEADER];
foreach (Dictionary<string, object> AppID
in ApplicationIds)
{
Console.WriteLine("ApplicationID: {0}",
AppID["AppID"]);
}
}
}
}
catch (Exception ex)
{
Console.WriteLine("An error occured while
retrieving Application List");
HandleError(ex);
}
//Logoff
try
{
restRequest = WebRequest.Create(LOGOFF_
AUTHENTICATION_URI);
restRequest.Method = VERB_METHOD_POST;
restRequest.ContentType = JSON_CONTENT_TYPE;
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER] =
SessionToken;
using (Stream requestStream =
restRequest.GetRequestStream())
{
byte[] inputStringBytes =
Encoding.UTF8.GetBytes("");
requestStream.Write(inputStringBytes, 0,
inputStringBytes.Length);
}
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonResult = rdr.ReadToEnd();
}
}
catch (Exception ex)
{
API Commands
74
75
Troubleshooting
Problem:
A delete request was sent to the Vault, and the following response was
received: 405 Method not allowed.
Solution: