PIM Web Services SDK

PIM Web Services SDK
Implementation Guide
Version 7.2.5
All rights reserved. This document contains information and ideas, which are
proprietary to Cyber-Ark Software. 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 Cyber-Ark Software.
PIMWS007-2-5-1
Copyright © 2000-2013 by Cyber-Ark® Software Ltd. All rights reserved.

2 PIM Web Services SDK Implementation Guide
Table of Contents
Introduction ..........................................................................................3
SDK Supported Platforms ...................................................................3
Using the PIM Web Services SDK .......................................................3
API Commands ......................................................................................4
Cyber-Ark Authentication ............................................................................. 4
Logon....................................................................................................................... 4
Logoff ...................................................................................................................... 5
Policy/ACL Methods ...................................................................................... 5
List .......................................................................................................................... 5
Add .......................................................................................................................... 6
Delete ..................................................................................................................... 7
Account/ACL Methods .................................................................................. 8
List .......................................................................................................................... 8
Add .......................................................................................................................... 9
Delete ................................................................................................................... 10
Usage Examples ................................................................................. 12
The Cyber-Ark Vault

Introduction 3
The PIM Web Services is a RESTful API that enables users to create, list, modify and
delete entities in the PIM Suite from within programs and scripts. The main purpose
of the PIM Web Services is to automate tasks that are usually performed manually
using the UI, and to incorporate them into system and account-provisioning scripts.
SDK Supported Platforms

The PIM 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 PIM Web Services SDK

The PIM Web Services SDK enables you to perform activities on PIM objects via a
REST Web Service interface. Each PIM 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/<Acc
ountAdress>|<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,
containing the value of a session token received from the Logon activity.
The PIM 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 the section Usage Examples, page 12.
The Cyber-Ark Vault

API Commands
The following API commands enable you to implement Cyber-Ark’s PIM Web
Services SDK.
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.
Cyber-Ark Authentication
Logon
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/CyberArkAuthe
nticationService.svc/Logon
HTTP Method
POST
Parameters
{
"username":"<user_name>",
"password":"<password>"
}
The Logon syntax has these parts:
Parameter Type Description Defa

ult
username string The user name. None
password string The user password. None
Result
{
"CyberArkLogonResult":"<Session_Token>"
}
Parameter Type Description Default

CyberArkLogonResult string The session token. None
The Cyber-Ark Vault

API Commands 5
Logoff
This method performs Logoff and removes the Vault session.
URL
http://<IIS_Server_Ip>/PasswordVault/WebServices/auth/Cyberark/CyberArkAuthe
nticationService.svc/Logoff
HTTP Method
POST
Result
{}
Status Code: 200
Description: OK
Policy/ACL Methods
List
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/{PolicyI
d}/PrivilegedCommands
HTTP Method
GET
The List syntax has these parts:
Parameter Type Description Valid Values Default

PolicyId text The Policy Id, provided in Not empty
the URL.
Result
{
"ListPolicyPrivilegedCommandsResult":
[
{"Command":"<command>",
"CommandGroup":"<true/false>",
"Id":"<number>",
"Type":"<Policy/Account>",
"IsGroup":"<true/false>",
"PermissionType":"<Allow/Deny>",
The Cyber-Ark Vault

"PolicyId":"<policyID>",
"Restrictions":"<restrictions string, delimited by ;>",
"UserName":"<userName>"},
{…},
{…}
]
}
Status Code: 200
Description: OK
Add
This method adds a new privileged command rule to the policy.
URL
d}/PrivilegedCommands
HTTP Method
PUT
Parameters
{
"Command":"<Command>",
"CommandGroup":<true/false>,
"Restrictions":"<Restrictions>",
"UserName":"<UserName>"
}
The Add syntax has these parts:

Command text The command. Not empty
CommandGroup bool Whether or not this True/False
is a command group.
PermissionType text Allow or Deny Allow/Deny
command.
PolicyId text The Policy Id, Not empty
provided in the URL.
Restrictions text A restrictions string. <restrictionName
>=<Value>;<… or
The Cyber-Ark Vault

API Commands 7

empty
UserName text The user this rule User name, or "*"
applies to. for all users
Result
{
"AddPolicyPrivilegedCommandResult":
{
"Command":"<command>",
"Id":"<number>",
"Restrictions":"<restrictions string, delimeted by ;>",
"UserName":"<userName>"}
}
Status Code: 201
Description: Policy ACL was added successfully
Delete
This method deletes all privileged commands rules associated with the policy.
URL
d}/PrivilegedCommands/{Id}
HTTP Method
DELETE
The Delete syntax has these parts:

PolicyId text The Policy Id, provided Not empty
in the URL.
Id number The Rule Id, provided in Not empty
the URL.
The Cyber-Ark Vault

Return Value
Status Code: 204 (empty content)
Description: Policy ACL with Id <Id> was deleted successfully
Account/ACL Methods
List
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/{Acc
ountAdress}|{AccountUserName}|{AccountPolicyId}/PrivilegedCommands
HTTP Method
GET
The List syntax has these parts:

AccountPolicyId text The Policy Id of the
account, provided in the
URL.
AccountAdress text The Address of the account, Not empty
AccountUserName text The User Name of the Not empty
URL.
Result
{
"ListAccountPrivilegedCommandsResult":
[
{"Command":"<command>",
"Id":"<number>",
"UserName":"<userName>"},
The Cyber-Ark Vault

API Commands 9
{…},
{…}
]
}
Status Code: 200
Description: OK
Add
This method adds a new privileged command rule to the account.
URL
http://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Account/{Acc
ountAdress}|{AccountUserName}|{AccountPolicyId}/PrivilegedCommands
HTTP Method
PUT
Parameters
{
"Command":"<Command>",
"CommandGroup":<true/false>,
"Restrictions":"<Restrictions>",
"UserName":"<UserName>"
}
The Add syntax has these parts:

account, provided in
the URL.
AccountAdress text The Address of the Not empty
the URL.
the URL.
Command text The command. Not empty
CommandGroup bool Whether or not this is True/False
a command group.
PermissionType text Allow or Deny Allow/Deny
command.
The Cyber-Ark Vault


Restrictions text A restrictions string. <restrictionName>=
<Value>;<… or empty
UserName text The user this rule User name, or "*" for
applies to. all users
Result
{
"AddAccountPrivilegedCommandResult":
{
"Command":"<command>",
"Id":"<number>",
"UserName":"<userName>"}
}
Status Code: 201
Description: Policy ACL added successfully
Delete
This method deletes privileged commands rules associated with the policy.
URL
d}/PrivilegedCommands/{Id}
HTTP Method
DELETE
The Delete syntax has these parts:

URL.
AccountAdress text The Address of the Not empty
URL.
The Cyber-Ark Vault

API Commands 11

URL.
Id number The Id of the Rule, Not empty
Return Value
Status Code: 204 (empty content)
Description: Policy ACL with Id <Id> was deleted successfully.
The Cyber-Ark Vault

Usage Examples
The following example shows how the PIM Web Services Access SDK can be
implemented in C#.
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_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;
WebResponse restResponse;
// For JSON serialization
JavaScriptSerializer jsonSerializer = new
JavaScriptSerializer();
Dictionary<string, object> deserializedJsonDictionary;
// Workflow objects
string sessionToken = null;
object[] AccountAcls;
// Workflow
//===========
The Cyber-Ark Vault

Usage Examples 13
// 0. Get Credentials from user:

Console.WriteLine("Enter Username:");
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 = (Dictionary<string,
object>)jsonSerializer.DeserializeObject(rawJsonSessionToken);
sessionToken =
(string)deserializedJsonDictionary[JSON_SESSION_TOKEN_HEADER];
// verify that the result isn’t empty.

if (string.IsNullOrEmpty(sessionToken))
throw new Exception("session token was not created");
}
}
}
catch (Exception ex)
{
Console.WriteLine("An error occurred on Logon");
HandleError(ex);
return;
}
The Cyber-Ark Vault

// 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.Headers[HTTP_SESSION_TOKEN_HEADER] = sessionToken;
// we add the session token to each request.

{
{
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[])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"]);
}
}
}
}
{
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.Headers[HTTP_SESSION_TOKEN_HEADER] = sessionToken;
// we add the session token to each request.
The Cyber-Ark Vault

Usage Examples 15
using (Stream requestStream = restRequest.GetRequestStream())

{
byte[] inputStringBytes = Encoding.UTF8.GetBytes("");
requestStream.Write(inputStringBytes, 0,
inputStringBytes.Length);
}
{
{
Encoding.UTF8);
string rawJsonResult = rdr.ReadToEnd();
}
}
}
{
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);
}
}
}
}
The Cyber-Ark Vault

PIM Web Services SDK

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

PIM Web Services SDK

Загружено:

Авторское право:

Доступные форматы

PIM Web Services SDK

Copyright © 2000-2013 by Cyber-Ark® Software Ltd. All rights reserved.

The Cyber-Ark Vault

SDK Supported Platforms

Using the PIM Web Services SDK

The Cyber-Ark Vault

Parameter Type Description Defa

Parameter Type Description Default

The Cyber-Ark Vault

Parameter Type Description Valid Values Default

The Cyber-Ark Vault

Parameter Type Description Valid Values Default

The Cyber-Ark Vault

Parameter Type Description Valid Values Default

The Delete syntax has these parts:

Parameter Type Description Valid Values Default

The Cyber-Ark Vault

The List syntax has these parts:

Parameter Type Description Valid Values Default

The Cyber-Ark Vault

Parameter Type Description Valid Values Default

The Cyber-Ark Vault

Parameter Type Description Valid Values Default

Parameter Type Description Valid Values Default

The Cyber-Ark Vault

AccountUserName text The User Name of the Not empty

The Cyber-Ark Vault

The Cyber-Ark Vault

// 0. Get Credentials from user:

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

// 1. Get the token

using (restResponse = restRequest.GetResponse())

// verify that it returned a result.

// deserialize the json and take the value from it.

// verify that the result isn’t empty.

The Cyber-Ark Vault

// 2. Make the request (for instance, retrieve all account acls)

using (restResponse = restRequest.GetResponse())

// verify that it returned a result.

// deserialize the json and take the value from it.

The Cyber-Ark Vault

using (Stream requestStream = restRequest.GetRequestStream())

private static void HandleError(Exception ex)

The Cyber-Ark Vault

Вам также может понравиться