7 Configuring the Identity Store Service

This chapter explains how to use the identity store service in OPSS. Topics include:

Introduction to the Identity Store Service
Configuring the Identity Store Provider
Configuring the Identity Store Service
Querying the Identity Store Programmatically

7.1 Introduction to the Identity Store Service

This section describes key concepts of the OPSS identity store service:

About the Identity Store Service
Service Architecture
Application Server Support

7.1.1 About the Identity Store Service

The identity store service enables you to query the identity store for user and role (group) information.

By default, a service instance supports querying against a single LDAP identity store. You can configure the service to support a virtualized identity store which queries multiple LDAP identity stores. This feature, known as identity virtualization, is described in Section 7.3, "Configuring the Identity Store Service".

7.1.2 Service Architecture

Figure 7-1 shows the architecture of the identity store service. Depending on the configuration, the service can support:

one or more LDAP servers
an XML file

as the identity store.

When the service is configured for LDAP, it queries a single LDAP store by default. You can also configure the service to query multiple LDAP stores.

Figure 7-1 The OPSS Identity Store Service

7.1.3 Application Server Support

The identity store service supports:

Oracle WebLogic Server
Third-party application servers

The service configuration differs depending on the application server as you need to specify the provider that supports the service.

7.1.4 Java SE Support

The identity store service is available in a stand-alone Java SE environment.

For more information, see Section 7.3.5, "Java SE Environments".

7.2 Configuring the Identity Store Provider

Before you can make use of the identity store service, you need to configure the identity store provider. OPSS support both XML- and LDAP-based providers.

This fragment from the jps-config.xml file shows the configuration of both XML and LDAP providers. The serviceProvider elements are children of the serviceProviders element.

<serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider" class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider">
      <description>LDAP-based IdentityStore Provider</description>
</serviceProvider>
 
<serviceProvider type="IDENTITY_STORE" name="idstore.xml.provider" class="oracle.security.jps.internal.idstore.xml.XmlIdentityStoreProvider">
      <description>XML-based IdentityStore Provider</description>
</serviceProvider>

For details, see Section 8.7.1, "Configuring the Identity Store Provider".

7.3 Configuring the Identity Store Service

This section describes how to configure the identity store service to LDAP-based stores.

What is Configured?
Configuration in WebLogic Server
Configuring Split Profiles
Configuration in Other Application Servers
Java SE Environments

7.3.1 What is Configured?

This section explains the different configuration parameters for the identity store service.

Configuring Multi-LDAP Lookup
Global/Connection Parameters
Back-End/Connection Parameters

7.3.1.1 Configuring Multi-LDAP Lookup

You use the following parameters to configure the service for multi-LDAP look-ups:

The virtualize property - This property can be either true (multi-LDAP lookup) or false (single-LDAP lookup). The default is false.
Global Connection Parameters (if 'virtualize' is enabled) - The calling application uses these parameters to specify global LDAP configuration such as the search base, create base, and so on. If any of these parameters are not configured, OPSS uses default values.
Back-end Connection Parameters - These parameters are specific to each LDAP store. One set of back-end parameters is specified for each LDAP. You do not need to set these parameters unless you wish to overwrite existing values.

7.3.1.2 Global/Connection Parameters

Table 7-1 shows the global parameters and their default values, if applicable:

Table 7-1 Global LDAP Identity Store Parameters

Parameter	Default Value
group.create.bases	same as user.create.bases
group.filter.object.classes	groupofuniquenames If the global value is explicitly given, it is used.
group.mandatory.attrs	-
group.member.attrs	uniquemember
group.object.classes	groupofuniquenames
group.search.bases	-
group.selected.create.base	-
group.selected.search.base	-
groupname.attr	cn If the global value is explicitly given, it is used.
max.search.filter.length	-
search.type	-
user.create.bases	If only one authenticator, uses that create base value. If multiple authenticators, no default value is set; user must explicitly set the global value.
user.filter.object.classes	inetorgperson
user.login.attr	uid
user.mandatory.attrs	-
user.object.classes	inetorgperson If the global value is explicitly given, it is used.
user.search.bases	Same as group.search.bases
username.attr	cn If the global value is explicitly given, it is used.

7.3.1.3 Back-End/Connection Parameters

As mentioned earlier, these are specific to the back-end LDAP store. For details, see:

7.3.2 Configuration in WebLogic Server

You configure LDAP authenticators in Oracle WebLogic Server using either the WebLogic console or WLST command-line; at runtime, Oracle WebLogic Server passes the configuration details to OPSS. Oracle WebLogic Server allows the configuration of multiple authenticators in a given context, selecting the first authenticator to initialize the identity store service by default. This process is explained in Section 3.1.2.2, "Configuring the LDAP Identity Store Service".

After the authenticators are configured, the identity store service can be set up to query one LDAP identity store or multiple stores. Configuring for multiple stores requires setting up the virtualize property.

This section explains how these options are set up.

7.3.2.1 Configuring the Service for Single LDAP

You can configure the identity store service to query only one LDAP store. Example 7-1 shows a fragment of jps-config.xml with a single LDAP service instance:

7.3.2.2 Configuring the Service for Multiple LDAP using Fusion Middleware Control

As in the single LDAP setup, you start by configuring the authentication providers in Oracle WebLogic Server.

Next, take these steps in Fusion Middleware Control:

Select the WebLogic domain in the navigation pane on the left.
Navigate to Security, then Security Provider Configuration.
Expand the Identity Store Provider section of the page.
Click Configure (corresponding to "Configure parameters for User and Role APIs to interact with identity store").
The Identity Store Configuration page appears.
Under Custom Properties, click Add.
Add the new property as follows:
```
Property Name=virtualize
Value=true
```
Note:
Be sure to add the property to the identity store service instance in the default context.
Click OK.

7.3.2.3 Configuring the Service for Multiple LDAP using WLST

To configure the virtualize property using WLST, take these steps:

Create a py script file to connect to the administration server in the domain of interest. You need to specify the userName, userPass, localHost, and portNumber for the operation.

See Appendix E, "Configuring OPSS Service Provider Instances with a WLST Script" for details about this script.
Navigate to $ORACLE_HOME/common/bin.
Run the wlst.sh command to execute the script.

For example, if the domain configuration file contains an authenticator named idstore.ldap, the following command:
```
wlst.sh /tmp/updateServiceInstanceProperty.py -si idstore.ldap  -key "virtualize" -value "true"
```
configures the provider for multi-LDAP lookup.

7.3.2.4 Configuring Other Parameters

If desired, you can update jps-config.xml to set query parameters listed in Section 7.3.1, "What is Configured?". These parameters are optional; default values are provided.

7.3.2.5 Restarting Servers

After configuring for multi-LDAP query, restart Weblogic servers (admin and managed servers).

7.3.2.6 Examples of the Configuration File

Example 7-1 shows a sample jps-config.xml file configured for single-LDAP queries in the Oracle WebLogic Server environment:

Example 7-1 Single-LDAP Configuration in Oracle WebLogic Server

<!-- JPS WLS LDAP Identity Store Service Instance -->
        <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/>
        </serviceInstance>

Example 7-2 shows a sample jps-config.xml file configured for multi-LDAP queries in the Oracle WebLogic Server environment:

Example 7-2 Multi-LDAP Configuration in Oracle WebLogic Server

<jpsConfig xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd" schema-major-version="11" schema-minor-version="1">
 
 <serviceProviders>
        <serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider" 
                 class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider">
            <description>LDAP-based IdentityStore Provider</description>
        </serviceProvider>
 </serviceProviders>
 
 <serviceInstances>
        <!-- IDstore instance connecting to multiple ldap  -->
        <serviceInstance name="idstore.virtualize" provider="idstore.ldap.provider">
 
            <!-- following property indicates using WLS ldap Authenticators -->
            <property name="idstore.config.provider" 
                 value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider"/>
 
             <!-- following property enables virtualization i.e., support for multiple stores -->
            <property name="virtualize" value="true"/>
 
            <!-- Front end ldap properties (if not supplied, will use default values) --> 
            <extendedProperty>
                <name>user.create.bases</name>
                <values>
                   <value>cn=users_front,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.create.bases</name>
                <values>
                  <value>cn=groups_front,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
        </serviceInstance>
 </serviceInstances>
 
  <jpsContexts default="default">
 
        <!-- the identity store uses multiple ldaps -->
        <jpsContext name="default">
            <!-- use multiple ldap -->
            <serviceInstanceRef ref="idstore.virtualize"/>    
            <!-- .....other services -->
        </jpsContext>
  </jpsContexts>
 
</jpsConfig>

Note that:

the virtualize property of the service instance is set to true, enabling multi-LDAP queries
the extendedProperty element enables you to set front-end parameters if desired to override default values

For more information, see "Front-End Parameters" in Section 7.3.1, "What is Configured?".

7.3.3 Configuring Split Profiles

Identity Virtualization supports a "split profile," where an application makes use of attributes for a single identity that are stored on two different sources.

This feature requires additional configuration beyond that described in this chapter. For details, see Appendix K, "Adapter Configuration for Identity Virtualization".

7.3.4 Configuration in Other Application Servers

Topics in this section include:

Configuring the Service for Single LDAP
Configuring the Service for Multiple LDAP

7.3.4.1 Configuring the Service for Single LDAP

See the example in Section 22.2.2, "Configuring an LDAP Identity Store in Java SE Applications," for details.

7.3.4.2 Configuring the Service for Multiple LDAP

To configure the identity store service to handle multiple LDAPs in third-party application servers:

Modify the jps-config.xml file to configure service instances for each supported LDAP directory
Restart the application server to make the changes effective.

Example 7-3 shows a sample jps-config.xml file configured to run multi-LDAP queries for third-party application servers:

Example 7-3 Multi-LDAP Configuration in Third-Party Application Servers

<jpsConfig xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd" schema-major-version="11" schema-minor-version="1">
 
 <serviceProviders>
        <serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider"                     
                class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider">
            <description>LDAP-based IdentityStore Provider</description>
        </serviceProvider>
 </serviceProviders>
 
 <serviceInstances>
          <!-- instance 'idstore.oid'  to represent an ldap server 'oid' -->
            <serviceInstance name="idstore.oid" provider="idstore.ldap.provider">
            <property name="subscriber.name" value="dc=us,dc=oracle,dc=com"/>
            <property name="idstore.type" value="OID"/>
            <property name="security.principal.key" value="oid.ldap.credentials"/>
            <property name="security.principal.alias" value="JPS"/>
            <property name="ldap.url" 
                value="ldap://oid1.us.oracle.com:389,ldap://oid2.us.oracle.com:389"/>
            <extendedProperty>
                <name>user.search.bases</name>
                <values>
                   <value>cn=users,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.search.bases</name>
                <values>
                  <value>cn=groups,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>username.attr</name>
                <values>
                  <value>uid</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>groupname.attr</name>
                <values>
                  <value>cn</value>
                </values>
            </extendedProperty>
            </serviceInstance>
 
          <!-- instance 'idstore.ad' to represent an ldap server 'ad' -->
            <serviceInstance name="idstore.ad" provider="idstore.ldap.provider">
            <property name="subscriber.name" value="dc=us,dc=oracle,dc=com"/>
            <property name="idstore.type" value="ACTIVE_DIRECTORY"/>
            <property name="security.principal.key" value="msad.ldap.credentials"/>
            <property name="security.principal.alias" value="JPS"/>
            <property name="ldap.url" 
                value="ldap://msad1.us.oracle.com:389,ldap://msad2.us.oracle.com:389"/>
            <extendedProperty>
                <name>user.search.bases</name>
                <values>
                   <value>cn=users,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.search.bases</name>
                <values>
                  <value>cn=groups,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>username.attr</name>
                <values>
                  <value>cn</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>groupname.attr</name>
                <values>
                  <value>cn</value>
                </values>
            </extendedProperty>
             </serviceInstance>
 
         <!-- IDStore service "idservice.virtualize" to connect to multiple ldaps ( 'oid' and 'ad') using libOVD-->
        <serviceInstance name="idservice.virtualize"          provider="idstore.ldap.provider">
 
             <!--following property enables virtualization i.e., support for multiple stores -->
               <property name="virtualize" value="true"/>
               <!-- backend ldap instance "idstore.oid"-->     
                               <serviceInstanceRef ref="idstore.oid"/>
               <!-- backend ldap instance "idstore.ad"-->
                            <serviceInstanceRef ref="idstore.ad"/>    
            <!-- Front end ldap properties (if not supplied, will use default values) --> 
            <extendedProperty>
                <name>user.create.bases</name>
                <values>
                   <value>cn=users_front,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.create.bases</name>
                <values>
                  <value>cn=groups_front,dc=us,dc=oracle,dc=com</value>
                </values>
            </extendedProperty>
        </serviceInstance>
 </serviceInstances>
 
  <jpsContexts default="default">
 
        <!-- IdStore service connect to  multiple ldaps ('oid'+'ad') through libOVD-->
        <jpsContext name="default">
                <!-- use multiple ldaps ('oid'+'ad') through libOVD-->
            <serviceInstanceRef ref="idservice.virtualize"/>  
            <!-- .....other services -->
        </jpsContext>
 
  </jpsContexts>
 
</jpsConfig>

Note that:

the first service instance defines the provider for Oracle Internet Directory
the second service instance defines the provider for Microsoft Active Directory
the virtualize property of the service instance is set to true, enabling multi-LDAP queries
the extendedProperty elements enable you to set front-end parameters if desired to override default values

For more information, see "Front-End Parameters" in Section 7.3.1, "What is Configured?".

7.3.5 Java SE Environments

In the Java SE environment, you directly modify the jps-config.xml file as follows:

define a new identity store service instance
add the new service instance to the JPS context, replacing any previously defined IdentityStore instance
to enable the 'virtualize' flag in the identity store service, refer to Example 7-3.

See Section 22.2.2, "Configuring an LDAP Identity Store in Java SE Applications" for details.

7.4 Querying the Identity Store Programmatically

To programmatically query the LDAP identity store, you use OPSS to obtain the JPS context; this acts like a bridge to obtain the store instance, and subsequently you use the User and Role API to query the store.

Example 7-4 Querying the LDAP Identity Store Programmatically

 try {
         //find the JPS context
         JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
         JpsContext ctx = ctxFactory.getContext();
        
         //find the JPS IdentityStore service instance (assuming the backend is            ldap type)
         LdapIdentityStore idstoreService = (LdapIdentityStore)ctx.getServiceInstance(IdentityStoreService.class)

         //get the User/Role API's Idmstore instance
          oracle.security.idm.IdentityStore idmIdentityStore = idstoreService.getIdmStore();
 
        //use the User/Role API to query id store
        //
 } catch (Exception e) {
  e.printStackTrace()
}

To see how to enable the 'virtualize' property in the identity store service, refer to Example 7-3.

For additional information about using MBeans, see Section E.2, "Configuring OPSS Services with MBeans".