This chapter describes how to migrate applications from the User and Role API to the Identity Directory API. This chapter contains the following topics:
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".
Application migrating from the User and Role API to the Identity Directory API need to make the following code changes:
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();
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();
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")));
Create/Read/Update/Delete (CRUD) operations on User, Group, Org, and generic entities are discussed in the following sections:
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)
The following is an example of the API for searching a user.
ResultSet<User> searchUsers(SearchFilter filter, SearchOptions opts)
The following is an example of the API for creating a user.
Principal createUser(List<Attribute> attrVals, CreateOptions opts)
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)
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)
The APIs for modifying user attributes and for getting the related entities are in User object instead of UserManager.
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)
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)
The differences between the User and Role API and Identity Directory API are discussed in the following topics:
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. |
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 |