Policy Analysis API

IBM Security

© Copyright International Business Machines Corporation 2003, 2012. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Purpose of this Document
Overview
API Description
API Example

Purpose of this Document

The Identity Governance provisioning platform controls access to managed resources using the provisioning policies defined in the system. Managed resources can be services such as Identity Manager, Windows NT, Solaris, and other clients. A provisioning policy grants entitlement to these resources based on the person's membership in a particular organization, an organizational role, or the fact that the person is not in any organizational role. Depending on how the provisioning policies are defined, more than one provisioning policy may apply to a given person. A person might be granted access to one service by one provisioning policy, and another service by another provisioning policy. More complex is the case where a person's access to a single service might be controlled by more than one provisioning policy. For example, the person might reside in an organization for which access to a service is controlled by one policy, and the person might have an organizational role for which access to the same service is controlled by another policy. This can make it rather difficult to determine the precise resources to which a given person is entitled. This document describes the Application Programming Interface (API) that is available for clients to analyze the policy enforcement being performed in the system.

Overview

The Policy Analysis API has been developed to provide developers an interface to Identity Governance that will allow them to obtain information about the provisioning policies defined in the system and the access granted a given individual.

The API consists of a set of java classes that retrieve and abstract the provisioning policy information that is used to control access to managed resources. The API does not provide support to allow a client to alter the provisioning policy enforcement in the system. Rather, it simply reports the enforcement as it is defined in the system. The client may use this information for the purposes of auditing, making decisions about potential changes to the policy enforcement in the system, and other tasks.

API Description

The API consists of a main class that provides the methods that can be used by a client to obtain policy enforcement information, and a set of classes the represent the policy enforcement in the system, and that are returned by the methods of the main class. All of these classes can be found in the com.ibm.itim.policy.analysis package.

Figrue 1: Policy Analysis API Class Diagram

The ProvisioningPolicyAnalysis class provides the external interfaces for querying the policy enforcement being performed in the system. It provides interfaces that:

• Return the provisioning policies that apply to a given role.

• Return the entitlements that apply to a given person.

• Return the joined entitlement that represents a given person's entitlement for a given service.

• Return the provisioning parameters of interest for the entitlement that represents a given person's entitlement for a given service.

The other classes in the API represent the output from these interfaces, described below.

The PPAProvisioningPolicy class represents a provisioning policy, including information such as:

• The name of the provisioning policy.

• The priority of the provisioning policy.

• The scope of the provisioning policy.

• The entitlements associated with the provisioning policy.

The PPAEntitlement class represents an entitlement, including information such as:

• The name of the target service.

• The type of the target service, such as all, hosted service, service instance, or service type.

• An indication as to whether or not a workflow process is associated with the entitlement.

• The provisioning parameters associated with the entitlement.

The PPAProvisioningParameter class represents a provisioning parameter, including information such as:

• The name of the provisioning parameter.

• The value(s) of the provisioning parameter.

• The enforcement(s) for the value(s) of the provisioning parameter, such as allowed, default, excluded, or mandatory.

API Example

The following method prints the entitlement a given person has on a given service using the Policy Analysis API.

public static void printEntitlement(PersonEntity person,
      ServiceEntity service) {
   try {
      // get the entitlement for the person and service
      PPAEntitlement entitlement = ProvisioningPolicyAnalysis
         .getEntitlement(person, service);

      // print summary information
      System.out.println("Target Name: " + entitlement.getTargetName());
      System.out.println("Target Type: " + entitlement.getTargetType());
      System.out.println("Workflow required: "
         + entitlement.isWorkflowRequired());
      System.out.println();

      // print parameters
      Collection params = entitlement.getProvisioningParameters();
      Iterator iter = params.iterator();
     while (iter.hasNext()) {
         PPAProvisioningParameter param = (PPAProvisioningParameter) iter.next();
         System.out.println(" Parameter: " + param.getName());

         int[] enforcements = param.getEnforcements();
         Object[] values = param.getValues();

         // print parameter values and associated enforcements
        for (int i = 0; i < enforcements.length; i++) {
            System.out.println("Value: " + values[i].toString()
               + " Enforcement: " + enforcements[i]);
         }

         System.out.println();
      }
   } catch (PPAException ex) {
      System.out.println(ex.getMessage());
   }
}