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
The Identity Governance provisioning platform is designed with extensibility as a primary goal. Many of the architectural components have been built using frameworks that can make use of custom extensions. Often, those extensions need to make use of the data model managed by Identity Governance (i.e., identities and accounts). This document describes the Application Programming Interface (API) that is available for querying elements of this data model.
The Data Services API has been developed to provide the developers of custom extensions to Identity Governance a portable and backwards-compatible interface to the Identity Governance data model.
The API consists of a set of java classes that abstract the more commonly used data model entities in the provisioning process, such as identities, accounts, and services. The classes that make up this API are the same classes the platform uses for its out-of-the-box feature set. A note about security: these classes communicate directly with the data store (directory server) using the platform’s credentials. Clients of this API will be assumed to have an appropriate level of trust. In fact, the platform credentials needed for this trust are obtained within the API code, which requires the client code to be executed within the platform’s environment. The easiest way to deploy client code within the platform’s environment is to have the platform call the code from its published extensions, such as authentication, workflow, and its JavaScript interpreter.
Although the ability to change the data model is provided within this API, it is very important to understand that this ability is not the focus of the API, and in fact, it is highly recommended that a client does not make changes to the data model through this API. The reason for this is that the Data Services API is a low level API that abstracts the physical layout of the data store (directory server), but does not provide a lot of the business logic that the provisioning applications within the platform do. For example, when adding a new person (identity) with the Data Services API, an entry is added to the data store only, but when adding a new person through the Identity Management application, the entry is added to the data store and the process of automatically provisioning the person is performed using the platform’s workflow engine. With that said, in limited situations this ability can safely be used as long as the client understands their effects. For example, the creation of containers in the org chart does not require any special provisioning business logic and can be safely done through this API.
The Data Services API consists of a set of classes that represent the commonly used entities within the Identity Governance data model and a set of classes. All of these classes can be found in the com.ibm.itim.dataservices.model package and its sub-packages.
An entity represents one entry of the data model, such as an identity, account, or service. Once a client obtains an instance of one of these entities, they can retrieve both Identity Governance specific attributes and custom attributes that describe it. An Identity Governance specific attribute is one that is used by Identity Manager for its internal business logic, such as an account’s status, or for navigating relationships, such as determining a business partner’s sponsor. A custom attribute is one that is not used within Identity Governance business logic, but is made available when the customer for business reasons extends the Identity Governance schema. Since these attributes may be relevant to business logic extensions making use of this API, an interface is provided to retrieve them. The UML class diagram in figure 1 below illustrates the primary entities available in the API and their relationships. There are several more entities available in the API that are not shown here. Please see the accompanying API Reference Document for more details on the individual classes.
Figure
1: Primary Entity Class Diagram
There is a consistent framework implemented in this API for querying and operating on entities along with their relationships (the framework is graphically depicted in figure 2 below). This framework is centered on the entity class itself. An entity class is a composite class that holds a reference to a value class that holds the defining attribute information for the entity, and provides access to other related entities with relationship-based interfaces. The relationships and attribute information are cached for the life of the entity, however, every time a relationship is evaluated, the entity, or entities, that participate in that relationship will be loaded from the data store. For example, the reference to the supervisor of a person is cached within the person entity class, but when the client requests the supervisor, the supervisor’s attribute information will be loaded from the data store at the time the supervisor entity is constructed.
To query for entities, the framework provides a search class for each type of entity. The search class will possibly provide canned queries as well as a filtered query where the client can create their own custom query criteria using a string representation of an LDAP filter (see RFC 2254).
To create a new entity in the data store, the framework provides a factory class for each type of entity. The factory class abstracts the physical placement and naming requirements of the data store implementation.
The deletion and modification of entities is made directly on the entity itself. The modification is made by passing an updated value object to the entity. It is important to note that the value object itself tracks the changes that have been made to it by the client. This is done for efficiency and to avoid confusion as to whether a missing attribute in a value object is due to it never being queried to start with (see the SearchParameters class and its use with search classes), or due to the client requesting it to be removed from the data store. Keep this in mind when passing value objects around in client code.
The evaluation of relationships in the data model is commonly achieved by using specific relationship-based methods on entity classes, such as getSupervisor() on a person entity. There is, however, support for additional relationships to be added to the data model to extend its capabilities for customization purposes. This can be achieved by creating a class to represent a relationship and registering it in the meta-data of the data model. Please see the ModelMetaData and Relationship class documentation in the API Reference Document for more details. Once registered, the relationship object can be obtained from an associated entity instance (see DirectoryObjectEntity) and evaluated.
Figure
2: API Framework
The following method uses the Data Services API to print the accounts owned by a specified user.
public static void printAccounts(String rawIdentityDN) {
try {
// create compatible object from raw dn
DistinguishedName identityDN = new DistinguishedName(rawIdentityDN);
// obtain an Identity object needed to look up accounts
PersonEntity identityEntity = new PersonSearch().lookup(identityDN);
if (identityEntity != null) {
// lookup accounts
Collection accounts = new AccountSearch().searchByOwner(identityDN);
Iterator iter = accounts.iterator();
// loop through accounts and print user id and service name
while (iter.hasNext()) {
AccountEntity accountEntity = (AccountEntity) iter.next();
Account account = (Account) accountEntity
.getDirectoryObject();
ServiceEntity serviceEntity = accountEntity.getService();
Service service = (Service) serviceEntity
.getDirectoryObject();
System.out.println("*****Account*****");
System.out.println("User Id: " + account.getUserId());
System.out.println("Service: " + service.getName());
System.out.println();
}
}
} catch (ModelCommunicationException ex) {
System.err.println("Communication Exception: " + ex.toString());
} catch (ObjectNotFoundException ex) {
System.err.println("Object Not Found Exception: " + ex.toString());
}
}