Developing with the User and Role API

19 Developing with the User and Role API

This chapter explains how to use the User and Role API to access, search, and modify entries in the identity store, and how to configure Secure Sockets Layer (SSL) with LDAP providers.

It includes the following sections:

About the User and Role API

Note:

The User and Role API is deprecated. Oracle recommends that you use instead the Identity Governance Framework and migrate usage to this framework. For information about this migration, see Migrating to Identity Directory API in Developing Applications with Identity Governance Framework.

The User and Role API allows applications to access identity information in a uniform and portable way regardless of the particular underlying identity repository. This repository can be an LDAP server, a database, a file, or some custom repository.

The User and Role API provides programmatic access to any repository, ensures portability, and helps you simplify application. For example, using this API, your application can access several repositories without requiring any changes to the application code.

This API includes methods to create, update, and delete users and roles, and search them for attributes; it allows you, for example, to obtain the email addresses of all users in a certain role.

To use the User and Role API from a Java container, the identity store must be LDAP and the Administration Server must be up and running. In addition, application role members must use the weblogic.security.principal.WLSUserImpl class.

Oracle recommends that you authenticate users with an authentication provider and that do not use User and Role API for that purpose, and that you do not use concurrently the User and Role API and other APIs accessing entries in the same LDAP server.

Developing Security Providers for Oracle WebLogic Server

Java API Reference for Oracle Platform Security Services User and Role

Authentication Providers and the User and Role API

The User and Role API uses, by default, the first authentication provider configured in the domain. If your application requires using any other configured authentication provider, then configure this special use as explained in Working with Service Providers.

When more than one provider is configured in the environment, you specify providers in an ordered list and set a control flag in each of them. Using this order and the control flags, the server determines which provider to use. After one is chosen, the remaining providers are ignored.

Working with Service Providers

To implement a provider, choose the provider class appropriate to the underlying repository, configure that provider, and then configure the provider runtime, as explained in the following sections:

See also:

Identity Assertion Providers in Developing Security Providers for Oracle WebLogic Server

Setting Up the Environment

The User and Role API interacts with the identity repository through an identity provider, which carries out the actual communication with the underlying repository. This offers flexibility because the same code can be used with different repositories by modifying the provider's connection information.

To configure your environment to use the User and Role API:

Ensure that the provider JAR file, which implements the underlying particular identity repository, and component JARs required by your provider are available in your environment.

Specify the object classes that the search method use:

     <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">
            <property name="idstore.config.provider"
value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider"/
>
            <property name="CONNECTION_POOL_CLASS"
value="oracle.security.idm.providers.stdldap.JNDIPool"/>
          <extendedProperty>
            <name>user.object.classes</name>
            <values>
               <value>top</value>
               <value>person</value>
               <value>inetorgperson</value>
               <value>organizationalperson</value>
               <value>otherActiveDirectorySpecificClasses</value>
               ...
            </values>
          </extendedProperty>

In case of an LDAP provider, configure the provider user so that it has permissions to read the cn=common,cn=products,cn=oraclecontext nodes.

Choosing the Provider Repository

OPSS supports a number of user repositories for an identity service provider. For systems and versions, see Oracle Fusion Middleware Supported System Configurations.

The choice of repository determines the provider class to use with the provider, as described in the following table:

Table 19-1 Repository and Provider Classes

Repository	Provider Class
Microsoft Active Directory	oracle.security.idm.providers.ad.ADIdentityStoreFactory
Novell eDirectory	oracle.security.idm.providers.edir.EDIdentityStoreFactory
Oracle Directory Server Enterprise Edition	oracle.security.idm.providers.iplanet.IPIdentityStoreFactory
Oracle Internet Directory	oracle.security.idm.providers.oid.OIDIdentityStoreFactory
OpenLDAP	oracle.security.idm.providers.openldap.OLdapIdentityStoreFactory
Embedded LDAP server	oracle.security.idm.providers.wlsldap.WLSLDAPIdentityStoreFactory
Oracle Virtual Directory	oracle.security.idm.providers.ovd.OVDIdentityStoreFactory
Microsoft ADAM	oracle.security.idm.providers.ad.ADIdentityStoreFactory
IBM Tivoli	oracle.security.idm.providers.openldap.OLdapIdentityStoreFactory

The provider class must implement the interface specified by the User and Role API framework. For information about this API, see Java API Reference for Oracle Platform Security Services.

Creating the Provider Instance

To create a provider instance after having identified the provider's class:

Use the IdentityStoreFactoryBuilder.getIdentityStoreFactory method to create a factory instance:
```
IdentityStoreFactoryBuilder builder =new IdentityStoreFactoryBuilder ();
   
```

Use the IdentityStoreFactory.getIdentityStoreInstance method to create a store instance:

IdentityStoreFactory oidFactory = builder.getIdentityStoreFactory(
   “oracle.security.idm.providers.oid.OIDIdentityStoreFactory", factEnv);

Obtain the handle to the identity store:

oidStore = oidFactory.getIdentityStoreInstance(storeEnv);

Configuring the Provider Start-Time and Runtime Properties

You can set a number of properties for the factory instance and the store instance, such as the URL, the repository port number, and the user and password to access the repository.

The following sections explain how to set these properties:

Configuring Start-Time and Runtime Properties

To configure the provider properties at start-time (when you create the provider) or at runtime, use properties including:

Start-time properties, with names prefixed with ST_.
Runtime properties, with names prefixed with RT_.

Start-time Configuration Properties

You configure start-time provider properties once because generally these values persist for the duration of the provider's lifetime.

Specify the property ST_SUBSCRIBER_NAME when you create the store instance, and all other start-time properties when you create the provider factory instance.

The following table describes the start-time identity provider properties.

Table 19-2 Start-Time Identity Provider Properties

Property Name	Description
ST_BINARY_ATTRIBUTES	The names of binary attributes stored in the LDAP server. The provider treats these attributes as binary data while sending and receiving data from the LDAP server.
ST_CONNECTION_POOL	The external connection pool, an instance of the `oracle.idm.connection.ConnectionPool` class. The provider uses this pool to acquire connections to the LDAP server, and the properties ST_SECURITY_PRINCIPAL, ST_SECURITY_CREDENTIALS, and ST_LDAP_URL are ignored.
ST_USER_NAME_ATTR	The provider user's name in the identity store.
ST_GROUP_NAME_ATTR	The provider user's role name in the identity store.
ST_USER_LOGIN_ATTR	The login ID of the provider's user in the identity store.
ST_SECURITY_PRINCIPAL	The user (principal).
ST_SECURITY_CREDENTIALS	The credentials to log in to the identity store.
ST_LDAP_URL	The URL of the identity store.
ST_MAX_SEARCHFILTER_LENGTH	The maximum length of the search filter allowed by the LDAP server.
ST_LOGGER	The logger that the API uses.
ST_SUBSCRIBER_NAME	The base distinguished name in the LDAP server. This property is specified when you create the IdentityStore instance and is used to determine default values for the remaining properties.
ST_CONNECTION_POOL_CLASS	The fully-qualified connection pool class name.
ST_INITIAL_CONTEXT_FACTORY	The fully-qualified class name of the factory that creates the initial context.

Runtime Configuration Properties

Runtime properties control the behavior of the provider's IdentityStore instance. You configure these properties by the specifying StoreConfiguration object that is obtained from the IdentityStore instance. All runtime properties have default values.

The following table describes the runtime identity provider properties.

Table 19-3 Runtime Identity Provider Properties

Property Name	Description
RT_USER_OBJECT_CLASSES	An array of classes required to create a user.
RT_USER_MANDATORY_ATTRS	Required attributes of a new user.
RT_USER_CREATE_BASES	Base DNs where a new user can be created.
RT_USER_SEARCH_BASES	Base DNs that can be searched for users.
RT_USER_FILTER_OBJECT_CLASSES	An array of classes used to search users.
RT_GROUP_OBJECT_CLASSES	An array of classes required to create a role.
RT_GROUP_MANDATORY_ATTRS	Required attributes of a new role.
RT_GROUP_CREATE_BASES	Base DNs where a new role can be created.
RT_GROUP_SEARCH_BASES	Base DNs that can be searched for roles.
RT_GROUP_MEMBER_ATTRS	An array of attributes in a role. All members of a role have a value for each of these attributes.
RT_GROUP_FILTER_OBJECT_CLASSES	An array of classes used to search roles.
RT_USER_SELECTED_CREATE_BASE	The distinguished name where a user is created with `createUser`. If null and the ST_SUBSCRIBER_NAME is unspecified, then the first supplied value of the RT_USER_CREATE_BASE is used. If null and the ST_SUBSCRIBER_NAME is specified, then the subscriber name of the identity store is used.
RT_GROUP_SELECTED_CREATE_BASE	The distinguished name where a role is created with `createRole`. If null and the ST_SUBSCRIBER_NAME is unspecified, then the first supplied value of the RT_GROUP_CREATE_BASE is used. If null and the ST_SUBSCRIBER_NAME is specified, then the subscriber name of the identity store is used.
RT_GROUP_GENERIC_SEARCH_BASE	The distinguished name where to search roles for a given identity. In LDAP providers, it is set, by default, to the subscriber name or else to the first group search base.
RT_SEARCH_TYPE	The type of search: SIMPLE, PAGED, or VIRTUAL_LIST_VIEW.

Enabling Execution Context ID

ECID enabling is required only for LDAP identity stores. By default, ECID support is disabled in the User and Role API. To enable it, set the ST_ECID_ENABLED property to true when initializing the API:

factEnv.put(OVDIdentityStoreFactory.ST_ECID_ENABLED, "true");

Configuring the Provider when Creating a Factory Instance

Configuration at this stage affects the entire factory object as well as objects created using the specific factory instance. Many start-time properties are set at this time, including ST_LDAP_URL, ST_SECURITY_PRINCIPAL, and ST_SECURITY_CREDENTIAL.

The following sections illustrate how to configure provider properties when you create a factory instance:

Configuring Common Properties

The following example illustrates a provider configuration at the time the LDAP factory is created, including the specification of a log location:

IdentityStoreFactoryBuilder builder = new IdentityStoreFactoryBuilder();
IdentityStoreFactory oidFactory = null;
Hashtable factEnv = new Hashtable();
Logger mylogr = Logger.getLogger("mylogger.abc.com");
FileHandler fh = new FileHandler("userroleapi.log");
mylogr.addHandler(fh);
factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_PRINCIPAL,"User DN");
factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_CREDENTIALS,"User password");
factEnv.put(OIDIdentityStoreFactory.ST_LDAP_URL,"ldap://ldaphost:port/");
factEnv.put(OIDIdentityStoreFactory.ST_LOGGER_NAME, "mylogger.abc.com");
oidFactory = builder.getIdentityStoreFactory(
   "oracle.security.idm.providers.oid.OIDIdentityStoreFactory", factEnv);

Configuring Constants, Number of Connections, and Pool Connection

To overwrite constants and default property values, supply a map in the ST_PROPERTY_ATTRIBUTE_MAPPING property during factory creation.

The following example illustrates how to set the maximum and minimum number of connections, the custom connection pool class, and the map of the RoleProfile.OWNER user to the myowner attribute:

factEnv.put(LDIdentityStoreFactory.ST_CONNECTION_POOL_MIN_CONNECTIONS,  "3");
factEnv.put(LDIdentityStoreFactory.ST_CONNECTION_POOL_MAX_CONNECTIONS, "16");

factEnv.put(OIDIdentityStoreFactory.ST_CONNECTION_POOL_CLASS,
"oracle.security.idm.providers.stdldap.JNDIPool");

factEnv.put(IPIdentityStoreFactory.ST_SECURITY_PRINCIPAL, "<User DN>");
factEnv.put(IPIdentityStoreFactory.ST_SECURITY_CREDENTIALS, "<User password>");
factEnv.put(IPIdentityStoreFactory.ST_LDAP_URL,"ldap://ldaphost:port/");
Map m = new Hashtable();
m.put(RoleProfile.OWNER, "myowner");
factEnv.put(IPIdentityStoreFactory.ST_PROPERTY_ATTRIBUTE_MAPPING, m);
ipFactory = builder.getIdentityStoreFactory(
   "oracle.security.idm.providers.iplanet.IPIdentityStoreFactory",
   factEnv);

All owner-related operations, such as getOwners, and getOwnedRoles are performed using the myowner attribute. The maximum minus the minimum connection values must be greater than 10.

Configuring the Provider when Creating a Store Instance

The identity store configuration applies to the store and all objects created with the store instance, and you specify the runtime property you want when you create the identity store instance.

The following example illustrates how to create a store instance and how to get a handle for it:

IdentityStore oidStore = null;
Hashtable storeEnv = new Hashtable();
storeEnv.put(OIDIdentityStoreFactory.ST_SUBSCRIBER_NAME,"dc=us,dc=oracle,dc=com");
oidStore = oidFactory.getIdentityStoreInstance(storeEnv);

Configuring the Provider at Runtime

To facilitate adding and modifying properties at runtime, the User and Role API provides the getStoreConfiguration method. For example, to set RT_USER_SEARCH_BASES at runtime:

StoreConfiguration conf = oidStore.getStoreConfiguration();
conf.setProperty(“RT_USER_SEARCH_BASES", “dc=us,dc=oracle,dc=com");

Programming Guidelines

The following sections contain recommendations to consider when you work with providers and provider artifacts:

Switching Providers

To ensure that your application works after switching providers, consider the following guidelines:

Use the constants specified in oracle.security.idm.UserProfile only to refer to user properties. Avoid using native constants, which are not portable. For example, if you must obtain a user's login name, then fetch it using the UserProfile.USER_NAME constant:
```
Property prop = usrprofile.getProperty(UserProfile.USER_NAME);
```

Use code like the following to obtain all the properties of a user,

UserProfile upf = null;
List proplst = store.getUserPropertyNames();
String[] proparr = (String[]) proplst.toArray(new String[proplst.size()]);
PropertySet pset = upf.getProperties(proparr);

Do not use native wildcard characters directly in your search filter string when you create search filters. Use instead the SimpleSearchFilter.getWildCardChar method that fetches the correct wildcard character for the provider:
```
SmpleSearchFilter sf = m_identityStore.getSimpleSearchFilter(
   attrName, SimpleSearchFilter.TYPE_EQUAL, null); 
sf.setValue(filterStringWithoutWildcard+sf.getWildCardChar());
```
For example, the method returns % for a database provider and * for an LDAP provider.

Apply the following conversion on the filter while generating the User and Role API filter, if your application accepts user-supplied filter strings with a predefined wildcard character:

//User supplied filter assumes “%" as the wildcard character
String userDefinedFilter = .................
SmpleSearchFilter sf = m_identityStore.getSimpleSearchFilter(
   attrName, SimpleSearchFilter.TYPE_EQUAL, null);
userDefinedFilter = userDefinedFilter.replaceall("%", sf.getWildCardChar());
sf.setValue(userDefinedFilter);

Using Identity Store Objects

When implementing your application, consider the following points:

The identity store implementations are not thread-safe. The User and Role API assumes that the store instances are not shared among threads. If the store instance is shared among threads, then the application code must take care to handle any required thread safety issues.
Some applications allow a user session to change the create and search bases and various other runtime properties, which you define as runtime properties, and the identity store changes its runtime behavior according to these settings. The framework allows only one identity store instance per session.

The Provider's Lifetime

A provider persists in the environment until you close the factory instance. When the provider instance ends, all the objects that were created with that instance become invalid and subsequent calls on them throw an exception. When you close a factory instance, it is recommended that you explicitly close server connections and delete no longer valid instances. Factory instances are thread-safe, but identity store instances are not.

Similar considerations apply to closing the identity store instance.

Searching the Identity Store

Queries to the identity store can return a single identity or multiple ones. The following sections explain how to use the User and Role API to query the identity store:

Searching for a Specific Identity

To query for a specific identity or role use any the following methods:

IdentityStore.searchUser(String name);
IdentityStore.searchUser(Principal principal);
IdentityStore.searchUser(int searchType, String name); 
IdentityStore.searchRole(int searchType, String value);

Use these methods when you must get the object reference to a known identity kept in the store. They raise an exception if multiple entities with the same value are found in the store.

Searching for Multiple Identities

To query for multiple identities or roles use any of the following methods:

IdentityStore.search(SearchParams params);
IdentityStore.searchUsers(SearchParams params);
IdentityStore.searchRoles(int searchType, SearchParams params);
IdentityStore.searchProfiles(SearchParams params);

Using Search Filters

The User and Role API includes a number of search filters that facilitate a variety of search operations. The following sections explain the use of search filters:

Filter Operators

The User and Role API supports the operators "=", "<",">", "<=" and ">=" which are used to create simple search filters, and the operators "&" and "|" which are used to combine two or more search strings to make a complex search filter.

Use the NOT operator in a simple or a complex search filter. The negated filter returns the entities which were rejected by the filter.

Filter for Logged-In User and Role

Applications commonly must retrieve the identity of the logged-in user and the user's group name. The user.login.attr and groupname.attr attributes are set when a user logs in, and you use the UserProfile.getUserName and RoleProfile.getProperty(RoleProfile.NAME) methods to get their values.

The following example shows how to query a logged in user:

SimpleSearchFilter sf = oidStore.getSimpleSearchFilter(
      UserProfile.USER_NAME,  SimpleSearchFilter.TYPE_EQUAL, "sampleUserName");
   SearchParameters ssp = new SearchParameters(sf, SearchParameters.SEARCH_USERS_ONLY);
 
   SearchResponse resp = oidStore.searchUsers(ssp);
   System.out.println("Searched users are:");
   while (resp.hasNext()) {
       Identity idy = resp.next();
       String foundUserName = ((User)idy).getUserProfile().getUserName();
       System.out.println("Found user name: "+ foundUserName );
   }

The following example shows how to query the logged-in user's role:

Role aRole = idStore.searchRole(IdentityStore.SEARCH_BY_NAME, "sampleRoleName");
    Property prop = aRole.getRoleProfile().getProperty(RoleProfile.NAME);
   
    List roleList = prop.getValues();
    Iterator itr = roleList.iterator(); 
   System.out.println("Searched roles are:");
    while (itr.hasNext()) {
        String foundRoleName = (String)itr.next();
        System.out.println("Found role name: "+ foundRoleName );
    }

Filters Examples

The implementation of a simple search filter depends on the underlying store. In the following example, the filter allows all entries with value not null for the NAME field:

SimpleSearchFilter sf = 
   oidStore.getSimpleSearchFilter(UserProfile.NAME, 
   SimpleSearchFilter.TYPE_EQUAL, null);
sf.setValue(sf.getWildCardChar());

The following example retrieves users whose preferred language is not English:

SimpleSearchFilter sf = 
   oidStore.getSimpleSearchFilter(
      UserProfile.PREFERRED_LANGUAGE, 		
      SimpleSearchFilter.TYPE_EQUAL,
      "english");
sf.negate();

The following example combines multiple search filters with operators "&" or "|". It searches for users whose name starts with a letter between "a" and "j":

SimpleSearchFilter sf1 = 
   oidStore.getSimpleSearchFilter(
      UserProfile.NAME,
      SimpleSearchFilter.TYPE_GREATER,
      null);
 
sf1.setValue("a"+sf1.getWildCardChar());
SimpleSearchFilter sf2 = 
   oidStore.getSimpleSearchFilter(UserProfile.NAME, 
      SimpleSearchFilter.TYPE_LESS, null);
sf2.setValue("j"+sf2.getWildCardChar());
SimpleSearchFilter sfArray[] = new SimpleSearchFilter[] {sf1, sf2};
ComplexSearchFilter cf1 = 
store.getComplexSearchFilter(sfArray, ComplexSearchFilter.TYPE_AND);

To use of nested filters to search for users whose name starts with a letter between "a" and "j" but not with the letter "i":

[continues from previous example]
SimpleSearchFilter sf3 = 
   oidStore.getSimpleSearchFilter(UserProfile.NAME,SimpleSearchFilter.TYPE_EQUAL,null);
sf3.setValue(“i"+sf3.getWildCardChar());
sf3.negate();
 
SearchFilter sfArray2[] = new SearchFilter[] {cf1, sf3};
ComplexSearchFilter cf2 = 
   store.getComplexSearchFilter(sfArray2, ComplexSearchFilter.TYPE_AND);

The following example filters names starting with the letter A and prints the return values:

// search filter (cn=a*)
SimpleSearchFilter sf = 
   oidStore.getSimpleSearchFilter(UserProfile.NAME,SimpleSearchFilter.TYPE_EQUAL,null);
sf.setValue("a"+sf.getWildCardChar());
      
SearchParameters params = new SearchParameters();
params.setFilter(sf);
 
// Search users
SearchResponse resp = oidStore.searchUsers(params);
System.out.println("Searched users are:");
while (resp.hasNext()) {
   Identity idy = resp.next();
   System.out.println("Unique name: "+idy.getUniqueName());
}

Creating and Modifying Entries in the Identity Store

The User and Role API allows you to add and modify identities with the use of the UserManager and RoleManager classes. To obtain UserManager and RoleManager instances from a store instance, use the following calls:

UserManager um = storeInst.getUserManager();
RoleManager rm = storeInst.getRoleManager();

The following sections provide examples that illustrate:

Creating Identities and Roles

To create a new identity, use one of the following methods in the UserManager class:

createUser(java.lang.String name, char[] password)
createUser(java.lang.String name, char[] password, PropertySet suppliedProps)

The second method sets user properties with the passed values. Required attribute values not supplied are given default values.

To create a new role, use one of the following methods in the RoleManager class:

createRole(String roleName);
createRole(String roleName, int roleScope);

Roles are created, by default, with the enterprise scope.

Modifying an Identity

To modify an identity, first obtain a reference to it. Then use the setProperty method in the User, UserProfile, Role, or RoleProfile classes to modify the identity.

To replace a display name:

UserProfile usrprofile = usr.getUserProfile();
ModProperty mprop = new ModProperty(UserProfile.DISPLAY_NAME,
   "modified display name",
   ModProperty.REPLACE);
usrprofile.setProperty(mprop);

Valid operators are: ADD, REMOVE, and REPLACE.

To modify a value in an attribute with multiple values, first remove the value you want to modify, and then add the modified value.

Deleting an Identity

To delete an identity, first obtain the user and role references, and then use the dropUser and dropRole methods:

User usr;
Role role;
usrmanager.dropUser(usr);
rolemanager.dropRole(role);

User and Role API Examples

The following examples illustrate the use of the User and Role API to query and manage users:

Searching Users Example

The following example illustrates how to set up a search filter to query users. To query groups, use the RoleProfile class. To query users, use the UserProfile class.:

import oracle.security.idm.*;
import oracle.security.idm.providers.oid.*;
import java.util.*;
import java.io.*;
 
public class SearchUsersOID
{
  public static void main(String args[])
  {
    IdentityStoreFactoryBuilder builder = new    
IdentityStoreFactoryBuilder();
    IdentityStoreFactory oidFactory = null;
    IdentityStore oidStore = null;
 
    try
    {
      Hashtable factEnv = new Hashtable();
      Hashtable storeEnv = new Hashtable();
      // creating the factory instance
      factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_PRINCIPAL,"<User DN>");
      factEnv.put(OIDIdentityStoreFactory.ST_SECURITY_CREDENTIALS,"<User password>"); 
      factEnv.put(OIDIdentityStoreFactory.ST_LDAP_URL,"ldap://ldaphost:port/");
oidFactory =  builder.getIdentityStoreFactory(
              "oracle.security.idm.providers.oid.OIDIdentityStoreFactory", 
              factEnv);
      
         storeEnv.put(OIDIdentityStoreFactory.RT_SUBSCRIBER_NAME,
         "<Subscriber name>");
      oidStore = oidFactory.getIdentityStoreInstance(storeEnv);

      // search filter (cn=a*)
      SimpleSearchFilter sf = oidStore.getSimpleSearchFilter(
                    UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, null);
      sf.setValue("a"+sf.getWildCardChar());

// sf2 search filter (!(cn=*a)) 
SimpleSearchFilter sf2 = oidStore.getSimpleSearchFilter(
                    UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, null);
sf2.setValue(sf2.getWildCardChar()+"a");
sf2.negate();
      
SimpleSearchFilter sfArray[] = new SimpleSearchFilter[] {sf,sf2};
ComplexSearchFilter cf1 = oidStore.getComplexSearchFilter(sfArray,
ComplexSearchFilter.TYPE_AND);
SearchParameters params = new SearchParameters();
params.setFilter(cf1);
 
// Searching for users
SearchResponse resp = oidStore.searchUsers(params);
System.out.println("Searched users are:");
while (resp.hasNext()) {
    Identity idy = resp.next();
    System.out.println("Unique name: "+idy.getUniqueName());
}
    }catch (IMException e)
    {
      e.printStackTrace();
    }
  }
}

Managing Users Example

To create, modify, and delete an identity in a Microsoft Active Directory store:

package oracle.security.idm.samples;
import oracle.security.idm.*;
import oracle.security.idm.providers.ad.*;
import java.util.*;
import java.io.*;
 
public class CreateModifyDeleteUserAD
{
  public static void main(String args[])
  {
    IdentityStoreFactoryBuilder builder = new IdentityStoreFactoryBuilder();
    IdentityStoreFactory adFactory = null;
    IdentityStore adStore = null;
    try
    {
      Hashtable factEnv = new Hashtable();
      Hashtable storeEnv = new Hashtable();
 
      String keystore = "/home/bhusingh/client_keystore.jks";
      System.setProperty("javax.net.ssl.trustStore",keystore);
      System.setProperty("javax.net.ssl.trustStorePassword","password");
 
      // create the factory
      factEnv.put(ADIdentityStoreFactory.ST_SECURITY_PRINCIPAL,
                  "sramaset@xyzt.com");
      factEnv.put(ADIdentityStoreFactory.ST_SECURITY_CREDENTIALS,"ntrtntrt"); 
      factEnv.put(ADIdentityStoreFactory.ST_LDAP_URL,
                  "ldaps://mynode.us.mycorp.com:123/");
      factEnv.put("java.naming.security.protocol","SSL");
      adFactory =  builder.getIdentityStoreFactory(
           "oracle.security.idm.providers.ad.ADIdentityStoreFactory",factEnv);
 
      // create the store
      storeEnv.put(ADIdentityStoreFactory.ST_SUBSCRIBER_NAME, 
                   "dc=upad,dc=us,dc=oracle,dc=com");
      adStore = adFactory.getIdentityStoreInstance(storeEnv);
 
      //get UserManager and create user
      UserManager usrmanager = adStore.getUserManager();
      String usrname = "amyd";
      try
      {
        User usr = adStore.searchUser(usrname);
        usrmanager.dropUser(usr);
      }catch(IMException ime){}
 
      System.out.println("creating user "+usrname);
      char[] password = {'w', 'e', 'l', 'c', 'o', 'm','e','3'};
      User usr = usrmanager.createUser(usrname, password);
      System.out.println("user (" +usr.getUniqueName() + ") created with guid="+usr.getGUID());
      System.out.println("user name = "+usr.getName() );
 
      // modify user
      System.out.println("DISPLAY_NAME="+usr.getDisplayName());
      System.out.println("modifying property UserProfile.DISPLAY_NAME");
      UserProfile usrprofile = usr.getUserProfile();
      ModProperty mprop = new ModProperty(UserProfile.DISPLAY_NAME,
                                          "modified display name",
                                          ModProperty.REPLACE);
      usrprofile.setProperty(mprop);
      System.out.println("get property values UserProfile.DISPLAY_NAME");
      Property prop = usrprofile.getProperty(UserProfile.DISPLAY_NAME);
      List values = prop.getValues();
      Iterator itr = values.iterator();
      while(itr.hasNext())
      {
        System.out.println(UserProfile.DISPLAY_NAME+": "+ itr.next());
      }
      System.out.println();
 
      System.out.println("verifying the password");
      boolean pass = false;
      try
      {
        usrmanager.authenticateUser(usrname, password);
        pass= true;
      }catch (oracle.security.idm.AuthenticationException e) 
      {
        System.out.println(e);
        e.printStackTrace();
      }
      if (pass)
        System.out.println("password verification succeded");
      else
        System.out.println("password verification failed");
 
      SimpleSearchFilter sf = adStore.getSimpleSearchFilter(
                    UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, usrname);
      
      SearchParameters params = new SearchParameters();
      params.setFilter(sf);
 
      // Search users
      SearchResponse resp = adStore.searchUsers(params);
      System.out.println("Searched users are:");
      while (resp.hasNext())
      {
        Identity idy = resp.next();
        System.out.println("name: "+idy.getName()+"\tUnique name: "+idy.getUniqueName());
      }
 
      // delete user
      System.out.println("deleting user "+usrname);
      usrmanager.dropUser(usr);
      System.out.println("user dropped");
    }catch (Exception e)
    {
      e.printStackTrace();
    }
  }
}

Configuring SSL for LDAP Providers

The following sections describe the User and Role API support for SSL connections to providers:

Setting Up SSL to Providers

LDAP providers for the User and Role API rely on the Java Secure Sockets Extension (JSSE) to provide SSL with LDAP identity stores.

To set up the ready-to-use SSL:

Specify values for the keystore and key password and set system properties:

String keystore = "<keystore location>";
String keypasswd = "<keystore password>";
System.setProperty("javax.net.ssl.trustStore",keystore);
System.setProperty("javax.net.ssl.trustStorePassword", keypasswd);

Set the SSL URL of the LDAP server:

factEnv.put(ADIdentityStoreFactory.ST_LDAP_URL,
 "ldaps://ldaphost:sslport/");

Set the security protocol to SSL:

factEnv.put("java.naming.security.protocol","SSL");

See also:

Configuring SSL for the Identity Store

Customizing SSL to Providers

To customize SSL:

Specify the custom SSL socket factory name:

factEnv.put("java.naming.ldap.factory.socket", 
"fully qualified custom socket factory name");

Set the SSL URL of the LDAP server:

factEnv.put(ADIdentityStoreFactory.ST_LDAP_URL,
 "ldaps://ldaphost:sslport/");

Set the security protocol to SSL:

factEnv.put("java.naming.security.protocol","SSL");