This chapter explains how to access and maintain identities with the Identity Directory API provided with the Identity Governance Framework.
This chapter includes the following sections:
The Identity Governance Framework allows applications to access identity data uniformly regardless of the particular underlying identity repository. This framework includes the Identity Directory API, a flexible, fully configurable collection of interfaces that allows access to artifacts in the identity store.
To use the Identity Directory API, add the igf-manifest.jar
file to the application classpath.
The Identity Directory API allows Java EE and SE applications to access and manage identity data. This API is part of the Identity Governance Framework and offers all the framework's benefits for identity control.
The Identity Directory API allows you to:
Operate on users and groups.
Change passwords.
Force password changes.
Maintain attributes with multiple values, and static and dynamic groups.
The Identify Directory API provides an interface to access and modify users and group information from different identity stores. The configuration is specified in the DOMAIN_HOME/config/fmwconfig/ids-config.xml
and ovd/ids/adapters.os.xml
files, and the OPSS configuration file.
See also:
Configuring Security Providers with Fusion Middleware Control
Identity Directory API Configuration in Developing Applications with Identity Governance Framework
Java API Reference for Identity Governance Framework Identity Directory
The following sections include examples that illustrate the use of the Identity Directory API to manage users and groups:
The following example illustrates how to obtain the Identity Directory handle and a directory instance:
JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory(); JpsContext ctx = ctxFactory.getContext(); //find the service instance IdentityStoreService idstoreService = ctx.getServiceInstance(IdentityStoreService.class) to //get instance oracle.igf.ids.IdentityDirectory ids = idstoreService.getIdentityStore();
The following example initializes the service with the configuration present in the IDS location. All user and group operations are performed with this IDS instance.
import java.util.ArrayList; import java.util.List; import java.util.Iterator; import java.util.Map; import java.security.Principal; import oracle.igf.ids.Entity; import oracle.igf.ids.User; import oracle.igf.ids.UserManager; import oracle.igf.ids.Group; import oracle.igf.ids.GroupManager; import oracle.igf.ids.config.OperationalConfig; import oracle.igf.ids.IdentityDirectoryFactory; import oracle.igf.ids.IdentityDirectoryInfo; import oracle.igf.ids.IdentityDirectory; import oracle.igf.ids.IDSException; import oracle.igf.ids.ReadOptions; import oracle.igf.ids.CreateOptions; import oracle.igf.ids.ModifyOptions; import oracle.igf.ids.DeleteOptions; import oracle.igf.ids.SearchOptions; import oracle.igf.ids.SearchFilter; import oracle.igf.ids.ResultSet; import oracle.igf.ids.Attribute; import oracle.igf.ids.ModAttribute; import oracle.dms.context.ExecutionContext; public class Ids1Test { private IdentityDirectory ids; private UserManager uMgr; private GroupManager gMgr; public Ids1Test() throws IDSException { // Set Operational Config OperationalConfig opConfig = new OperationalConfig(); // Set search/crate base, name, objclass, etc. config. // This overrides default operational configuration in IDS opConfig.setEntityProperty("User", opConfig.SEARCH_BASE, "l=amer,dc=example,dc=com"); opConfig.setEntityProperty("User", opConfig.CREATE_BASE, "l=amer,dc=example,dc=com"); opConfig.setEntityProperty("User", opConfig.FILTER_OBJCLASSES, "person"); opConfig.setEntityProperty("User", opConfig.CREATE_OBJCLASSES, "inetorgperson"); opConfig.setEntityProperty("Group", opConfig.SEARCH_BASE, "cn=dlcontainerOCS,dc=example,dc=com"); opConfig.setEntityProperty("Group", opConfig.CREATE_BASE, "cn=dlcontainerOCS,dc=example,dc=com"); opConfig.setEntityProperty("Group", opConfig.FILTER_OBJCLASSES, "groupofuniquenames"); opConfig.setEntityProperty("Group", opConfig.CREATE_OBJCLASSES, "groupofuniquenames,orclgroup"); // Get IdentityDirectoryService "userrole" configured in IDS config IdentityDirectoryFactory factory = new IdentityDirectoryFactory(); ids = factory.getIdentityDirectory("userrole", opConfig); // Get UserManager and GroupManager handles uMgr = ids.getUserManager(); gMgr = ids.getGroupManager(); }
The following examples illustrate how to create and delete a user.
public Principal createUser() { Principal principal = null; List<Attribute> attrs = new ArrayList<Attribute>(); attrs.add(new Attribute("commonname", "test1_user1")); attrs.add(new Attribute("password", "password23".toCharArray())); attrs.add(new Attribute("firstname", "test1")); attrs.add(new Attribute("lastname", "user1")); attrs.add(new Attribute("mail", "test1.user1@example.com")); attrs.add(new Attribute("telephone", "1 650 123 0001")); attrs.add(new Attribute("title", "Senior Director")); attrs.add(new Attribute("uid", "tuser1")); attrs.add(new Attribute("description", "created test user 1", new java.util.Locale("us", "en"))); try { CreateOptions createOpts = new CreateOptions(); createOpts.setCreateBase("l=apac,dc=example,dc=com"); principal = uMgr.createUser(attrs, createOpts); System.out.println("Created user " + principal.getName()); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } return principal; }
public void deleteGroup(Principal principal) { try { DeleteOptions deleteOpts = new DeleteOptions(); gMgr.deleteGroup(principal, deleteOpts); System.out.println("Deleted group " + principal.getName()); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
The following examples illustrates how to obtain a handle to a user and modify it.
public User getUser(Principal principal) { User user = null; try { ReadOptions readOpts = new ReadOptions(); // Getting specific locale values readOpts.setLocale("us-en"); user = uMgr.getUser(principal, readOpts); printEntity(user); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } return user; }
public void modifyUser(User user) { try { ModifyOptions modifyOpts = new ModifyOptions(); List<ModAttribute> attrs = new ArrayList<ModAttribute>(); attrs.add(new ModAttribute("description", "modified test user 1")); //attrs.add(new ModAttribute("uid", "testuser1")); user.modify(attrs, modifyOpts); System.out.println("Modified user " + user.getName()); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
The following examples illustrate a simple and complex user search.
try { ReadOptions readOpts = new ReadOptions(); readOpts.setSearchBase("l=apac"); User user = uMgr.searchUser("tuser1", readOpts); printEntity(user); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
public void searchUsers() { try { // Complex search filter with nested AND and OR conditiions SearchFilter filter = new SearchFilter( SearchFilter.LogicalOp.OR, new SearchFilter(SearchFilter.LogicalOp.AND, new SearchFilter("firstname", SearchFilter.Operator.BEGINS_WITH, "ve"), new SearchFilter("telephone", SearchFilter.Operator.CONTAINS, "506")), new SearchFilter(SearchFilter.LogicalOp.AND, new SearchFilter("firstname", SearchFilter.Operator.BEGINS_WITH, "ra"), new SearchFilter(SearchFilter.LogicalOp.OR, new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH, "ldap"), new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH, "sun"), new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH, "access")), new SearchFilter("telephone", SearchFilter.Operator.CONTAINS, "506"))); // Request attributes List<String> reqAttrs = new ArrayList<String>(); reqAttrs.add("jpegphoto"); SearchOptions searchOpts = new SearchOptions(); searchOpts.setPageSize(3); searchOpts.setRequestedPage(1); searchOpts.setRequestedAttrs(reqAttrs); searchOpts.setSearchBase("l=amer"); ResultSet<User> sr = uMgr.searchUsers(filter, searchOpts); while (sr.hasMore()) { User user = sr.getNext(); System.out.println(user.getSubjectName()); System.out.println(" " + user.getAttributeValue("commonname")); } } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
The following example illustrates how to create and delete a group.
public Principal createGroup() { Principal principal = null; List<Attribute> attrs = new ArrayList<Attribute>(); attrs.add(new Attribute("name", "test1_group1")); attrs.add(new Attribute("description", "created test group 1")); attrs.add(new Attribute("displayname", "test1 group1")); try { CreateOptions createOpts = new CreateOptions(); principal = gMgr.createGroup(attrs, createOpts); System.out.println("Created group " + principal.getName()); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } return principal; }
The following example illustrates how to obtain a handle to a group.
public Group getGroup(Principal principal) { Group group = null; try { ReadOptions readOpts = new ReadOptions(); group = gMgr.getGroup(principal, readOpts); printEntity(group); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } return group; }
The following example illustrates a search filter that returns multiple groups.
public void searchGroups() { try { SearchFilter filter = new SearchFilter("name", SearchFilter.Operator.BEGINS_WITH, "test"); SearchOptions searchOpts = new SearchOptions(); searchOpts.setPageSize(10); ResultSet<Group> sr = gMgr.searchGroups(filter, searchOpts); while (sr.hasMore()) { Group group = sr.getNext(); System.out.println(group.getSubjectName()); } } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
The following examples illustrate how to add and delete a user from a group.
public void addMember() { try { ReadOptions readOpts = new ReadOptions(); User user = uMgr.searchUser("testuser1", readOpts); Group group = gMgr.searchGroup("test1_group1", readOpts); ModifyOptions modOpts = new ModifyOptions(); user.addMemberOf(group, modOpts); System.out.println("added testuser1 as member of test1_group1"); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
public void deleteMember() { try { ReadOptions readOpts = new ReadOptions(); User user = uMgr.searchUser("testuser1", readOpts); Group group = gMgr.searchGroup("test1_group1", readOpts); ModifyOptions modOpts = new ModifyOptions(); group.deleteMember(user, modOpts); System.out.println("deleted testuser1 from the group test1_group1"); } catch (Exception e) { System.out.println(e.getMessage()); e.printStackTrace(); } }
For information about Secure Sockets Layer (SSL) configuration when using the Identity Directory API, see Configuring SSL for the Identity Store.