20 Developing with the Identity Governance Framework
This chapter includes the following sections:
About the Identity Governance Framework
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.
Identity Directory API Overview
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.
About the Identity Directory API Configuration
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
Using the Identity Directory API
The following sections include examples that illustrate the use of the Identity Directory API to manage users and groups:
Initializing and Obtaining the Identity Directory Handle
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();
}Creating and Deleting a User
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();
}
}Obtaining and Modifying a User
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();
}
}Simple and Complex User Search
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();
}
}Creating and Deleting a Group
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;
}
Obtaining a Group
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;
}Group Search Filter
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();
}
}Adding and Deleting a Member to a Group
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();
}
}Configuring SSL Using the Identity Directory API
For information about Secure Sockets Layer (SSL) configuration when using the Identity Directory API, see Configuring SSL for the Identity Store.