Skip Headers
Oracle® Fusion Middleware Developer's Guide for Identity Governance Framework
11g Release 1 (11.1.1)

Part Number E16588-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
PDF · Mobi · ePub

4 Migrating to Identity Directory API

This chapter describes how to migrate applications from the User and Role API to the Identity Directory API. This chapter contains the following topics:

4.1 Introduction

If you have an application that uses the User and Role API described in Oracle Fusion Middleware Application Security Guide and Oracle Fusion Middleware User and Role Java API Reference for Oracle Platform Security Services, you can modify it to use Identity Directory API instead.

The Identity Directory API also picks up the LDAP-based identity store confirmation from the jps-config file. As such, when migrating an application from the User and Role API to the Identity Directory API you do not need to change the configuration in the jps-config file.

Applications that initialize the User and Role API with a programmatic configuration can use a similar method to initialize the Identity Directory API. For more information, see Section 2.4.3, "Initialize and Obtain In-Memory Identity Directory Handle".

4.2 Migrate the Application

Application migrating from the User and Role API to the Identity Directory API need to make the following code changes:

4.2.1 API Initialization

Process is similar to using IdentityStoreService.GetIdmStore() for getting oracle.security.idm.IdentityStore handle. Identity Directory API uses IdentityStoreService.getIdentityStore() to get IdentityDirectory handle. For example:

import oracle.igf.ids.IdentityDirectory;
import oracle.igf.ids.IDSException;
import oracle.security.jps.JpsContext;
import oracle.security.jps.JpsContextFactory;
import oracle.security.jps.service.idstore.IdentityStoreService;

// Get IdentityDirectory from JpsContext
JpsContext context = JpsContextFactory.getContextFactory().getContext();
IdentityStoreService idstore = (IdentityStoreService)
context.getServiceInstance(IdentityStoreService.class);
Identity Directory ids = idstore.getIdentityStore();

4.2.2 Getting UserManager and GroupManager Handle

User related CRUD operations can be performed with oracle.igf.ids.UserManager and Role related CRUD operations can be performed with oracle.igf.ids.GroupManager. UserManager and GroupManager handles can be obtained from IdentityDirectory object. For example:

import oracle.igf.ids.UserManager;
import oracle.igf.ids.GroupManager;

// Get UserManager and GroupManager handles
        UserManager uMgr = ids.getUserManager();
        GroupManager gMgr = ids.getGroupManager();

4.2.3 Search Filter

A simple or complex search filter can be built using oracle.igf.ids.SearchFilter. For example:

import oracle.igf.ids.SearchFilter;

// Simple search filter for (firstname equals "john")

SearchFilter filter1 = new SearchFilter("firstname", 
SearchFilter.Operator.EQUALS, "john");

        // Complex search filter for 
        ((title contains "manager") and (org equals "amer")) or 
((title contains "senior manager") and (org equals "apac"))

            SearchFilter filter = new SearchFilter(
                SearchFilter.LogicalOp.OR,
                new SearchFilter(SearchFilter.LogicalOp.AND,
                  new SearchFilter("manager", SearchFilter.Operator.CONTAINS,
 "manager"),
                  new SearchFilter("org", SearchFilter.Operator.EQUALS, "amer")),
                new SearchFilter(SearchFilter.LogicalOp.AND,
                  new SearchFilter("manager", SearchFilter.Operator.CONTAINS,
 "senior manager"),
                  new SearchFilter("org", SearchFilter.Operator.EQUALS, "apac")));
           

4.2.4 CRUD Operations

Create/Read/Update/Delete (CRUD) operations on User, Group, Org, and generic entities are discussed in the following sections:

4.2.4.1 Finding a User

The following APIs are used for finding a user:

  • Get user for given principal identifier. For example:

    User getUser(Principal principal, ReadOptions opts)
    
  • Search for user matching given id attribute value that uniquely identifies the user. For example:

    User searchUser(String id, ReadOptions opts)
    
  • Finds user matching given attribute name and value. For example:

    User searchUser(String attrName, String attrVal, ReadOptions opts)
    
  • Search for user matching given GUID value that uniquely identifies the user. For example:

    searchUserByGuid(String guid, ReadOptions opts) 
    

4.2.4.2 Searching Users

The following is an example of the API for searching a user.

ResultSet<User> searchUsers(SearchFilter filter, SearchOptions opts)

4.2.4.3 Creating a User

The following is an example of the API for creating a user.

Principal createUser(List<Attribute> attrVals, CreateOptions opts)

4.2.4.4 Deleting a User

The following are examples of the API for deleting a user.

  • Delete the user given the principal identifier.

    void deleteUser(Principal principal, DeleteOptions opts)
    
  • Delete the user given the id attribute value.

    void deleteUser(String id, DeleteOptions opts)
    

4.2.4.5 Authenticating a User

The following are examples of the API for user authentication.

  • Authenticate the user matching the given id attribute value.

    User authenticateUser(String id, char[] password, ReadOptions opts)
    
  • Authenticate the user for given principal identifier.

    boolean authenticateUser(Principal principal, char[] password)
    

4.2.4.6 Modifying Users and Managing Related Entities

The APIs for modifying user attributes and for getting the related entities are in User object instead of UserManager.

4.2.4.6.1 Modifying a User

The following are examples of the API for modifying a user.

  • Modify user attributes.

    void User.modify(List<ModAttribute> attrVals, ModifyOptions opts) 
    
  • Set the user attribute value.

    void User.setAttributeValue(String attrName, String attrVal, ModifyOptions opts)
    
4.2.4.6.2 Managing Related Entities

The following are examples of the APIs for managing entities.

  • Get the management chain.

    ResultSet<User> getManagementChain(int nLevels, SearchOptions opts) 
    
  • Check if the given user is manager of this user.

    boolean isManager(User user, boolean direct, ReadOptions opts)
    
  • Set the given user as manager of this user.

    void setManager(User user, ModifyOptions opts)
    
  • Get all the reportees of this user.

    ResultSet<User> getReportees(int nLevels,
     SearchFilter targetFilter, SearchOptions opts) 
    
  • Get all the groups this user is a member of and matching the given filter criteria.

    ResultSet<Group> getMemberOfGroups(int
     nLevels, SearchFilter targetFilter, SearchOptions opts)
     
    
  • Check if this user is a member of the given group.

    boolean isMemberOf(Group group, boolean direct, ReadOptions opts) 
    
  • Add this user as a member to given group.

    void addMemberOf(Group group, ModifyOptions opts) 
    
  • Delete this user as a member to given group.

    void deleteMemberOf(Group group, ModifyOptions opts)
    

4.3 Comparison Between User and Role API and IDS API

The differences between the User and Role API and Identity Directory API are discussed in the following topics:

4.3.1 User-Related APIs

Table 4-1 provides a comparison between the User-related API method and the corresponding Identity Directory API API method.

Table 4-1 Comparison Between User-Related API and Identity Directory API

Functionality User/Role API Method Identity Directory API Method

User Creation

User UserManager.createUser(String name, char[] password)

User UserManager.createUser(String name, char[] password, PropertySet pset)

Principal UserManager.createUser(List<Attribute> attrVals, CreateOptions opts)

Delete User

void UserManager.dropUser(UserProfile user)

void UserManager.dropUser(User user);

void UserManager.deleteUser(Principal principal, DeleteOptions opts)

void UserManager.deleteUser(String id, DeleteOptions opts)

Authenticate User

User UserManager.authenticateUser(String user_id, char[] passwd)

User UserManager.authenticateUser(User user, char[] passwd)

User UserManager.authenticateUser(String user_id, String authProperty, char[] passwd)

User UserManager.authenticateUser(String id, char[] password, ReadOptions opts)

boolean UserManager.authenticateUser(Principal principal, char[] password)

Check if create User is supported

boolean UserManager.isCreateUserSupported()

boolean UserManager.getCapabilities().isCreateCapable()

Check if modify User is supported

boolean UserManager.isModifyUserSupported()

boolean UserManager.getCapabilities().isUpdateCapable()

Check if drop User is supported

boolean UserManager.isDropUserSupported()

boolean UserManager.getCapabilities().isDeleteCapable()

Search Users by given search criteria

SearchResponse IdentityStore.searchUsers(SearchParameters params)

ResultSet<User> UserManager.searchUsers(SearchFilter filter, SearchOptions opts)

Search an User by name/uniquename /guid

User IdentityStore.searchUser(String name)

User UserManager.searchUser(String id, ReadOptions opts)

User UserManager.searchUser(String attrName, String attrVal, ReadOptions opts)

Check if User exists in the repository for a given User object

boolean IdentityStore.exists (User user)

User.getPrincipal() if the following method returns null user doesn't exist; otherwise exists

User getUser(Principal principal, ReadOptions opts)

Simple search filter (search based on a single attribute name, type and value)

SimpleSearchFilter

SearchFilter(String propertyName, Operator op, String propertyVal)

Complex Search Filter (search based on more than one attribute with filter conditions and nested filters)

ComplextSearchFilter

SearchFilter(LogicalOp op, SearchFilter... searchFilters)

Getting a property value for a given property name

String User.getPropertyVal(String propName)

(User Role API fetches the attribute values from cache. If it misses cache, it fetches from repository)

String User.getAttributeValue(String attrName)

Limitation: Returns attribute values from User object that has been already fetched from the repository.

Getting the User property for a given property name

Property User.getProperty(String propName)

Attribute User.getAttribute(String attrName)

Getting the user properties for a given set of property names

Map User.getProperties()

Map<String, Attribute> User.getAllAttributes()

Get all user properties from the repository for a user

PropertySet User.getAllUserProperties()

Map<String, Attribute> User.getAllAttributes()

Get all user property names from the schema

List IdentityStore.getUserPropertyNames()

Returns the names of all the properties in the schema

List<String> UserManager.getEntityAttributes()

Changing the attribute value in the repository of an user

void User.setProperty(ModProperty mprop)

void User.setAttributeValue(String attrName, String attrVal, ModifyOptions opts)

Changing the set of attribute values in the repository for an user

void User.setProperties(ModProperty[] modPropObjs)

void User.setProperties(LdapContext ctx, ModProperty[] modPropObjs)

void User.modify(List<ModAttribute> attrVals, ModifyOptions opts)

Get all the reportees of an User either direct or indirect

SearchResponse User.getReportees(boolean direct)

ResultSet<User> User.getReportees(int nLevels, SearchFilter targetFilter, SearchOptions opts)

Get Management chain of an user

List User.getManagementChain(int max, String upToManagerName, String upToTitle)

ResultSet<User> User.getManagementChain(int nLevels, SearchOptions opts)

List<User> User.getManagementChain(int nLevels, String manager, String title, SearchOptions opts)

Get/Set of Binary Attributes

Available

Property in User/Role API supports binary attributes

byte[] user.getJPEGPhoto()

void user.setJPEGPhoto(String imgpath)

Returns base64 encoded value

While setting the value either base64 encoded value or byte[] can be used for creating ModAttribute.

Selecting the Realm

Available

env.put(OIDIdentityStoreFactory.RT_SUBSCRIBER_NAME, "<realm dn>");

IdentityStoreFactory.getIdentityStoreInstance(env);

This is part of IDS Operational configuration. At API level searchbase and createbase can be specified as well.


4.3.2 Role-Related APIs

Table 4-2 provides a comparison between the Role-related API method and the corresponding Identity Directory API method.

Table 4-2 Comparison Between Role-Related API and Identity Directory API

Functionality User/Role API Method Identity Directory API Method

Creating a Role

Role RoleManager.createRole(String name, int scope)

Role RoleManager.createRole(String name)

Principal GroupManager.createGroup(List<Attribute> attrVals, CreateOptions opts)

Deleting a Role

void RoleManager.dropRole(RoleProfile role)

void RoleManager.dropRole(Role role)

void GroupManager.deleteGroup(Principal principal, DeleteOptions opts)

Check if create role is supported

boolean RoleManager.isCreateRoleSupported()

boolean GroupManager.getCapabilities().isCreateCapable()

Check if modify role is supported

boolean RoleManager.isModifyRoleSupported()

boolean GroupManager.getCapabilities().isUpdateCapable()

Check if delete role is supported

boolean RoleManager.isDropRoleSupported()

boolean GroupManager.getCapabilities().isDeleteCapable()

Is the Group owned by a User

boolean RoleManager.isGranted(Role parent, Principal principal)

boolean Group.isMember(User user, boolean direct, ReadOptions opts)

boolean User.isMemberOf(Group group, boolean direct, ReadOptions opts)

Is the Group owned by a User

boolean RoleManager.isOwnedBy(Role parent, Principal principal)

boolean User.isOwnerOf(Group group, boolean direct, ReadOptions opts)

Is the group managed by a User

boolean RoleManager.isManagedBy(Role parent, Principal principal)

Not supported

Get all the members of a Role either direct / indirect

SearchResponse Role.getGrantees(SearchFilter filter, boolean direct)

ResultSet<User> Group.getMembers(int nLevels, SearchFilter targetFilter, SearchOptions opts)

Add an user as a member to a role

void RoleManager.grantRole(Role parent, Principal principal)

void Group.addMember(User user, ModifyOptions opts)

Remove a user from being member of a role

void RoleManager.revokeRole(Role parent, Principal principal)

void Group.deleteMember(User user, ModifyOptions opts)

Get all the owners of a specific Role either direct / indirect

SearchResponse Role.getOwners(SearchFilter filter, boolean direct)

SearchResponse Role.getOwners(SearchFilter filter)

ResultSet<User> Group.getOwners(int nLevels, SearchFilter targetFilter, SearchOptions opts)

Add a user as a owner of a role

void Role.addOwner(Principal principal)

void Group.addOwner(User user, ModifyOptions opts)

Remove a user from being a owner of a Role

void Role.removeOwner(Principal principal)

void Group.deleteOwner(User user, ModifyOptions opts)

Get all the managers of a Role either direct / indirect

SearchResponse Role.getManagers(SearchFilter filter, boolean direct)

SearchResponse Role.getManagers(SearchFilter filter)

Not Supported

Add a user as a manager of a Role

void Role.addManager(Principal principal)

Not Supported

Remove a user from being manager of a Role

void Role.removeManager(Principal principal)

Not Supported

Getting the role property

Property Role.getProperty(String propName)

Note: User Role API fetches these attribute values from cache. If it misses cache, it fetches from repository.

Attribute Group.getAttribute(String attrName)

Determine the Role Type

Role.isApplicationRole

Role.isEnterpriseRole

Role.isSeeded

Not Supported

Search Roles for a given search criteria

SearchResponse IdentityStore.searchRoles(int scope, SearchParameters params)

ResultSet<Group> GroupManager.searchGroups(SearchFilter filter, SearchOptions opts)

Search a Role by name/uniquename /guid

Role IdentityStore.searchRole(int searchType, String value)

Group searchGroup(String id, ReadOptions opts)

Group searchGroup(String attrName, String attrVal, ReadOptions opts)

Search both User and Roles for a given filter

SearchResponse IdentityStore.search(SearchParameters params)

Available through separate methods:

UserManager.searchUsers

GroupManager.searchGroups

Get all the roles assigned to user/group

SearchResponse getGrantedRoles(Principal principal, boolean direct)

ResultSet<Group> User.getMemberOfGroups(int nLevels, SearchFilter targetFilter, SearchOptions opts)

ResultSet<Group> Group.getMemberOfGroups(int nLevels, SearchFilter targetFilter, SearchOptions opts)

Get all the roles owned by user/group

SearchResponse getOwnedRoles(Principal principal, boolean direct)

ResultSet<Group> User.getOwnedGroups(int nLevels, SearchFilter targetFilter, SearchOptions opts)

ResultSet<Group> Group.getOwnedGroups(int nLevels, SearchFilter targetFilter, SearchOptions opts)

Get all the roles managed by user/group

SearchResponse getManagedRoles(Principal principal, boolean direct)

Not supported