2 Using the Identity Directory API

2.1.1 About the Identity Directory Service

The Identity Directory Service is a common service used by identity management products to access and manage an Identity Directory. The Identity Directory API is used to initialize the Identity Directory Service. The Identity Directory Service provides an interface to both access and modify users and group information from different identity stores. An Identity Directory is an instance of the Identity Directory Service having:

• a unique name (IDS name)

• a logical entity configuration

• a physical identity store configuration

2.1.2 Identity Directory Service Architecture

Figure 2-2 shows the logical architecture of the Identity Directory API.

Figure 2-1 Identity Directory API Architecture

Description of "Figure 2-1 Identity Directory API Architecture"

Figure 2-2 shows the relationship between the Identity Directory API components.

Figure 2-2 Identity Directory API Components

Description of "Figure 2-2 Identity Directory API Components"

2.2.1 Logical Entity Configuration

Table 2-1 describes the logical entity configuration properties.

Table 2-2 describes the logical attributes.

Table 2-3 describes the properties required in each logical entity definition.

Table 2-4 describes the properties required in each logical entity relationship definition.

2.2.2 Physical Identity Store Configuration

Table 2-5 describes the physical identity store configuration properties.

2.2.3 Operational Configuration

The operational configuration contains mainly base, name attribute, and objectclass configuration for each of the entities.

Table 2-6 describes the operational configuration entities.

2.3.1 Keep the defaultFetch Attributes Minimal

While configuring a new Identity Directory, try to keep the number of entity defaultFetch attributes minimal. Also, try to have large attributes like jpegphoto configured with a defaultFetch value of false. The reason is every time the entity is read from the backend, all the defaultFetch attributes from backend directory will be retrieved. Too many defaultFetch attributes will affect the performance.

2.3.2 Initialize the Identity Directory Once

Initialization of Identity Directory has some overhead to initialize the entire ArisId stack. As a result, applications should initialize the Identity Directory once, preferably on application startup, and use only one handle throughout.

2.4.1 Initialize and Obtain Identity Directory Handle

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

import oracle.igf.ids.UserManager;
import oracle.igf.ids.GroupManager;
import oracle.igf.ids.config.OperationalConfig;
import oracle.igf.ids.IdentityDirectoryFactory;
import oracle.igf.ids.IdentityDirectory;
import oracle.igf.ids.IDSException;


public class IdsSample {

    private IdentityDirectory ids;
    private UserManager uMgr;
    private GroupManager gMgr;

    public IdsSample() throws IDSException {
        // Set Operational Config
        OperationalConfig opConfig = new OperationalConfig();

        // Set the application credentials (optional).  This
 overrides the credentials set in
        // physical ID store configuration 
opConfig.setApplicationUser("cn=user1,dc=us,dc=example,dc=com");
opConfig.setApplicationPassword("password".toCharArray());

        // Set search/crate base, name, objclass, etc. config
 (optional).  This overrides default operational configuration
 in IDS
        opConfig.setEntityProperty("User", opConfig.SEARCH_BASE,
 "dc=us,dc=example,dc=com");
        opConfig.setEntityProperty("User", opConfig.CREATE_BASE,
 "dc=us,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=groups,dc=us,dc=example,dc=com");
        opConfig.setEntityProperty("Group", opConfig.CREATE
_BASE, "cn=groups,dc=us,dc=example,dc=com");
        opConfig.setEntityProperty("Group", opConfig.FILTER
_OBJCLASSES, "groupofuniquenames");
        opConfig.setEntityProperty("Group", opConfig.CREATE
_OBJCLASSES, "groupofuniquenames");

        // Get IdentityDirectory "ids1" configured in IDS config
        IdentityDirectoryFactory factory = new
 IdentityDirectoryFactory();
        ids = factory.getIdentityDirectory("ids1", opConfig);

        // Get UserManager and GroupManager handles
        uMgr = ids.getUserManager();
        gMgr = ids.getGroupManager();
    }
}

2.4.2 Initialize and Obtain Identity Directory Handle from JPS Context

The following code sample initializes and obtains the identity directory handle from JPS context.

import oracle.igf.ids.UserManager;
import oracle.igf.ids.GroupManager;
import oracle.igf.ids.config.OperationalConfig;
import oracle.igf.ids.IdentityDirectoryFactory;
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;

public class IdsSample {

    private IdentityDirectory ids;
    private UserManager uMgr;
    private GroupManager gMgr;

    public IdsSample() throws IDSException {

        // Get IdentityDirectory from JpsContext
        try {
            JpsContext context =
JpsContextFactory.getContextFactory().getContext();
            IdentityStoreService idstore = (IdentityStoreService)
context.getServiceInstance(IdentityStoreService.class);
            ids = idstore.getIdentityStore();
        } catch (Exception e) {
            throw new IDSException(e);
        }        

 // Get UserManager and GroupManager handles
        uMgr = ids.getUserManager();
        gMgr = ids.getGroupManager();
    }
}

2.4.3 Initialize and Obtain In-Memory Identity Directory Handle

The following code sample initializes and obtains the in-memory identity directory handle.

import java.util.ArrayList;
import java.util.List;

import oracle.igf.ids.UserManager;
import oracle.igf.ids.GroupManager;
import oracle.igf.ids.config.AttributeDef;
import oracle.igf.ids.config.AttributeRef;
import oracle.igf.ids.config.EntityDef;
import oracle.igf.ids.config.EntitiesConfig;
import oracle.igf.ids.config.EntityRelationship;
import oracle.igf.ids.config.IdentityStoreConfig;
import oracle.igf.ids.config.OperationalConfig;
import oracle.igf.ids.IdentityDirectoryFactory;
import oracle.igf.ids.IdentityDirectory;
import oracle.igf.ids.IDSException;

public class IdsSample {

    private IdentityDirectory ids;
    private UserManager uMgr;
    private GroupManager gMgr;
    public IdsSample() throws IDSException {

        // Add Attribute definitions
        List<AttributeDef> attrDefs = new ArrayList<AttributeDef>();
        attrDefs.add(new AttributeDef("cn", AttributeDef.DataType.STRING));
        attrDefs.add(new AttributeDef("firstname", AttributeDef.DataType.STRING));
        attrDefs.add(new AttributeDef("sn", AttributeDef.DataType.STRING));
        attrDefs.add(new AttributeDef("telephonenumber",
 AttributeDef.DataType.STRING));
        attrDefs.add(new AttributeDef("uid", AttributeDef.DataType.STRING));
        attrDefs.add(new AttributeDef("uniquemember",
 AttributeDef.DataType.STRING));

        // Add User entity definition
        List<EntityDef> entityDefs = new ArrayList<EntityDef>();
        EntityDef userEntityDef = new EntityDef("User", EntityDef.EntityType.USER,
 "cn");
        userEntityDef.addAttribute(new AttributeRef("cn"));
        userEntityDef.addAttribute(new AttributeRef("firstname"));
        userEntityDef.addAttribute(new AttributeRef("sn"));
        userEntityDef.addAttribute(new AttributeRef("telephonenumber"));
        userEntityDef.addAttribute(new AttributeRef("uid"));
        entityDefs.add(userEntityDef);

        // Add Group entity definition
        EntityDef groupEntityDef = new EntityDef("Group",
 EntityDef.EntityType.GROUP, "cn");
        groupEntityDef.addAttribute(new AttributeRef("cn"));
        groupEntityDef.addAttribute(new AttributeRef("uniquemember", false,
 AttributeRef.FilterType.EQUALS));
        entityDefs.add(groupEntityDef);

        // Add Entity relationship definition
        List<EntityRelationship> entityRelations = new
 ArrayList<EntityRelationship>();
        entityRelations.add(new EntityRelationship("user_memberOfGroup",
                EntityRelationship.RelationshipType.MANYTOMANY, "User",
 "principal", "Group", "uniquemember"));
        entityRelations.add(new EntityRelationship("group_memberOfGroup",
                EntityRelationship.RelationshipType.MANYTOMANY, "Group",
 "principal", "Group", "uniquemember", true));
        EntitiesConfig entityCfg = new EntitiesConfig(attrDefs,
 entityDefs, entityRelations);


        // Create physical Identity Store configuration
        IdentityStoreConfig idStoreCfg = new IdentityStoreConfig(
            "ldap://host1:389,ldap://host2:389", "cn=orcladmin",
 "password".toCharArray(), IdentityStoreConfig.IdentityStoreType.OID);
       
 idStoreCfg.setHighAvailabilityOption(IdentityStoreConfig.HAOption.FAILOVER);
        idStoreCfg.setProperty(IdentityStoreConfig.HEARTBEAT_INTERVAL, "60");
        idStoreCfg.setProperty(IdentityStoreConfig.CONN_TIMEOUT, "30000");    //
 milli sec
        idStoreCfg.setProperty(IdentityStoreConfig.MIN_POOLSIZE, "5");
        idStoreCfg.setProperty(IdentityStoreConfig.MAX_POOLSIZE, "10");
        idStoreCfg.setProperty(IdentityStoreConfig.MAX_POOLWAIT, "1000");     //
 milli sec
        idStoreCfg.setProperty(IdentityStoreConfig.MAX_POOLCHECKS, "10");
        idStoreCfg.setProperty(IdentityStoreConfig.FOLLOW_REFERRAL, "false");
        idStoreCfg.setAttrMapping("firstname", "givenname");

        // Set operational config
        OperationalConfig opConfig = new OperationalConfig();
        opConfig.setEntityProperty(opConfig.USER_ENTITY, opConfig.SEARCH_BASE,
 "cn=users,dc=us,dc=example,dc=com");
        opConfig.setEntityProperty(opConfig.USER_ENTITY, opConfig.CREATE_BASE,
 "cn=users,dc=us,dc=example,dc=com");
        opConfig.setEntityProperty(opConfig.USER_ENTITY, opConfig.NAME_ATTR,
 "cn");
        opConfig.setEntityProperty(opConfig.USER_ENTITY, opConfig.FILTER
_OBJCLASSES, "inetorgperson");
        opConfig.setEntityProperty(opConfig.USER_ENTITY, opConfig.CREATE
_OBJCLASSES, "inetorgperson");
        opConfig.setEntityProperty(opConfig.GROUP_ENTITY, opConfig.SEARCH_BASE,
 "cn=groups,dc=us,dc=example,dc=com");
        opConfig.setEntityProperty(opConfig.GROUP_ENTITY, opConfig.CREATE_BASE,
 "cn=groups,dc=us,dc=example,dc=com");
        opConfig.setEntityProperty(opConfig.GROUP_ENTITY, opConfig.NAME_ATTR,
 "cn");
        opConfig.setEntityProperty(opConfig.GROUP_ENTITY, opConfig.FILTER
_OBJCLASSES, "groupofuniquenames");
        opConfig.setEntityProperty(opConfig.GROUP_ENTITY, opConfig.CREATE
_OBJCLASSES, "groupofuniquenames");

        // Initialize Identity Store Service
        IdentityDirectoryFactory factory = new IdentityDirectoryFactory();
        ids = factory.getIdentityDirectory("ids1", entityCfg, idStoreCfg,
 opConfig);

        // Get UserManager and GroupManager handles
        uMgr = ids.getUserManager();
        gMgr = ids.getGroupManager();
    }

}

2.4.4 Add User

The following code sample adds a user to the identity store:

Principal principal = null;
        
        List<Attribute> attrs = new ArrayList<Attribute>();
        attrs.add(new Attribute("commonname", "test1_user1"));
        attrs.add(new Attribute("password", "mypassword".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"));

        try {
            CreateOptions createOpts = new CreateOptions();

            principal = uMgr.createUser(attrs, createOpts);



            System.out.println("Created user " + principal.getName());

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.5 Get User for Given Principal

The following code sample gets a user for a given principal.

User user = null;

        try {
            ReadOptions readOpts = new ReadOptions();

            user = uMgr.getUser(principal, readOpts);
            
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.6 Modify User

The following code sample modifies a user in the identity directory.

try {
            ModifyOptions modifyOpts = new ModifyOptions();

            List<ModAttribute> attrs = new ArrayList<ModAttribute>();
            attrs.add(new ModAttribute("description", "modified test user 1"));

            user.modify(attrs, modifyOpts);
            

            System.out.println("Modified user " + user.getName());
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.7 Get User for Given ID Value

The following code sample gets a user matching the given identity value.

try {
            ReadOptions readOpts = new ReadOptions();

            User user = uMgr.searchUser("tuser1", readOpts);
            
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.8 Search Users Using Complex Search Filter

The following code sample shows how to search for users using a complex search filter.

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,
 "test"),
                  new SearchFilter("telephone", SearchFilter.Operator.CONTAINS,
 "650")),
                new SearchFilter(SearchFilter.LogicalOp.AND,
                  new SearchFilter("firstname", SearchFilter.Operator.BEGINS_WITH,
 "demo"),
                  new SearchFilter(SearchFilter.LogicalOp.OR,
                    new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH,
 "hr"),
                    new SearchFilter("orgunit", SearchFilter.Operator.BEGINS_WITH,
 "it"),
           
                  new SearchFilter("telephone", SearchFilter.Operator.CONTAINS,
 "650")));

            // Requesting attributes
            List<String> reqAttrs = new ArrayList<String>();
            reqAttrs.add("jpegphoto");

            SearchOptions searchOpts = new SearchOptions();
            searchOpts.setPageSize(100);
            searchOpts.setRequestedAttrs(reqAttrs);
            searchOpts.setSortAttrs(new String[] {"firstname"});

            ResultSet<User> sr = uMgr.searchUsers(filter, searchOpts);
            while (sr.hasMore()) {
                User user = sr.getNext();
                System.out.println(user.getSubjectName());
            }

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    

2.4.9 Change User Password

The following code sample shows how to change a user password.

ModifyOptions modOpts = new ModifyOptions();

        try {
            user.changePassword("welcome123".toCharArray(),
 "welcome1".toCharArray(), modOpts);
            System.out.println("Changed user password");
        } catch (Exception e) {
            System.out.println("Failed to change user password");
            e.printStackTrace();
        }

2.4.10 Reset User Password

The following code sample shows how to reset a user password.

ModifyOptions modOpts = new ModifyOptions();

        try {
            user.resetPassword("welcome123".toCharArray(), modOpts);
            System.out.println("Reset user password");
        } catch (Exception e) {
            System.out.println("Failed to reset user password");
            e.printStackTrace();
        }

2.4.11 Authenticate User

The following code sample shows how to authenticate a user.

        ReadOptions readOpts = new ReadOptions();
        try {
            User user = uMgr.authenticateUser("tuser1",
 "mypassword".toCharArray(), readOpts);   
            System.out.println("authentication success");
        } catch (Exception e) {
            System.out.println("Authentication failed. " + e.getMessage());
            e.printStackTrace();
        }

2.4.12 Delete User

The following code sample shows how to delete a user.

try {
            DeleteOptions deleteOpts = new DeleteOptions();

            uMgr.deleteUser(principal, deleteOpts);
            
            System.out.println("Deleted user " + principal.getName());

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.13 Create Group

The following code sample shows how to create a group.

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

2.4.14 Search Groups

The following code sample shows how to search 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();
        }

2.4.15 Get Management Chain

The following code sample shows how to get a management chain.

try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("tuser1", readOpts);

            SearchOptions searchOpts = new SearchOptions();
            searchOpts.setPageSize(10);
            int nLevels = 0;

            ResultSet<User> sr  = user.getManagementChain(nLevels, searchOpts);
            while (sr.hasMore()) {
                User u = sr.getNext();
                System.out.println(u.getSubjectName());
            }

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.16 Get Reportees of a User

The following code sample shows how to get the reportees of user.

// Get Reportees with target search filter
    public void getReportees() {

        try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("tuser1", readOpts);

            SearchOptions searchOpts = new SearchOptions();
            searchOpts.setPageSize(20);
            int nLevels = 0;

            // get all the direct/indirect reporting of tuser1 who are
 "developers"
            SearchFilter filter = new SearchFilter("title",
 SearchFilter.Operator.CONTAINS, "developer");
            ResultSet<User> sr  = user.getReportees(nLevels, filter, searchOpts);
            while (sr.hasMore()) {
                User u = sr.getNext();
                System.out.println(u.getSubjectName());
            }

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.17 Add a Member to a Group

The following code sample adds a member to a group.

try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("tuser1", readOpts);
            Group group = gMgr.searchGroup("test1_group1", readOpts);

            ModifyOptions modOpts = new ModifyOptions();
            user.addMemberOf(group, modOpts);

            System.out.println("added tuser1 as a member of test1_group1");

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.18 Delete a Member From Group

The following code sample deletes a member from a group.

try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("tuser1", readOpts);
            Group group = gMgr.searchGroup("test1_group1", readOpts);

            ModifyOptions modOpts = new ModifyOptions();
            group.deleteMember(user, modOpts);

            System.out.println("deleted tuser1 from the group test1_group1");

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }

2.4.19 Get All The Groups User is a Member

The following code sample gets all the groups in which user is a member.

try {
            ReadOptions readOpts = new ReadOptions();
            User user = uMgr.searchUser("tuser1", readOpts);

            SearchOptions searchOpts = new SearchOptions();
            searchOpts.setPageSize(10);
            int nLevels = 0;

            ResultSet<Group> sr  = user.getMemberOfGroups(nLevels, null,
 searchOpts);
            while (sr.hasMore()) {
                Group group = sr.getNext();
                System.out.println(group.getSubjectName());
            }

        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }