Você está na página 1de 75

Privileged Account Security

Web Services SDK


Implementation Guide
Version 9.5
Copyright 1999-2015 CyberArk Software Ltd. All rights reserved.
This document contains information and ideas, which are proprietary to CyberArk
Software Ltd. No part of this publication may be reproduced, stored in a retrieval system,
or transmitted, in any form or by any means, electronic, mechanical, photocopying,
recording, scanning, or otherwise, without the prior written permission of CyberArk
Software Ltd.

PASWS-009-5-0-1

Table of Contents

Table of Contents
Whats New?
Introduction

3
4

SDK Supported Platforms


Using the PAS Web Services SDK

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

Privileged Account Security

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.

Privileged Account Security

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

Privileged Account Security

Privileged Account Security Web Services SDK Implementation Guide

SDK Supported Platforms


The PAS Web Services SDK is a RESTful API that can be invoked by any RESTful client
for various programming and scripting environments, including Java, C#, Perl, PHP,
Python and Ruby.

Using the PAS Web Services SDK


The PAS Web Services SDK enables you to perform activities on PAS objects via a
REST Web Service interface. Each PAS object has its own URL path in the PVWA
website that can be accessed using the relevant HTTP request verb. For example, to get
a list of all privileged commands (OPM rules) associated with a specific account, access
the privileged commands path of that account with an HTTP GET request, using the
following format:
http://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Account/
<AccountAdress>|<AccountUserName>|<AccountPolicyId>/PrivilegedCommands
For example:
http://10.10.10.10/PasswordVault/WebServices/PIMServices.svc/Account/
MyComp|root|UnixSSH/PrivilegedCommands
As a result of the above request, a list of all privileged commands associated with the root
user of the machine MyComp appears, in JSON format.
Every HTTP request must contain an HTTP header field named Authorization that
contains the value of a session token received from the Logon activity.
The PAS Web Services can be accessed with any tool or language that enables you to
create HTTP requests and handle HTTP responses. For more information, refer to the
C# and Java examples in Usage Examples, page 65.

Privileged Account Security

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

Privileged Account Security

Privileged Account Security Web Services SDK Implementation Guide

CyberArk Authentication
Logon
Description:

This method authenticates a user to the Vault and returns a token


that can be used in subsequent Web Services calls.

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

The name of the user logging


on.

None

password

string

The password of the user


logging on.

None

{
"CyberArkLogonResult":"<Session_Token>"
}
Parameter

Type

Description

Default

CyberArkLogonResult

string

The session token


that identifies the
session. This
token is used for
every other web
service in the same
session.

None

Privileged Account Security

API Commands

Logoff
Description:

This method performs Logoff and removes the Vault session.

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:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token
that
identifies the
session.

A session token
that was returned
from the Logon
method.

Parameters:

This method has no parameters.

Result:

{
}
Status Code: 200
Description: OK

Privileged Account Security

Privileged Account Security Web Services SDK Implementation Guide

Managing Accounts
Add Account
Description:

This method adds a new privileged account to the Vault.

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:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

Privileged Account Security

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"}
]
}
}

Privileged Account Security

10

11

Privileged Account Security Web Services SDK Implementation Guide

The Add syntax has these parts:


Valid
Values

Parameter

Type

Description

safe

String

The Safe where the


account will be created.
This parameter is
required.

Safe name

platformID

String

The platform assigned to


this account.
This parameter is
required.

Platform
ID

address

String

The name or address of


the machine where the
account will be used.

Machine
name or
address

account Name

String

The name of the account.

Account
name

password

String

The password value.


This parameter is
required.

Password

username

String

The name of the user who


will use the account on
the target machine.

User name
on the
target
machine

groupName

String

The name of the group


with which the account
will be associated .

Group
name

groupPlatformID

String

The ID of the platform


that manages the account
group.

Group
platform ID

disableAutoMgmt

Boolean

Whether or not automatic


management will be
disabled for this account.

true/false

Default=false
disable AutoMgmt
Reason

String

The reason why the


account was disabled for
auto-management.
This parameter is only
relevant if
disableAutoMgmt is set
to true.

dynamic
Properties

List

List of name=value pairs

Privileged Account Security

API Commands

Parameter

Type

Description

Valid
Values

ExtraPass1Name

String

The name of the logon


account.

Logon
account

ExtraPass1Folder

String

The folder where the


logon account is stored.

Folder

Default="Root"
ExtraPass1Safe

String

The Safe where the logon


account is stored.

Safe name

ExtraPass3Name

String

The name of the reconcile


account.

Reconcile
account

ExtraPass3Folder

String

The folder where the


reconcile account is
stored.

Folder

Default="Root"
ExtraPass3Safe

Result:

String

The Safe where the


reconcile account is
stored.

{
}
Status Code: 201
Description: Account was added successfully

Privileged Account Security

Safe name

12

13

Privileged Account Security Web Services SDK Implementation Guide

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:

The following input parameter is required in the header:

Query
Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

The following parameters can be specified in the URL to filter the result:
Parameter

Type

Description

Valid
Values

Keywords

String

Specify a keyword to search for. If


you specify multiple keywords, the
search will include all the
keywords. Separate keywords with
a space.

Multiple
keywords.
Maximum
of 500
characters.

Safe

String

Specify the name of a Safe to


search. The search will be carried
out only in the Safes in the Vault
that you are authorized to access.

Maximum
of 28
characters

The following example shows how to retrieve an account with address:


10.10.1.1, user: root, Safe: called UNIXAccountsSafe.
/PasswordVault/WebServices/PIMServices.svc/Accounts?
Keywords=10.10.1.1%2C%20root&Safe=%5EUNIXAccountsSafe%5Cd

Privileged Account Security

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

The number of accounts that were found by the


requested query.

AccountID

Integer

The account`s unique ID.

Safe

String

The name of the Safe where the account is


stored.

Folder

String

The name of the folder where the account is


stored.

Name

String

The name of the account.

Privileged Account Security

14

15

Privileged Account Security Web Services SDK Implementation Guide

Delete Account
Description:

This method deletes a specific account in the Vault.


The user who runs this web service requires the following permission in the
Vault:
Delete accounts

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

The unique ID of the account to


delete. This is retrieved by the Get
Account web service.

Account
ID

Note: Make sure there are no spaces in the URL.

HTTP
Method:

DELETE

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

{
}

Result:

{
}
Status Code:200
Description: Account was deleted successfully

Privileged Account Security

API Commands

Change Credentials
Description:

This method initiates an immediate password change by


the CPM to a new random password.
The user who runs this web service requires the following
permission in the Safe where the privileged account is
stored:

URL:

Initiate CPM password management operations


http://<IIS_Server_Ip>//PasswordVault/WebServices/
PIMServices.svc/Accounts/{AccountID}
/ChangeCredentials
The following information is required to replace
{AccountID}:

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

Note: Make sure there are no spaces in the URL.


PUT
The following input parameter is required in the header:
Parameter

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

Privileged Account Security

16

17

Privileged Account Security Web Services SDK Implementation Guide

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

Privileged Account Security

Yes/No

API Commands

Update Account Details


Description:

This method updates an existing account's details. In order to execute this


web service, all the accounts details must be entered in the web service
request. If the existing accounts properties are not sent as part of the
request, the properties will be removed from the account. Any values sent in
the request that were changed will be updated. All other properties values
will remain the same.
When you change the name or folder of a service account that has multiple
dependencies (usages), the connection between it and its dependencies will
be automatically maintained.
In addition, when you change the name or a folder of an account that is
linked to another account, whether logon, reconciliation or verification, the
links will be automatically updated.
Notes:
This web service has the following limitations:
Dependencies (usages) cannot be updated.
Accounts that do not have a policy ID cannot be updated.
Permissions
To update account properties, Safe members require the following
permission:
Update password properties
To rename accounts, Safe members require the following permission:
Rename accounts
To move accounts to a different folder, Safe members require the
following permission:
Move accounts/folders

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

The unique ID of the account to


update. This is retrieved by the

Account
ID

Get Account Service.

HTTP
Method:

PUT

Privileged Account Security

18

19

Privileged Account Security Web Services SDK Implementation Guide

Header
Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the "Logon"
method.

Privileged Account Security

API Commands

Query
Parameters:

The following parameters can be updated:


Parameter

Type

Description

Valid Values

Folder

String

The folder where


the account is
stored.

Folder name

AccountName

String

The name of the


account to update.

Account name

Make sure the


account name
meets your
enterprise account
policy
specifications.
DeviceType

String

The device type to


update. Make sure
you specify all
required
parameters.

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.

Privileged Account Security

Platform ID

20

21

Privileged Account Security Web Services SDK Implementation Guide

Parameter

Type

Description

Valid Values

Address

String

The new name or


address of the
machine where the
account will be
used.

Machine name
or address

UserName -

String

The updated name


of the user who will
use the account on
the target machine.

User name on
the target
machine

GroupName

String

The name of the


group with which
the account is
associated.

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

Privileged Account Security

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
}
}

In the following example, a new account group name was entered to


replace an existing account group name in the optional GroupName
field:
{
"Accounts":
{
Folder:Root,
AccountName: Operating System-WinDesktopLocal1.1.1.1-Administrator,
PlaformID":WinDesktopLocal,
DeviceType":Operating System,
Address:10.10.10.10,
UserName":Administrator,
GroupName: WindowsAccountGroup
}
}

In the following example, department and geographical location


properties are added to an existing account with properties:
{
"Accounts":
{
Folder:Root,
AccountName: Operating System-WinDesktopLocal1.1.1.1-Administrator,
PlaformID":WinDesktopLocal,
DeviceType":Operating System,
Address:10.10.10.10,
UserName":Administrator,
GroupName: WindowsAccountGroup,
Properties : [{
Key: Department, Value: Finance"},
{Key": GeoLocation, Value: UK}]
}
}

Privileged Account Security

22

23

Privileged Account Security Web Services SDK Implementation Guide

Result:

{
}
Status Code: 200
Description: Account was updated successfully

Safe Methods
Add Safe
Description:

This method adds a new Safe to the Vault.


The user who runs this web service requires the following permission in the
Vault:

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:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

Privileged Account Security

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

Name of a Safe to create.


This parameter is required.

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

Description of the new Safe.

Up to 100
characters.

OLAC
Enabled

Boolean

Whether or not to enable


Object Level Access Control
for the new Safe.

true/false

Managing
CPM

String

The name of the CPM user


who will manage the new
Safe.

An existing
CPM user or
to prevent
the CPM
from
managing
the Safe.

NumberOf
Versions
Retention

Numeric

The number of retained


versions of every password
that is stored in the Safe.

1-999

Specify either this parameter


or NumberOfDaysRetention.
If you specify this parameter
the NumberOfDaysRetention
parameter is disabled.

Privileged Account Security

24

25

Privileged Account Security Web Services SDK Implementation Guide

Parameter

Type

Description

NumberOf
Days
Retention

Numeric

The number of days for which


password versions are saved
in the Safe.

Valid
Values
1-3650

Specify either this parameter


or
NumberOfVersionsRetention
If you specify this parameter
the
NumberOfVersionsRetention
parameter is disabled.

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.

Privileged Account Security

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

The name of the Safe to


update.

Safe name

Note: Make sure there are no spaces in the URL.

HTTP
Method:

PUT

Header
Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

Privileged Account Security

26

27

Privileged Account Security Web Services SDK Implementation Guide

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

The name of the Safe to


update.

Safe
name.

Specify up to 28
characters.
The following characters
arent allowed: \/:*<>".|
Do not start a Safe name
with a space.
Description

String

The updated description of


the Safe.

Up to100
characters

OLACEnabled

Boolean

Whether or not to enable


Object Level Access
Control.

true/false

Managing
CPM

String

Name of the CPM user who


will manage the Safe.

An
existing
CPM user
or to
prevent
the CPM
from
managing
the Safe.

NumberOf
Versions
Retention

Numeric

The number of versions of


every password that is
stored in the Safe.

1-999

Specify either this parameter


or NumberOfDaysRetention.
If you specify this parameter
the
NumberOfDaysRetention
parameter is disabled.

Privileged Account Security

API Commands

Parameter

Type

Description

NumberOf
Days
Retention

Numeric

The number of days that


versions are stored in the
Safe.

Valid
Values
1-3650

Specify either this parameter


or
NumberOfVersionsRetention
If you specify this parameter
the
NumberOfVersionsRetention
parameter is disabled.

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

Privileged Account Security

28

29

Privileged Account Security Web Services SDK Implementation Guide

Delete Safe
Description:

This method deletes a Safe from the Vault.


The user who runs this web service requires the following permission in the
Vault:
Manage Safe

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

The name of Safe to delete.

Safe name

Note: Make sure there are no spaces in the URL.

HTTP
Method:

DELETE

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

{
}

Result:

{
}
Status Code 200

Privileged Account Security

API Commands

Safe Members
Add Safe Member
Description:

This method adds an existing user as a Safe member.


The user who runs this web service requires the following permission in the
Vault:
Manage Safe Members

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

The name of the safe to add a


member to.

Safe
name

Note: Make sure there are no spaces in the URL.

HTTP
Method:

POST

Header
Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the "Logon"
Method.

Privileged Account Security

30

31

Privileged Account Security Web Services SDK Implementation Guide

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 or


group to add as a Safe
member. This parameter is
required.

Vault or domain
user.

SearchIn

String

The Vault or Domain to


search for the user or group
to add as a Safe member.

Vault or the
domains that
are defined in
the Vault.

Default value = Vault.

Privileged Account Security

API Commands

Parameter

Type

Description

Valid Values

Membership
Expiration
Date

String

Defines when the


members Safe
membership expires.

Date format
MM/DD/YY

Specify for no expiration


date.
Default = no expiration
Permissions

Result:

The Safe members


permissions in the Safe.

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

Privileged Account Security

32

33

Privileged Account Security Web Services SDK Implementation Guide

Update Safe Member


Description:

This method updates an existing Safe member.


The user who runs this web service requires the following permission
in the Vault:
Manage Safe Members

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

Name of the Safe to which the Safe member


belongs.

MemberName

String

Vault/Domain user/group member to update.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

PUT

Header
Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session
token that was
resumed from
the `Logon
method`.

Privileged Account Security

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.

Specify the following permissions:

Privileged Account Security

Valid
Values

Permissions
specified in
the following
table.

34

35

Privileged Account Security Web Services SDK Implementation Guide

Valid
Values

Parameter

Type

Description

UseAccounts

Boolean

Use accounts but not


view passwords.

true/false

RetrieveAccounts

Boolean

Retrieve and view


accounts in the Safe.

true/false

ListAccounts

Boolean

View accounts list.

true/false

AddAccounts

Boolean

Add accounts in the Safe.


Users who are given
AddAccounts
authorization receive
UpdateAccountProperties

true/false

as well. Users who have


this permission
automatically
have
UpdateAccountProperties
as well.
UpdateAccount
Content

Boolean

Update existing account


content.

true/false

UpdateAccount
Properties

Boolean

Update existing account


properties.

true/false

InitiateCPM

Boolean

true/false

Account

Initiate password
management

Management

operations through CPM,

Operations

such as changing
passwords,
verifying and reconciling
passwords. When this
parameter
is set to false, the
SpecifyNext
AccountContent
is automatically set to
false.

Privileged Account Security

API Commands

Parameter

Type

Description

Valid
Values

SpecifyNext
AccountContent

Boolean

Specify the password that

true/false

will be used when the


CPM changes the
password value.
This parameter can only
be specified when
InitiateCPMAccount
ManagementOperations
is set to true.
When
InitiateCPMAccount
ManagementOperations
is set to false this
parameter is
automatically set to false.

RenameAccounts

Boolean

Rename existing
accounts in the Safe.

true/false

DeleteAccounts

Boolean

Delete existing
passwords in the Safe

true/false

UnlockAccounts

Boolean

Unlock accounts that are


locked by other users.

true/false

ManageSafe

Boolean

Perform administrative
tasks

true/false

in the Safe, including:


Update Safe
properties
Recover the Safe
Delete the Safe
ManageSafe
Members

Boolean

Add and remove Safe


members, and update
their

true/false

authorizations in the Safe.


BackupSafe

Boolean

Create a backup of a Safe

true/false

and its contents, and


store in another location.
ViewAudit

Boolean

Log
ViewSafe
Members

View account and user

true/false

activity in the Safe.


Boolean

View Safe members`


permissions.

Privileged Account Security

true/false

36

37

Privileged Account Security Web Services SDK Implementation Guide

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

Access the Safe without


confirmation from
authorized users. This
overrides the

true/false

Safe properties that


specify
that Safe members
require confirmation to
access the Safe.
CreateFolders

Boolean

Create folders in the safe

true/false

DeleteFolders

Boolean

Delete folders from the


safe

true/false

MoveAccounts
AndFolders

Boolean

Move accounts and


folders in the Safe to
different folders and
subfolders.

true/false

Privileged Account Security

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

Privileged Account Security

38

39

Privileged Account Security Web Services SDK Implementation Guide

Delete Safe Member


Description:

This method removes a specific member from a Safe.


The user who runs this web service requires the following permission in the
Vault:
Manage Safe Members

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

The name of the Safe from which


to delete the member.

Safe name

Member
Name

String

The name of the Safe member to


delete from the Safes list of
members.

Vault user
or domain
user.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

DELETE

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

{
}

Result:

{
}
Status Code: 200

Privileged Account Security

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

The ID of the policy for which the privileged


commands will be listed.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

GET

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

The List syntax has these parts:


Parameter

Type

Description

PolicyId

text

The Policy Id provided in the


URL.

Privileged Account Security

Valid
Values
Not empty

40

41

Privileged Account Security Web Services SDK Implementation Guide

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

Privileged Account Security

API Commands

Add Policy/ACL
Description:

This method adds a new privileged command rule to the


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

The ID of the policy to which the


new privileged command rule will
be added.

Note: Make sure that there are no spaces in the URL.

HTTP Method:

PUT

Header Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token
that
identifies
the session.

A session token
that was
returned from the
Logon method.

Privileged Account Security

42

43

Privileged Account Security Web Services SDK Implementation Guide

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.

User name, or "*"


for all users

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

Privileged Account Security

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

The ID of the policy from which the privileged


commands will be deleted.

Id

String

The ID of the command rule that will be deleted.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

DELETE

Header Input:

The following input parameter is required in the header:

Parameters:

Result:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

The Delete syntax has these parts:


Valid
Values

Parameter

Type

Description

PolicyId

text

The Policy Id provided in the


URL.

Not empty

Id

number

The Rule Id provided in the


URL.

Not empty

Status Code: 204 (empty content)


Description: Policy ACL with Id <Id> was deleted successfully.

Privileged Account Security

44

45

Privileged Account Security Web Services SDK Implementation Guide

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

The address of the account whose


privileged commands will be listed.

Account
UserName

String

The name of the accounts user.

Account
PolicyId

String

The Policy ID associated with this account.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

GET

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

The List syntax has these parts:


Valid
Values

Parameter

Type

Description

AccountPolicyId

text

The Policy Id of the account


provided in the URL.

AccountAddress

text

The Address of the account


provided in the URL.

Not
empty

AccountUser
Name

text

The User Name of the account


provided in the URL.

Not
empty

Privileged Account Security

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

Privileged Account Security

46

47

Privileged Account Security Web Services SDK Implementation Guide

Add Account/ACL
Description:

This method adds a new privileged command rule to the 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

The address of the account to which a new


privileged command will be added.

Account
UserName

String

The name of the accounts user.

Account

String

The Policy ID associated with this account.

PolicyId
Note: Make sure there are no spaces in the URL.

HTTP
Method:

PUT

Header
Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

Privileged Account Security

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

The Policy Id of the


account, provided in
the URL.

Account
Address

text

The Address of the


account, provided in
the URL.

Not empty

Account
UserName

text

The User Name of


the account, provided
in the URL.

Not empty

Command

text

The command.

Not empty

Command
Group

bool

Whether or not this is


a command group.

True/False

PermissionType

text

Allow or Deny
command.

Allow/Deny

Restrictions

text

A restrictions string.

<restrictionName>=
<Value>;< or
empty

UserName

text

The user this rule


applies to.

User name, or "*"


for all users

Privileged Account Security

Valid Values

48

49

Privileged Account Security Web Services SDK Implementation Guide

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.

Privileged Account Security

API Commands

Delete Account ACL


Description:

This method deletes privileged commands rules associated with the


account.

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

The ID of the account from which the privileged


commands will be deleted.

Id

String

The ID of the command rule that will be deleted.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

DELETE

Header Input:

The following input parameter is required in the header:

Parameters:

Result:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

The Delete syntax has these parts:


Valid
Values

Parameter

Type

Description

Account
PolicyId

text

The Policy Id of the account,


provided in the URL.

Account
Address

text

The address of the account,


provided in the URL.

Not
empty

Account
UserName

text

The username of the account,


provided in the URL.

Not
empty

Id

number

The ID of the rule, provided in the


URL.

Not
empty

Status Code: 204 (empty content)


Description: Policy ACL with Id <Id> was deleted successfully.

Privileged Account Security

50

51

Privileged Account Security Web Services SDK Implementation Guide

Applications
List Applications
Description:

This method returns a list of all the applications in the Vault.


The user who runs this web service requires the following
permission in the Vault:
Audit Users

URL:

http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Applications/
Note: Make sure there are no spaces in the URL.

HTTP Method:

GET

Header

The following input parameter is required in the 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.

Privileged Account Security

API Commands

Query Parameters:

The following parameters can be specified in the URL to filter


the result:
Parameter

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

Privileged Account Security

52

53

Privileged Account Security Web Services SDK Implementation Guide

List a Specific Application


Description:

This method returns information about a specific application.


The user who runs this web service requires the following permission in the
Vault:
Audit Users

URL:

http://<IIS_Server_Ip>/PasswordVault/WebServices/
PIMServices.svc/Applications/{AppID}
The following information is required to replace {AppID}:
Parameter

Type

Description

AppID

String

The name of the application about which


information is returned.

Note:

You cannot search for an application


whose name includes @. To find these
applications, list all applications, then find the
specific application in the returned applications
list.
Note: Make sure there are no spaces in the URL.

HTTP
Method:

GET

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

{
}

Privileged Account Security

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

Privileged Account Security

54

55

Privileged Account Security Web Services SDK Implementation Guide

Add Application
Description:

This method adds a new application to the Vault.


The user who adds this application requires the
following permission in the Vault:
Manage Users

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:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the session.

A session token that


was returned
from the Logon
method.

Privileged Account Security

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

Specify fewer than 128


characters.
Do not include
ampersand (&).
Application names can
include @, but a
search for applications
cannot include this
character.
[class=TableTextBullet]
This parameter is required.
Description

String

Description of the
application.
Note: Specify up to 29
characters.

Location

String

Location of the application


in the Vault hierarchy.
Note: To insert a
backslash in the location
path, use a double
backslash.

AccessPermitted
From

Integer

The hour that access is


permitted to the application

Privileged Account Security

0-23

56

57

Privileged Account Security Web Services SDK Implementation Guide

Valid
Values

Parameter

Type

Description

AccessPermitted

Integer

The hour that access is


permitted to the
application.

0-23

ExpirationDate

String

The date when the


application expires.

mm-ddyyyy

Disabled

Boolean

Whether the application is


disabled.
Default=false

true/false

BusinessOwner

String

The first name of the


business owner.

To

FName

Note: Specifies up to 29
characters.
BusinessOwner

String

The last name of the


business owner.

String

The email of the business


owner

String

The phone number of the


business owner.

Business

Note: Specifies up to 24
characters.

Phone

LName
BusinessOwner
Email
BusinessOwner
Phone

Result:

{
}
Status Code: 201
Description: Application added successfully.

Privileged Account Security

Owner

API Commands

List all Authentication Methods of a Specific Application


Description:

This method returns information about all the authentications methods of a


specific application.
The user who runs this web service requires the following permission in the
Vault:
Audit Users

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

The name of the application for which information


about the authentication methods are returned.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

GET

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

{
}

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

Privileged Account Security

58

59

Privileged Account Security Web Services SDK Implementation Guide

Add Authentication
Description:

This method adds a new authentication method to a


specific application in the Vault.
The user who adds this authentication method requires the
following permissions in the Vault:
Manage Users

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

The name of the application for which the user is


adding a new authentication method.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

POST

Header
Input:

The following input parameter is required in the header:


Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

Privileged Account Security

API Commands

Parameters:

The web service parameters depend on the type of authentication


specified in the URL.
For Path authentication:
{
"authentication":{
AuthType : path,
AuthValue : <Path string>,
IsFolder : < true/false >,
"AllowInternalScripts":<true/false>
}
}
The Path authentication syntax has these parts:
Parameter

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

Privileged Account Security

60

61

Privileged Account Security Web Services SDK Implementation Guide

For Hash authentication:


{
"authentication":{
AuthType : hash,
AuthValue : <Hash string>,
"Comment":"<Comment>",
}
}
The Hash authentication syntax has these parts:
Parameter

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

For OS user authentication:


{
"authentication":{
AuthType : osUser,
AuthValue : <OS User Name>
}
}
The OS user authentication syntax has these parts:
Parameter

Type

Description

Valid Values

AuthType

String

The type of
authentication.

machineAddress/osUser/path/
hashValue

This
parameter is
required.

Privileged Account Security

API Commands

Parameter

Type

Description

AuthValue

String

The content of
the
authentication.

Valid Values

This
parameter is
required.

For Address authentication:


{
"authentication":{
AuthType : machineAddress,
AuthValue : <machine address>
}
}
The Address authentication syntax has these parts:
Parameter

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

Privileged Account Security

62

63

Privileged Account Security Web Services SDK Implementation Guide

Delete a Specific Application


Description:

This method deletes a specific application.


The user requires the following permission in the Vault:
Manage Users

URL:

http://<IIS_Server_Ip>/PasswordVault /WebServices/
PIMServices.svc/Applications/{AppID}/
The following information is required to replace {AppID}:
Parameter

Type

Description

AppID

String

The name of the application


that will be deleted.

Note: Make sure there are no spaces in the URL.

HTTP Method:

DELETE

Header Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Authorization

String

The token
that
identifies
the session.

{
}

Result:

{
}
Status Code: 200

Privileged Account Security

Valid
Values
A session
token that
was
returned
from the
Logon
method.

API Commands

Delete a Specific Authentication


Description:

This method deletes a specific authentication method from a defined


application.
The user requires the following permission in the Vault:
Manage Users

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

The ID of the application in which the


authentication method will be deleted.

AuthID

Integer

The unique ID of the specific authentication.

Note: Make sure there are no spaces in the URL.

HTTP
Method:

DELETE

Header
Input:

The following input parameter is required in the header:

Parameters:

Parameter

Type

Description

Valid Values

Authorization

String

The token that


identifies the
session.

A session token that was


returned from the Logon
method.

{
}

Result:

{
}
Status Code: 200

Privileged Account Security

64

65

Privileged Account Security Web Services SDK Implementation Guide

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;

Privileged Account Security

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 =

Privileged Account Security

66

67

Privileged Account Security Web Services SDK Implementation Guide

(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[])

Privileged Account Security

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)

Privileged Account Security

68

69

Privileged Account Security Web Services SDK Implementation Guide

{
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);
}
}
}
}

Privileged Account Security

API Commands

Example 2: Adding an Application/Authentication


The following example shows how the PAS Web Services Access SDK can be
implemented in C# to add an application and its authentication method.
using System
using System;using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Web.Script.Serialization;
namespace WebServiceSDKtest
{
class AIMRestExmpl
{
static void Main(string[] args)
{
//Constants
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 HTTP_SESSION_TOKEN_HEADER =
"Authorization";
const string JSON_GET_ACCOUNT_RES_HEADER =
"application";
const string APPID = "WSTestApp8";
//URI information
const string PVWA_WS_URI =
@"http://192.168.2.13/PasswordVault/WebServices";
const string LOGON_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 AIM_WS_ONE = PVWA_WS_URI +
@"/PIMServices.svc/Applications";
//Variables
WebRequest restRequest;
WebResponse restResponse;
JavaScriptSerializer
jsonSerializer = new
JavaScriptSerializer();
Dictionary<string, object> deserializedJsonDictionary;
string SessionToken = null;
object[] ApplicationIds;
//Authentication Connection String Assembly
Console.WriteLine("Enter Vault Username:"); //Get
username from user
string user = Console.ReadLine();
Console.WriteLine("Enter Vault Password:"); //Get
Password from user
string pass = Console.ReadLine();

Privileged Account Security

70

71

Privileged Account Security Web Services SDK Implementation Guide

string ConnectionString = "{\"username\":\"" + user +


"\",\"password\":\"" + pass + "\"}";
//Token retrieval
try
{
restRequest = WebRequest.Create(LOGON_
AUTHENTICATION_URI); //Specifying URI
restRequest.Method = VERB_METHOD_POST;
restRequest.ContentType = JSON_CONTENT_TYPE;
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())
{
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonSessionToken = rdr.ReadToEnd
();
if(string.IsNullOrEmpty
(rawJsonSessionToken))
{
throw new Exception("Session Token
not created");
}
deserializedJsonDictionary =
(Dictionary<string, object>)jsonSerializer.DeserializeObject
(rawJsonSessionToken);
SessionToken = (string)
deserializedJsonDictionary[JSON_SESSION_TOKEN_HEADER];
if(string.IsNullOrEmpty(SessionToken))
{
throw new Exception("session token was
not created");
}
}
}
}
catch (Exception ex)
{
Console.WriteLine("A Logon Error Has Occured");
HandleError(ex);
return;
}
//Create the AppID request
try
{

Privileged Account Security

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

Privileged Account Security

72

73

Privileged Account Security Web Services SDK Implementation Guide

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)
{

Privileged Account Security

API Commands

Console.WriteLine("An error occured while logging


off");
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 occured: " + res.StatusDescription);
break;
case HttpStatusCode.InternalServerError:
default:
Console.WriteLine("An error occured: "
+ res.StatusDescription);
break;
}
}
else
{
Console.WriteLine("An Error Occured: " +
ex.Message);
}
}
}
}

Privileged Account Security

74

75

Privileged Account Security Web Services SDK Implementation Guide

Troubleshooting
Problem:

A delete request was sent to the Vault, and the following response was
received: 405 Method not allowed.

Solution:

Reinstall WebDAV on the IIS:


1. On the IIS, uninstall the WebDAV component:
2. In the Server Manager, select Roles, and then Web Server (IIS).
3. Click Remove Role Services, then clear WebDAV Publishing, and
remove the component.
4. Install the WebDAV component:
5. Click Add Role Services, then select WebDAV Publishing, and
install the component.
6. You may be required to restart the computer.
Note: WebDAV is installed as part of the PVWA installation. For more
information, refer to the Privileged Account Security Installation Guide.

Privileged Account Security

Você também pode gostar