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 Securing Applications with Oracle Platform Security Services and Java API Reference for Oracle Platform Security Services User and Role, 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, "Initializing and Obtaining 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:
The process of initializing 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.
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)
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)
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:
The table in this section provides a comparison between the User-related API method and the corresponding Identity Directory API API method.
| 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. |
The table in this section provides a comparison between the Role-related API method and the corresponding Identity Directory API method.
| 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 |
Moving from one environment to another, especially from a test environment to production environment, provides you the flexibility to test applications in a test environment and then roll them out in the production environment.
This section describes the Identity Directory Service/libOVD properties that you need to modify while moving from a test environment to production environment, and contains the following topics:
Moving Identity Directory Service/libOVD installation diminishes the amount of work that would otherwise be required to reapply all the customization and configuration changes made in one environment to another. You can install, configure, customize, and validate Identity Directory Service/libOVD in a test environment. Once the system is stable and performs as required, you can create the production environment by moving a copy of the server and its configuration from the test environment, instead of redoing all the changes that were incorporated into the test environment.
A move plan contains configuration settings of the source environment. When you move between environments, you run the extractMovePlan script to create a move plan for the entity that you are moving. The extractMovePlan script extracts configuration information from the archive into a move plan. It also extracts any needed configuration plans. Before you apply the archive to the target, you must edit the move plan to reflect the values of the target environment.
You can modify properties with the scope of READ_WRITE. Do not modify the properties with the scope of READ_ONLY. For a comprehensive description and the procedure to follow for moving between environments, see "Moving from a Test to a Production Environment" section in the Oracle Fusion Middleware Administrator's Guide.
This section contains the following topics:
Locating Identity Directory Service/libOVD configGroup Elements
Understanding Identity Directory Service/libOVD Move Plan Properties
Move plans usually contain multiple configGroup elements. To locate Identity Directory Service/libOVD ConfigGroup, in the generated move plan, you must look for <type>LIBOVD_ADAPTERS</type>. This tag provides comprehensive information about the libOVD adapter properties that you might have to update. A property is associated with a particular configGroup element.
Each adapter is represented by a configProperty id tag of the form:
"LDAP:<context_name>:<adapter_name>"
Consider the following example: "LDAP:ids:myOID"
Table 4-1 shows the properties for the move plan for libOVD.
The following example shows a section of the move plan for Identity Directory Service/libOVD, with portion of the LIBOVD_ADAPTERS configGroup elements:
<configGroup>
<type>LIBOVD_ADAPTERS</type>
<configProperty id="LDAP:ids:myOID">
<configProperty>
<name>Context Name</name>
<value>ids</value>
<itemMetadata>
<dataType>STRING</dataType>
<scope>READ_ONLY</scope>
</itemMetadata>
</configProperty>
<configProperty>
<name>Adapter Name</name>
<value>myOID</value>
<itemMetadata>
<dataType>STRING</dataType>
<scope>READ_ONLY</scope>
</itemMetadata>
</configProperty>
<configProperty>
<name>LDAP URL</name>
<value>ldap://hostname:1389</value>
<itemMetadata>
<dataType>STRING</dataType>
<scope>READ_WRITE</scope>
</itemMetadata>
</configProperty>
<configProperty>
<name>LDAP Host Read Only</name>
<value>false</value>
<itemMetadata>
<dataType>STRING</dataType>
<scope>READ_WRITE</scope>
</itemMetadata>
</configProperty>
<configProperty>
<name>LDAP Host Percentage</name>
<value>100</value>
<itemMetadata>
<dataType>STRING</dataType>
<scope>READ_WRITE</scope>
</itemMetadata>
</configProperty>
<configProperty>
<name>DN</name>
<value>cn=orcladmin</value>
<itemMetadata>
<dataType>STRING</dataType>
<scope>READ_WRITE</scope>
</itemMetadata>
</configProperty>
<configProperty>
<name>Password File</name>
<value/>
<itemMetadata>
<dataType>STRING</dataType>
<password>true</password>
<scope>READ_WRITE</scope>
</itemMetadata>
</configProperty>
</configProperty>
</configGroup>
The Table 4-1 in this section describes the move plan properties you can customize for Identity Directory Service/libOVD adapter.
Table 4-1 Move Plan Properties for libOVD
| Property | Description | Sample Value |
|---|---|---|
|
Context Name |
The libOVD context to use with which the adapter is associated. This is a read-only property. |
|
|
Adapter Name |
The name of the adapter. This is a read-only property. |
|
|
LDAP URL |
The LDAP URL value for the adapter in the form of ldap://host:port. This is a read-write property. |
|
|
DN |
The DN of the user to connect to the backend LDAP. This is a read-write property. |
|
|
Password File |
The absolute path to the secure file containing the password of the user. This is a read-write property. |
|
|
LDAP Host Read Only |
The flag indicating if the given host is read only. The default value is |
|
|
LDAP Host Percentage |
It specifies the load percentage value for the given LADAP host. The default value is |
|
Tuning is the adjustment or modification of parameters to meet specific deployment requirements. The default IDS configuration must be tuned for your deployment scenario.
You must review the requirements and recommendations in this section carefully.
This section contains the following topics:
Table 4-2 lists the configuration parameters that require turning in a real deployment scenario for IDS.
Table 4-2 Configuration Parameters for IDS
| Parameter | Description |
|---|---|
|
|
The initial number of LDAP connections created when the LDAP connection pool is set up. |
|
|
The maximum number of LDAP connections allowed in the LDAP connection pool. Note: If a deployment has numerous concurrent requests coming in, then you must set this value appropriately to prevent running out of connections or waiting for a connection during an operation. |
|
|
These parameters determine the waiting time for free LDAP connection when all the LDAP connections in the connection pool are in use. IDS waits for |
|
|
This is the timer interval (in seconds) used by the LDAP connection pool cleanup timer. The LDAP connection pool cleanup timer runs using this timer interval to perform pool cleanup tasks like shrinking the connection pool based on the idle connection if needed. |
|
|
This specifies the maximum idle time for an LDAP connection. In an LDAP connection remains idle for this amount of time, it will be closed when the next LDAP connection pool cleanup timer runs. |
|
|
The amount of time in milliseconds IDS waits for an LDAP request to be acknowledged by the LDAP remote host. |
|
|
This specifies the LDAP connection timeout duration in milli seconds. If a connection cannot be established in this period, then the connection attempt is aborted. |
|
|
This is the interval in seconds to check the availability of backend LDAP. |
|
|
This parameters set |
|
|
This specifies the maximum time any connection can potentially be reused after which the pool removes and closes a connection. The value is specified in seconds. |
|
|
This specifies the time duration in seconds that a borrowed connection can remain unused before it is automatically reclaimed by the pool. |
The configuration information is stored in XML file. In such a scenario, you can use the WebLogic Scripting Tool (WLST) to modify the configuration parameters.
This section describes how to configure the tuning parameters using the WLST command.
Note:
In all the WLST command examples in this section,ADAPTER_NAME refers to the name of the IDS repository. For instance, the libOVD adapter name.For InitialPoolSize:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='InitialPoolSize', value=10, contextName='ids')
For MaxPoolSize:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='MaxPoolSize', value=100, contextName='ids')
For MaxPoolWait and MaxPoolCheck:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='MaxPoolWait', value=1000, contextName='ids') modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='MaxPoolChecks', value=10, contextName='ids')
For PoolCleanupInterval:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='PoolCleanupInterval', value=300, contextName='ids')
For MaxPoolConnectionIdleTime:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='MaxPoolConnectionIdleTime', value=3600, contextName='ids')
For OperationTimeout:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='OperationTimeout', value=120000, contextName='ids')
For ConnectTimeout
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='ConnectTimeout', value=10000, contextName='ids')
For HeartbeatInterval:
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='HeartBeatInterval', value=60, contextName='ids')
For SocketOption:
modifySocketOptions(adapterName='ADAPTER_NAME', reuseAddress=false, keepAlive=false, tcpNoDelay=true, readTimeout=1800, contextName='ids')
For MaxPoolConnectionReuseTime
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='MaxPoolConnectionReuseTime', value=3600, contextName='ids')
For PoolConnectionReclaimTime
modifyLDAPAdapter(adapterName='ADAPTER_NAME', attribute='PoolConnectionReclaimTime', value=180, contextName='ids')
Note:
You must run theactivateLibOVDConfigChanges('ids') WLST command or restart the WebLogic server for configuration changes to take effect.The configuration information is stored by the IDS consumer and is passed during run-time to IDS by invoking the IdentityStoreConfig class. For more information about using the class and its properties, see Oracle Fusion Middleware Java API Reference for Identity Governance Framework Identity Directory.
You can modify the following configuration parameters using the Java API class:
Table 4-3 Field Name for Configuration Parameters
| Parameter | Field Name to Modify |
|---|---|
|
InitialPoolSize |
|
|
MaxPoolSize |
|
|
MaxPoolWait MaxPoolChecks |
|
|
PoolCleanupInterval |
|
|
MaxPoolConnectionIdleTime |
|
|
OperationTimeout |
|
|
ConnectTimeout |
|
|
HeartbeatInterval |
|
|
SocketOptions |
|
|
MaxPoolConnectionReuseTime |
|
|
PoolConnectionReclaimTime |
|
SocketOptions setting helps detect and safely close orphan socket connections caused by remote server failure. TCP waits for the configured duration of time for a response from the remote server before closing the socket. However, when there is a firewall or a Load Balancer between libOVD and the backend LDAP, then you must set the readTimeout value in the SocketOptions appropriately to prevent timeout errors. It is recommended that you set this value to a value which is less than the firewall or the Load Balancer timeout.