4 Migrating From the User and Role API to the ArisID API

This chapter describes how to migrate applications from the User and Role API to the ArisID API.

This chapter contains the following topics:

• Introduction

• Migrate a Simple Application

• Migrate Complex Application

• Comparison Between User and Role API and Aris ID API

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 ArisID beans instead.

First you must determine whether your application is simple or complex.

An application is simple if it has the following characteristics:

• User attributes belong to the LDAP inetorgperson object class.

• Role attributes belong to the LDAP groupofuniquenames object class.

• Search filters have only and condition on the attribute values.

• The standard userrole jar file meets your requirements.

  See Also:

  • Oracle Fusion Middleware Identity Governance Framework UserRole API Reference

  • Oracle Fusion Middleware Identity Governance Framework IDXUserRole API Reference

All other applications are identified as complex applications.

Migrate a Simple Application

If you have used the standard User and Role API without adding custom attributes, you can migrate to the ArisID API by following this sequence of steps.

To migrate a simple application, proceed as follows. This sequence applies only to Java EE applications.

Initialize the Application

Initialize your application to use the ArisID APIs.

import oracle.igf.userrole.UserManager;
import oracle.igf.userrole.RoleManager;
import org.openliberty.arisidbeans.ArisIdConstants;
import org.openliberty.arisidbeans.PropertyFilterValue;
HashMap env = new HashMap();

SECURITY_PRINCIPAL & SECURITY_CREDENTIALS are optional. If they are not used, the application connects to the backend with the credentials configured at domain level.

env.put(ArisIdConstants.SECURITY_PRINCIPAL, "cn=orcladmin");
env.put(ArisIdConstants.SECURITY_CREDENTIALS, "mypassword");

Create UserManager and Role manager objects.

UserManager userMgr = new UserManager(env);
RoleManager roleMgr = new RoleManager(env);                 

If the API will connect to the default identity store configured in Oracle Platform Security Services, the host and port details are automatically obtained from the identity store. If the API connects to a non-default identity store, the following must be configured:

• Set the system property igf.ovd.config.dir to point to the directory where the Identity Virtualization library configuration files reside.

• Configure each adapter in the Identity Virtualization library with the host and port details (such as host, port, root dn, plugins, and so on).

For more information about Identity Virtualization library, see Oracle Fusion Middleware Application Security Guide.

Perform Search Operations

You have the following search options:

• SearchByGuid

• SearchByName

• SearchUsers

• SearchByPage

SearchByGuid

You can search based on the GUID using one of the searchUserByGuid() methods. For example:

User myObject = userMgr.searchUserByGuid(String guidValue);

You can also search specifying more context to the search.

User myObject = userMgr.searchUserByGuid(String guidValue, Map appCtx); 
 

Where appCtx can contain the following details:

• APP_CTX_AUTHUSER - Principal (the Application principal to be used for doing the search)

• APP_CTX_LOCALE - User locale (applicable to all the attributes which have locale specific values)

• APP_CTX_PAGE - Application's page size

SearchByName

You can search based on the loginid using one of the searchUser() methods. For example:

User myObject = userMgr.searchUser(String loginid);

You can also search specifying more context to the search:

User myObject = userMgr.searchUser(String loginid, Map appCtx);

Where appCtx can contain the following details:

• APP_CTX_AUTHUSER - Principal (the Application principal to be used for doing the search)

• APP_CTX_LOCALE - User locale (applicable to all the attributes which have locale specific values)

• APP_CTX_PAGE - Application's page size.

SearchUsers

You can search based on the following filter:

List myUsers = userMgr.searchUsers(java.util.List<org.openliberty.arisidbeans.PropertyFilterValue> attrFiltersList));

You can construct the attrFiltersList as follows:

attrFilters = new ArrayList<PropertyFilterValue>();
attrFilters.add(new PropertyFilterValue("firstname", "abc"));
attrFilters.add(new PropertyFilterValue("lastname", "xyz"));

SearchByPage

The ArisID API provides pagination support. You can search for users by using searchUsersByPage() as follows:

SearchResults<User> sResult = userMgr.searchUsersByPage(java.util.List
 <org.openliberty.arisidbeans.PropertyFilterValue> attrFiltessList));
while (sResult.hasMore()) {
    List<User> users = sResult.getNextSet();
    for (int i = 0; i < users.size(); i++)
// Process each user entry fetched
        Util.printObject(users.get(i));
}

Migrate Complex Application

For complex applications, you need to create a custom CARML file and generate ArisID beans. You can migrate search code in the same way as for simple applications. There are some additional preliminary steps, however. Proceed as follows.

Identify the New Attributes

If your application requires custom attributes (that is, attributes which are not supported by inetorgperson), you must create an application-specific CARML file. You need to edit the CARML file and add the attribute definitions in the data definitions part of the CARML file.

Identify the Interactions

The default ArisID bean interactions are designed to access all the attributes of the user and role entries. If your application requires custom interactions for performance reasons, you can create the interactions by editing the CARML file.

Generate ArisID Beans by Using the JDeveloper Extension

Use the Identity Governance Framework ArisID JDeveloper extension to create and edit the CARML file and generate the beans. For more information, see Chapter 3, "Developing Applications."

Set Up the Environment

Make the CARML file available to your application. Include the classes generated by the BeanGenerator as part of your application, or make it available in the CLASSPATH environment variable.

Perform Search Operations

Search operations are the same as for simple application migration. See "Perform Search Operations".

Comparison Between User and Role API and Aris ID API

These APIs are compared to the ArisID API in the following tables:

• User-Related APIs

• Role-Related APIs

User-Related APIs

Table 4-1 provides a comparison between the User-related API method and the corresponding Identity Beans method available in the Identity Governance Framework Aris ID API.

Identity Beans methods marked with a double asterisk (**) have an optional parameter: Map<String.Object> appCtxMap. For example, UserManager.createUser(List<PropertyValue> attrVals, Map<String,Object> appCtxMap). appCtxMap may contain the following elements:

• UserManager.APP_CTX_AUTHUSER: java.security.Principal, the user context to execute under.

• UserManager.APP_CTX_PAGE: String value of Page size. This is applicable only for search methods returning SearchResults object.

• UserManager.APP_CTX_LOCALE: String value of language code.

Table 4-1 Comparison Between User-Related API and ArisID API

Functionality	User/Role API Method	Identity Beans Method
User Creation	User UserManager.createUser(String name, char[] password) User UserManager.createUser(String name, char[] password, PropertySet pset)	** void UserManager.createUser(List<PropertyValue> attrVals)
Delete User	void UserManager.dropUser(UserProfile user) void UserManager.dropUser(User user);	** void UserManager.dropUser(IPrincipalIdentifier ** void UserManager.dropUser(String SubjectId) ** void UserManager.dropUser(User subj)
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(List<PropertyFilterValue> attrFiltersList) ** User UserManager.authenticateUser(String uid, String password)
Check if create User is supported	boolean UserManager.isCreateUserSupported()	boolean UserManager.isCreateUserSupported()
Check if modify User is supported	boolean UserManager.isModifyUserSupported()	boolean UserManager.isModifyUserSupported()
Check if drop User is supported	boolean UserManager.isDropUserSupported()	boolean UserManager.isDropUserSupported()
Search Users by given search criteria	SearchResponse IdentityStore.searchUsers(SearchParameters params)	** List<User> UserManager.searchUsers(List<PropertyFilterValue> attrFiltersList) ** SearchResults<User> UserManager.searchUsersbyPage(List<PropertyFilterValue> attrFiltersList)
Search an User by name /uniquename / guid	User IdentityStore.searchUser(String name)	** User UserManager.searchUser(List<PropertyFilterValue> attrFiltersList) ** User UserManager.searchUser(String loginid)
Check if User exists in the repository for a given User object	boolean IdentityStore.exists (User user)	boolean UserManager.exists(User subj)
Simple search filter (search based on a single attribute name, type and value)	SimpleSearchFilter	Filter defined for search interaction in CARML file
Complex Search Filter (search based on more than one attribute with filter conditions and nested filters)	ComplextSearchFilter	Limited Support available where the actual attributes based on which the search will be made is predefined in CARML file.
Getting a property value for a given property name	String User.getPropertyVal(String propName) Note: User Role API, fetches the attribute values from cache. If it misses cache, it fetches from repository.	String User.getAttributeValue(String attribute) boolean User.getPredicateValue(String predicate) Object User.getPropertyValue(String property) Limitation: Returns attribute values from User object that's already fetched from the repository. This doesn't go to repository again to fetch the latest value. This applies to all variations of get values.
Getting the User property for a given property name	Property User.getProperty(String propName)	IAttributeValue User.getAttribute(String attribute) PredicateValue User.getPredicate(String predicate) Object User.getProperty(String property)
Getting the user properties for a given set of property names	Map User.getProperties()	Map<String,IAttributeValue> User.getAllAttributes() Map<String,PredicateValue> User.getAllPredicates() Map<String,Object> User.getAllProperties()
Get all user property names from the schema	List IdentityStore.getUserPropertyNames() Note: Returns the names of all the properties in the schema	List<String> UserManager.getAllAttributeNames() List<String> UserManager.getAllPredicateNames() List<String> UserManager.getAllPropertyNames()
Changing the attribute value in the repository of an user	void User.setProperty(ModProperty mprop)	void User.setAttributeValue(String attrName, String attrValue) void User.setAttribute(ModPropertyValue attr)
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.setAttributes(List<ModPropertyValue> attrs)
Get all the reports of an User either direct or indirect	SearchResponse User.getReportees(boolean direct)	** List<User> UserManager.getReportees(User user, int nLevels)
Get Management chain of an user	List User.getManagementChain(int max, String upToManagerName, String upToTitle)	** List<User> UserManager.getManagementChain(User user, int nLevels, String title, String manager)
Get/Set of Binary Attributes	Available. Property in User/Role API supports binary attributes byte[] user.getJPEGPhoto() void user.setJPEGPhoto(String imgpath)	Available. byte[] User.getJpegphoto() void User.setJpegphoto(byte[] value)
Selecting the Realm	Available. env.put(OIDIdentityStoreFactory.RT_SUBSCRIBER_NAME, "<realm dn>"); IdentityStoreFactory.getIdentityStoreInstance(env);	This is part of Mapping configuration.

Role-Related APIs

Table 4-2 provides a comparison between the Role-related API method and the corresponding Identity Beans method available in the Identity Governance Framework Aris ID API.

Identity Beans methods marked with a double asterisk (**) have an optional parameter: Map<String.Object> appCtxMap. For example, RoleManager.searchRolesbyPage(List<PropertyFilterValue> attrFiltersList, Map<String,Object> appCtxMap). appCtxMap may contain the following elements:

• UserManager.APP_CTX_AUTHUSER: java.security.Principal, the user context to execute under.

• UserManager.APP_CTX_PAGE: String value of Page size. This is applicable only for search methods returning SearchResults object.

• UserManager.APP_CTX_LOCALE: String value of language code.

Table 4-2 Comparison Between Role-Related APIs and ArisID API

Functionality	User/Role API Method	Identity Beans Method
Creating a Role	Role RoleManager.createRole(String name, int scope) Role RoleManager.createRole(String name)	** void RoleManager.createRole(List<PropertyValue> attrVals)
Deleting a Role	void RoleManager.dropRole(RoleProfile role) void RoleManager.dropRole(Role role)	** void RoleManager.dropRole(IPrincipalIdentifier principal) ** void RoleManager.dropRole(Role subj)
Check if create role is supported	boolean RoleManager.isCreateRoleSupported()	boolean RoleManager.isCreateRoleSupported()
Check if modify role is supported	boolean RoleManager.isModifyRoleSupported()	boolean RoleManager.isModifyRoleSupported()
Check if delete role is supported	boolean RoleManager.isDropRoleSupported()	boolean RoleManager.isDropRoleSupported()
Is the Group owned by a User	boolean RoleManager.isGranted(Role parent, Principal principal)	** boolean RoleManager.isGranted(Role role, Role member, boolean direct) ** boolean RoleManager.isGranted(Role role, User member, boolean direct)
Is the Group owned by a User	boolean RoleManager.isOwnedBy(Role parent, Principal principal)	** boolean RoleManager.isOwned(Role role, Role owner, boolean direct) ** boolean RoleManager.isOwned(Role role, User owner, boolean direct)
Is the group managed by a User	boolean RoleManager.isManagedBy(Role parent, Principal principal)	** boolean RoleManager.isManaged(Role role, Role manager, boolean direct) ** boolean RoleManager.isManaged(Role role, User manager, boolean direct)
Get all the members of a Role either direct / indirect	SearchResponse Role.getGrantees(SearchFilter filter, boolean direct)	** List<User> RoleManager.getGrantees(Role role, int nLevels, UserManager usermanager)
Add a user as a member to a role	void RoleManager.grantRole(Role parent, Principal principal)	** void Role.addMember(Role role) ** void Role.addMember(String value) ** void Role.addMember(User user)
Remove a user from being member of a role	void RoleManager.revokeRole(Role parent, Principal principal)	** List<User> RoleManager.getOwners(Role role, int nLevels, UserManager usermanager)
Get all the owners of a specific Role either direct / indirect	SearchResponse Role.getOwners(SearchFilter filter, boolean direct) SearchResponse Role.getOwners(SearchFilter filter)	** List<User> RoleManager.getOwners(Role role, int nLevels, UserManager usermanager)
Add a user as a owner of a role	void Role.addOwner(Principal principal)	** void Role.addOwner(Role role) ** void Role.addOwner(String value) ** void Role.addOwner(User user)
Remove a user from being a owner of a Role	void Role.removeOwner(Principal principal)	** void Role.deleteOwner(Role role) ** void Role.deleteOwner(String value) ** void Role.deleteOwner(User user)
Get all the managers of a Role either direct / indirect	SearchResponse Role.getManagers(SearchFilter filter, boolean direct) SearchResponse Role.getManagers(SearchFilter filter)	** List<User> RoleManager.getManagers(Role role, int nLevels, UserManager usermanager)
Add an user as a manager of a Role	void Role.addManager(Principal principal)	** void Role.addManager(Role role) ** void Role.addManager(String value) ** void Role.addManager(User user)
Remove an user from being manager of a Role	void Role.removeManager(Principal principal)	** void Role.deleteManager(Role role) ** void Role.deleteManager(String value) ** void Role.deleteManager(User user)
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)	IAttributeValue Role.getAttribute(String attribute) PredicateValue Role.getPredicate(String predicate) Object Role.getProperty(String property)
Determine the Role Type	Role.isApplicationRole Role.isEnterpriseRole Role.isSeeded
Search Roles for a given search criteria	SearchResponse IdentityStore.searchRoles(int scope, SearchParameters params)	** List<Role> RoleManager.searchRoles(List<PropertyFilterValue> attrFiltersList) ** SearchResults<Role> RoleManager.searchRolesbyPage(List<PropertyFilterValue> attrFiltersList)
Search a Role by name / uniquename / guid	Role IdentityStore.searchRole(int searchType, String value)	** Role RoleManager.searchUser(List<PropertyFilterValue> attrFiltersList) ** Role RoleManager.searchUser(String guid)
Search both User and Roles for a given filter	SearchResponse IdentityStore.search(SearchParameters params)	This is available through separate methods: UserManager.searchUsers, RoleManager.searchRoles