CEPM DotNet Developer Guide
PEP API Quick Start Guide
Download this chapter
PEP API Quick Start GuidePEP API Quick Start Guide
Download the complete book
CEPM DotNet Developer GuideCEPM DotNet Developer Guide (PDF - 1 MB)
 Feedback

Table Of Contents

PEP API Quick Start Guide

Compile and Run the PEP Simulator

IsUserAccessAllowed()

IsUserAccessAllowed(subject, resource, action)

Sample Code

GetDecisions()

GetDecisions(subject, resource, action)

Sample Code

GetPermissibleResourcesForUsers()

GetPermissibleResourcesForUsers(subject, resource)

Sample Code

GetRolesAllowedForResource()

GetRolesAllowedForResource(resource)

Sample Code

GetAuthorizedDecisions()


PEP API Quick Start Guide

This chapter provides use cases that will teach you how to work with the PEP Simulator and develop code with some of the more commonly used PEP API methods This includes the newly introduced getAuthorizedDecisions() method.

For more information on how to work with the PEP APIs, refer to Appendix A, "PEP API Reference Guide." The guide contains documentation for over 50 PEP API methods. For information on the full set of PEP APIs, refer to the PEP API Javadocs.

Compile and Run the PEP Simulator

The PEP Simulator is a CEPM utility that allows developers to quickly test entitlement policies defined within the administration console. The utility also serves as test bed for working with the PEP APIs.

To edit, compile, and run the PEP Simulator, you must:

Step 1 Unzip PEPSimulator-V3.3.0.0.zip.

Step 2 Open the command prompt and navigate to the PEP Simulator directory.

Step 3 Edit the PEPSimulator.cs file. Replacing the username and resource values with the user and resource names you want to test. For example: 

String username = "jdoe";

String resource = "Prime group:Prime portal:Account 1";

Step 4 Save the updated PEPSimulator.cs file.

Step 5 Enter compile

Step 6 Enter run

The PEP Simulator returns a True or False result based on the applicable policies for the user and resource.

Repeat steps 4 through 7 to test different user and resource combinations.

IsUserAccessAllowed()

This method determines whether a user is authorized to perform an action on a specific resource and returns a Boolean result (True or False). This use case uses the most common form of the IsUserAccessAllowed() method, which passes subject, resource, and action information. For more information on the other overloaded variations of this method, refer to Appendix A, "PEP API Reference Guide."

IsUserAccessAllowed(subject, resource, action)

•subject—String value containing user ID .

Example:

jdoe

•resource—String value containing fully qualified resource name.

Example:

Prime group:Prime portal:Account 1

•action—String value containing action for the resource.

Example:

buy, sell, read, write, delete, and any.

•Return type—Boolean (Permit = true, Deny / Not Applicable = false)

Sample Code 

//Define subject, resource, and action values

String username = "jdoe";

String resource = "Prime group:Prime portal:Account 1";

String action = "any";

//Initialize Com.Cisco.Epm Authorization Manager

IAuthorizationManager mgr = 
AuthorizationManagerFactory.GetInstance().GetAuthorizationManager();

//Invoke IsUserAccessAllowed() method, providing user, resource, and action information

Boolean decision = mgr.IsUserAccessAllowed(username,resource,action);

//Print decision

Console.WriteLine("Is "+username+" allowed to access "+resource+"? "+decision);

To perform this check, you must:

Step 1 Open PEPSimulator.cs in a text editor.

Step 2 Edit the file using the sample code as a guide.

Step 3 Save the changes.

Step 4 Enter compile

Step 5 Enter run

GetDecisions()

Similar to IsUserAccessAllowed() method, determines whether a user is authorized to perform an action on a specific resource. However, GetDecisions() returns the full XACML response instead of a Boolean result. This use cases uses the most common form of the GetDecisions() method, which passes subject, resource, and action information. For more information on the other overloaded variations of this method, refer to Appendix A, "PEP API Reference Guide."

GetDecisions(subject, resource, action)

•subject—String value containing user ID.

Example:

jdoe

•resource—String value containing fully qualified resource name.

Example:

Prime group:Prime portal:Account 1

•action—String value containing action for the resource.

Example:

buy, sell, read, write, delete, and any.

•Return type—XacmlResponse containing the full XACML response from the PDP

Sample Code 

//Define subject, resource, and action values

String username = "jdoe";

String resource = "Prime group:Prime portal:Account 1";

String action = "any";

//Initialize Com.Cisco.Epm Authorization Manager

IAuthorizationManager mgr = 
AuthorizationManagerFactory.GetInstance().GetAuthorizationManager();

//Invoke GetDecisions() method, providing user, resource, and action

XacmlResponse pdpResponse = mgr.GetDecisions(username,resource,action);

//Use XacmlResponse methods to print the decision and the entire XACML response

Console.WriteLine("Decision: "+pdpResponse.GetDecision());

Console.WriteLine("XACML Response: ");

Console.WriteLine(pdpResponse.toString());

To perform this check, you must:

Step 1 Open PEPSimulator.cs in a text editor.

Step 2 Edit the file using the sample code as a guide.

Step 3 Save the changes.

Step 4 Enter compile

Step 5 Enter run

GetPermissibleResourcesForUsers()

This method returns a list of a user's permitted subresources for a specified resource. This use case uses the most common form of the GetPermissibleResourcesForUsers() method, which passes subject and resource information. For more information on the other overloaded variations of this method, refer to Appendix A, "PEP API Reference Guide."

GetPermissibleResourcesForUsers(subject, resource)

•subject: String value containing user ID.

Example:

jdoe

•resource: String value containing fully qualified resource name.

Example:

Prime group:Prime portal

•Return type: String[] array containing all of the permissible child resources

Sample Code 

//Define subject and resource values 
String username = "jdoe"; 
String resource = "Prime group:Prime portal";

//Initialize Com.Cisco.Epm Authorization Manager 
IAuthorizationManager mgr = 
AuthorizationManagerFactory.GetInstance().GetAuthorizationManager();

//Invoke GetPermissibleResourcesForUsers() method, providing user and resource 
String [] str = mgr.GetPermissibleResourcesForUser(username,resource);

//Iterate through String array and print permissible resources for user  
if(str!=null){ 
   Console.WriteLine(username+" is allowed to access the following resources: ");

   for(int i=0;i<str.length;i++){ 
      Console.WriteLine("Resource: "+str[i]); 
   } 
}

To list a user's permitted subresources for a given resource, follow these steps:

Step 1 Open PEPSimulator.cs in a text editor.

Step 2 Edit the file using the sample code as a guide.

Step 3 Save the changes.

Step 4 Enter compile

Step 5 Enter run

GetRolesAllowedForResource()

This method returns a list of permissible roles for a resource. This use case uses the most common form of the GetRolesAllowedForResource() method which passes resource information. For more information on the other overloaded variations of this method, refer to Appendix A, "PEP API Reference Guide."

GetRolesAllowedForResource(resource)

•resource—String value containing fully qualified resource name (for example, Prime group:Prime portal:Account 1)

•Return type—String[] array containing all roles allowed to access resource

Sample Code 

//Define resource values 
String resource = "Prime group:Prime portal:Account 1";

//Initialize Com.Cisco.Epm Authorization Manager 
IAuthorizationManager mgr = 
AuthorizationManagerFactory.GetInstance().GetAuthorizationManager();

//Invoke GetRolesAllowedForResource () method, providing resource name 
String [] str = mgr.GetRolesAllowedForResource(resource);

//Iterate through String array and print roles allowed to access resource 
if(str!=null){ 
   Console.WriteLine("The following roles are allowed access to "+resource+":");

   for(int i=0;i<str.length;i++){ 
      Console.WriteLine("Role: "+str[i]); 
   } 
}

To list the permissible roles of a resource, you must:

Step 1 Open PEPSimulator.cs in a text editor.

Step 2 Edit the file using the sample code as a guide.

Step 3 Save the changes.

Step 4 Enter compile

Step 5 Enter run

GetAuthorizedDecisions()

This is a generic method which takes XACML request as its input parameter. This single API method replaces all existing PEP methods such as IsUserAccessAllowed(), IsRoleAccessAllowed(), GetDecisions(), and so on.

To use this method:

Step 1 Define the following input parameters: 

String subject = "Mary";

String resource = "Prime group:Prime portal:Send Trades";

String action = "any";

HashTable<String, String> envMap = new HashTable<String, String>();

envMap.Add(XacmlConstant.LEVEL, "-1");

String roleBundle = "Default";

String context = "Global Context:Global Context";

Step 2 Initialize IAuthorization Manager. 

IAuthorizationManager mgr = 
AuthorizationManagerFactory.GetInstance().GetAuthorizationManager();

Step 3 Invoke the XacmlGenerator to create the XacmlRequest. 

Com.Cisco.Epm.Xacml.XACMLGenerator generator = new XACMLGenerator();

Step 4 Create the XacmlRequest. 

Com.Cisco.Epm.Xacml.XacmlRequest xacmlRequest = generator.CreateXacmlRequest(subject, 
resource, action, envMap, roleBundle, context, XacmlConstant.SUBJECTID)

If the subject is a role, the XacmlConstant will be ROLEID, in case of a group, it will be GROUPID.

The Xacml Generator will consider the above mentioned parameters and generate a XacmlRequest which may look like: 

<Request>

<Subject SubjectCategory="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject">

<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" 
DataType="http://www.w3.org/2001/XMLSchema#string" Issuer="requestor">

<AttributeValue>Mary</AttributeValue>

</Attribute>

</Subject>

<Resource>

<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" 
DataType="http://www.w3.org/2001/XMLSchema#string">

<AttributeValue>Prime group:Prime portal:Send Trades</AttributeValue>

</Attribute>

</Resource>

<Action>

<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" 
DataType="http://www.w3.org/2001/XMLSchema#string">

<AttributeValue>any</AttributeValue>

</Attribute>

</Action>

<Environment>

<Attribute AttributeId="Key" DataType="http://www.w3.org/2001/XMLSchema#string">

<AttributeValue>value</AttributeValue>

</Attribute>

<Attribute AttributeId="urn:cisco:cepm:3.3:xacml:context-name" 
DataType="http://www.w3.org/2001/XMLSchema#string">

<AttributeValue>Global Context:Global Context</AttributeValue>

</Attribute>

<Attribute AttributeId="urn:cisco:cepm:3.3:xacml:rolebundle-name" 
DataType="http://www.w3.org/2001/XMLSchema#string">

<AttributeValue>Default</AttributeValue>

</Attribute>

</Environment>

</Request>

Step 5 Invoke the GetAuthorizedDecisions() method by passing the XacmlRequest as an inputparameter. 

Com.Cisco.Epm.Xacml.XacmlResponse xacmlResponse = 
mgr.GetAuthorizedDecisions(xacmlRequest);

Step 6 Invoke the GetResults() to get the XacmlResponse. 

Com.Cisco.Epm.Xacml.Result results[] = xacmlResponse.GetResults();

This response contains results of all the child resources created under the specified resource Send Trades because the value implemented for level is -1. This gives the XacmlResponse which may look like: 

<Response>

<Result ResourceId="Prime group:Prime portal:Send Trades:Buy Trades">

<Decision>Permit</Decision>

<Status>

<StatusCode Value="urn:cisco:cepm:3.3:xacml:status:ok"/>

<StatusMessage>Request is successful</StatusMessage>

<StatusDetail>Response from PDP</StatusDetail>

</Status>

<Obligations>

<Obligation FulfillOn="Permit" ObligationId="urn:cisco:cepm:3.3:xacml:response-qualifier">

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:is-resource">

<AttributeValue 
DataType="http://www.w3.org/2001/XMLSchema#string">resource</AttributeValue>

</AttributeAssignment>

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:resource-type-name">

<AttributeValue 
DataType="http://www.w3.org/2001/XMLSchema#string">GLOBAL:UNTYPE</AttributeValue>

</AttributeAssignment>

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:ttl">

<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">0</AttributeValue>

</AttributeAssignment>

</Obligation>

</Obligations>

</Result>

<Result ResourceId="Prime group:Prime portal:Send Trades">

<Decision>Permit</Decision>

<Status>

<StatusCode Value="urn:cisco:cepm:3.3:xacml:status:ok"/>

<StatusMessage>Request is successful</StatusMessage>

<StatusDetail>Response from PDP</StatusDetail>

</Status>

<Obligations>

<Obligation FulfillOn="Permit" ObligationId="urn:cisco:cepm:3.3:xacml:response-qualifier">

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:is-resource">

<AttributeValue 
DataType="http://www.w3.org/2001/XMLSchema#string">resource</AttributeValue>

</AttributeAssignment>

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:resource-type-name">

<AttributeValue 
DataType="http://www.w3.org/2001/XMLSchema#string">GLOBAL:UNTYPE</AttributeValue>

</AttributeAssignment>

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:ttl">

<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">0</AttributeValue>

</AttributeAssignment>

</Obligation>

</Obligations>

</Result>

<Result ResourceId="Prime group:Prime portal:Send Trades:Sell Trades">

<Decision>Permit</Decision>

<Status>

<StatusCode Value="urn:cisco:cepm:3.3:xacml:status:ok"/>

<StatusMessage>Request is successful</StatusMessage>

<StatusDetail>Response from PDP</StatusDetail>

</Status>

<Obligations>

<Obligation FulfillOn="Permit" ObligationId="urn:cisco:cepm:3.3:xacml:response-qualifier">

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:is-resource">

<AttributeValue 
DataType="http://www.w3.org/2001/XMLSchema#string">resource</AttributeValue>

</AttributeAssignment>

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:resource-type-name">

<AttributeValue 
DataType="http://www.w3.org/2001/XMLSchema#string">GLOBAL:UNTYPE</AttributeValue>

</AttributeAssignment>

<AttributeAssignment AttributeId="urn:cisco:cepm:3.3:xacml:ttl">

<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">0</AttributeValue>

</AttributeAssignment>

</Obligation>

</Obligations>

</Result>

</Response>

Step 7 Retrieve the resource ID, decisions, and obligations. 

for (Result result : results) {

	Console.WriteLine("Resource name[" + result.GetResourceId() + "]");

	Console.WriteLine("Decision [" + result.GetDecision() + "]");

Obligation obligations[] = result.GetObligations();

	foreach(Obligation obligation in obligations) {

	AttributeAssignment[] assignments = obligation.GetAttributeAssignment();

			foreach(AttributeAssignment assignment in assignments) {

			Console.WriteLine("Attribute ID[" + assignment.GetAttributeID() + "]");

			Console.WriteLine("Attribute ID[" + assignment.GetValue() + "]");

The result includes the decisions and obligations for the specified resource and its child resources, such as Buy Trades and Sell Trades. 

Resource name[Prime group:Prime portal:Send Trades]

Decision [0]

Attribute ID[urn:cisco:cepm:3.3:xacml:is-resource]

Attribute ID[resource]

Attribute ID[urn:cisco:cepm:3.3:xacml:resource-type-name]

Attribute ID[GLOBAL:UNTYPE]

Attribute ID[urn:cisco:cepm:3.3:xacml:ttl]

Attribute ID[0]

Resource name[Prime group:Prime portal:Send Trades:Buy Trades]

Decision [0]

Attribute ID[urn:cisco:cepm:3.3:xacml:is-resource]

Attribute ID[resource]

Attribute ID[urn:cisco:cepm:3.3:xacml:resource-type-name]

Attribute ID[GLOBAL:UNTYPE]

Attribute ID[urn:cisco:cepm:3.3:xacml:ttl]

Attribute ID[0]

Resource name[Prime group:Prime portal:Send Trades:Sell Trades]

Decision [0]

Attribute ID[urn:cisco:cepm:3.3:xacml:is-resource]

Attribute ID[resource]

Attribute ID[urn:cisco:cepm:3.3:xacml:resource-type-name]

Attribute ID[GLOBAL:UNTYPE]

Attribute ID[urn:cisco:cepm:3.3:xacml:ttl]

Attribute ID[0]

Where Decision[0] means permit decision. If the decision is deny it will be `1'.