26 Developing with the Identity Directory API

26.1.1 Feature Overview

This section explains the features supported by the Identity Directory API.

Features for User Entities

The following features are supported for users:

• Perform Create, Read, Update, Delete (CRUD) operations on users

• Perform the following actions:

  • get and set user attributes

  • authenticate the user with the identity store's native authentication mechanism

  • get the group to which the user belongs (optionally, including nested groups)

  • make user a member of a group

• Change user password

• Force user password change

• Get and set user state (enable/disable, lockout, password must change)

Features for Group Entities

The following features are supported for groups:

• Perform CRUD operations on groups

• Perform the following actions:

  • get and set attributes

  • get and search for members of a group

  • get the groups to which a groups belongs (optionally, including nested groups)

  • determine if the group is a member of another group

• Support multi-valued attributes

• Support static and dynamic groups

26.4.1 Getting an Identity Directory API Instance

You can obtain the identity directory handle from the jps-context and get a directory instance as follows:

JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
JpsContext ctx = ctxFactory.getContext();
       
//find the JPS IdentityStore service instance
IdentityStoreService idstoreService =   ctx.getServiceInstance(IdentityStoreService.class)
 
//get the Identity Directory instance
oracle.igf.ids.IdentityDirectory ids = idstoreService.getIdentityStore();

26.4.2 Performing CRUD Operations on Users and Groups

You can perform Create, Retrieve, Update, and Delete (CRUD) operations on users and groups.

• User Operations

• Group Operations

Principal UserManager.createUser(List<Attribute> attrVals, CreateOptions opts)

User UserManager.getUser(Principal principal, ReadOptions opts)

User UserManager.searchUser(String id, ReadOptions opts)

void UserManager.deleteUser(String id, DeleteOtions opts)

void UserManager.modify(List<ModAttribute> attrVals, ModifyOptions opts)

ResultSet UserManager.searchUsers(SearchFilter filter, SearchOptions opts)

Principal GroupManager.createGroup(List<Attribute> attrVals, CreateOptions opts)

User GroupManager.getGroup(Principal principal, ReadOptions opts)

User GroupManager.searchGroup(String id, ReadOptions opts)

void GroupManager.deleteGroup(String id, DeleteOtions opts)

void GroupManager.modify(List<ModAttribute> attrVals, ModifyOptions opts)

ResultSet GroupManager.searchGroups(SearchFilter filter, SearchOptions opts)

26.5.1 Initialize and Obtain Identity Directory Handle

This sample code initializes and obtains a handle to the identity directory:

/**
 * This is a sample program for initializing Identity Directory Service with the configuration
 * that is already persisted in IDS config location.
 * Basic User and Group CRUDS are performed using 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;
 
 
    /**
     * Get Identity Store Service
     */
    public Ids1Test() throws IDSException {
 
        // Set Operational Config
        OperationalConfig opConfig = new OperationalConfig();
 
        // Set the application credentials: this overrides the credentials 
        // set in physical ID store configuration
        //opConfig.setApplicationUser("cn=test_user1,l=amer,dc=example,dc=com");
        //opConfig.setApplicationPassword("welcome123".toCharArray());
 
        // 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.getDefaultIdentityDirectory(opConfig);
        ids = factory.getIdentityDirectory("userrole", opConfig);
 
        // Get UserManager and GroupManager handles
        uMgr = ids.getUserManager();
        gMgr = ids.getGroupManager();
    }
 

26.5.2 Create a User

This sample code creates a user in the identity store:

 public Principal createUser() {
        Principal principal = null;
        
        List<Attribute> attrs = new ArrayList<Attribute>();
        attrs.add(new Attribute("commonname", "test1_user1"));
        attrs.add(new Attribute("password", "welcome123".toCharArray()));
        attrs.add(new Attribute("firstname", "test1"));
        attrs.add(new Attribute("lastname", "user1"));
        attrs.add(new Attribute("mail", "[email protected]"));
        attrs.add(new Attribute("telephone", "1 650 123 0001"));
        attrs.add(new Attribute("title", "Senior Director"));
        attrs.add(new Attribute("uid", "tuser1"));
        // Adding locale specific value
        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;
    }

26.5.3 Get a User

This sample code obtains a user from the identity store:

 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;
    }

26.5.4 Modify a User

This sample code modifies an existing user by adding a new user attribute:

 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();
        }
    }

26.5.5 Simple Search for a User

This sample code performs a basic 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();
        }
    }

26.5.6 Complex Search for Users

This sample code uses a complex search filter to return matching users:

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")));
 
      // Requesting 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();
            //printEntity(user);
            //System.out.println(" ");
            System.out.println(user.getSubjectName());
            System.out.println("    " + user.getAttributeValue("commonname"));
         }
 
      } catch (Exception e) {
         System.out.println(e.getMessage());
         e.printStackTrace();
      }
    }

26.5.7 Create a Group

This sample code creates 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;
    }

26.5.8 Get a Group

This sample code returns a specific 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;
    }

26.5.9 Get Group Using a Search Filter

This sample code uses a search filter to return 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();
        }
    }

26.5.10 Delete a Group

This sample code deletes a group from the store:

 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();
        }
    }

26.5.11 Add a Member to a Group

This sample code adds a member to 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();
        }
    }

26.5.12 Delete a Member from a Group

This sample code deletes a member from a group:

 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();
        }
    }