7 Configuring the Identity Store Service

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

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

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 either an XML file or one or more LDAP servers 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 depends on the application server; you must 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.6, "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 supports both file-based (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. Topics include:

What is Configured?
Configuration in WebLogic Server
Configuring Split Profiles
Configuring Custom Authenticators
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. It includes:

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 queries:

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 The global value is used if explicitly provided.
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 it as the 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 The global value is used if explicitly provided.

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 you to configure multiple authenticators in a given context, and selects the first authenticator to initialize the identity store service by default. This process is explained in Section 3.2.2.1, "Multiple Authenticators".

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 to set up these options.

7.3.2.1 Configuring the Service for Single LDAP

You can configure the identity store service to query only one LDAP store. See Example 7-2 which displays a fragment of the jps-config.xml file with a single LDAP service instance.

7.3.2.2 Configuring the Service for Multiple LDAP Without virtualize Property

In cases when the virtualize property cannot be set, you can configure the identity store service to query more than one LDAP store and override the configuration in WebLogic Server. See Example 7-1 which displays a fragment of the jps-config.xml file where a multiple LDAP service instance is defined using a comma separated list of LDAP urls.

Example 7-1 Multiple-LDAP Configuration Without Setting virtualize Property

<property name="ldap.url", value="ldap://host1:port1,ldap://host2:port2" />

7.3.2.3 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, perform 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.4 Configuring the Service for Multiple LDAP using WLST

To configure the virtualize property using WLST, perform 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 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.5 Configuring the Timeout Setting Using WLST

To configure the timeout setting using WLST, perform these steps:

Run the following WLST command to list all adapters: listAdapters().
Run the following WLST command to set the timeout for each adapter. 120 second timeout is an example, set to zero for no timeout.

modifyLDAPAdapter('<ADAPTER NAME>', 'OperationTimeout', 120000)
Restart WebLogic Server.

7.3.2.6 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.7 Restarting Servers

After configuring for multi-LDAP query, restart the WebLogic administration and managed servers.

7.3.2.8 Examples of the Configuration File

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

Example 7-2 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-3 shows a sample jps-config.xml file configured for multi-LDAP queries in the Oracle WebLogic Server environment:

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

<jpsConfig xmlns="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.example.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=example,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.create.bases</name>
                <values>
                  <value>cn=groups_front,dc=us,dc=example,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 Configuring Custom Authenticators

OPSS supports the set of LDAP-based Oracle WebLogic Server authentication providers (WebLogic authenticators) for access to identity stores. If the out-of-the-box WebLogic authenticators are not applicable to your LDAP server type, you can customize a generic authenticator for this task.

This section explains how you can configure such an authenticator when the 'virtualize' flag is enabled for the identity store service.

Note the following points in this context:

When using a generic LDAP authenticator, you need to tell the Identity Store Service of the exact LDAP type so that it can find the proper LDAP plug-in. You do this by overriding the 'idstore.type' property in jps-config.xml.
As the 'virtualize' flag is enabled, and the Oracle WebLogic Server domain has two or more authenticators (for example, the defaultAuthenticator and generic LDAP), you need to tell the Identity Store Service which LDAP server's 'idstore.type' is to be overridden.

You provide this information as follows in jps-config.xml:

<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" />
 
    <property value="true" name="virtualize" />
 
    <!-- the following refer to the Generic ldap name configured on the WLS
authenticator provider, you get this name from WebLogic config.xml file or admin
console  -->
    <serviceInstanceRef ref="myGenericLDAPName"/>
 
  </serviceInstance>
 
 
  <!-- the following provide the overriding to the Generic ldap (e.g. AD)
-->
  <!-- "myGenericLDAPName" is the name used on WLS for the generic LDAP
authenticator provider  -->
  <serviceInstance name="myGenericLDAPName" provider="idstore.ldap.provider">
 
    <!-- the following overrides the 'idstore.type' property to
"ACTIVE_DIRECTORY" -->
    <property name="idstore.type" value="ACTIVE_DIRECTORY" />
  </serviceInstance>

If you need to override an additional LDAP provider instance, simply add another similar entry to the file.

7.3.5 Configuration in Other Application Servers

Topics in this section include:

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

7.3.5.1 Configuring the Service for Single LDAP

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

7.3.5.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-4 shows a sample jps-config.xml file configured to run multi-LDAP queries for third-party application servers:

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

<jpsConfig xmlns="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.example.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=example,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://hostname.example.com:389,ldap://hostname.example.com:389"/>
            <extendedProperty>
                <name>user.search.bases</name>
                <values>
                   <value>cn=users,dc=us,dc=example,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.search.bases</name>
                <values>
                  <value>cn=groups,dc=us,dc=example,dc=com</value>
                </values>
            </extendedProperty>
            <property name="username.attr" value="uid" />
            <property name="groupname.attr" value="cn" />
            </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=example,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://hostname.example.com:389,ldap://hostname.example.com:389"/>
            <extendedProperty>
                <name>user.search.bases</name>
                <values>
                   <value>cn=users,dc=us,dc=example,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.search.bases</name>
                <values>
                  <value>cn=groups,dc=us,dc=example,dc=com</value>
                </values>
            </extendedProperty>
            <property name="username.attr" value="uid" />
            <property name="groupname.attr" value="cn" />
             </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=example,dc=com</value>
                </values>
            </extendedProperty>
            <extendedProperty>
                <name>group.create.bases</name>
                <values>
                  <value>cn=groups_front,dc=us,dc=example,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.6 Java SE Environments

In a Java SE environment, all configurations are set in the jps-config-jse.xml file. According to your needs, you can:

Define a new identity store service instance.
Add the new service instance to the JPS context, replacing any previously defined IdentityStore instance.
Enable the virtualize flag in the identity store service; see Example 7-4.

For further information, see Section 22.3.2, "Configuring an LDAP Identity Store in Java SE Applications".

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. Subsequently you use the User and Role API to query the store.

Example 7-5 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
        //

//alternatively, instead of using IdentityStore, use the 
//IdentityDirectory to access LDAP
oracle.igf.ids.IdentityDirectory ids = idstoreService.getIdentityStore();
// ref. chapter "Developing with the Identity Directory API"
// on how to use IdentityDirectory

 } catch (Exception e) {
  e.printStackTrace()
}

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

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

7.5 SSL for the Identity Store Service

Connections between the identity store and an LDAP server can be SSL-enabled. This section explains how the connections are configured in the various scenarios. Use the following table to determine the correct procedure to use:

If virtualize flag is set to	And the User and Role API is in use	And the Identity Directory Service is in use
virtualize=false (that is, virtualize flag is not set)	Specify truststore using JSSE parameters, as explained in Section 8.2.3. For example: -Djavax.net.ssl.trustStore=trust_store_path_name	Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3.
virtualize=true (that is, virtualize flag is set)	Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3.	Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3.

If virtualize flag is set to

And the User and Role API is in use

And the Identity Directory Service is in use

virtualize=false (that is, virtualize flag is not set)

Specify truststore using JSSE parameters, as explained in Section 8.2.3.

For example:

-Djavax.net.ssl.trustStore=trust_store_path_name

Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3.

virtualize=true (that is, virtualize flag is set)

Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3.

Connections from Oracle WebLogic Server to Identity Store
One-way SSL in a Multi-LDAP Scenario
Two-way SSL in a Multi-LDAP Scenario

7.5.1 Connections from Oracle WebLogic Server to Identity Store

When the connection to the identity store originates at a client residing in Oracle WebLogic Server, SSL configuration is handled by Oracle WebLogic Server. For details, see Section 8.2.3.

7.5.2 One-way SSL in a Multi-LDAP Scenario

Both the Identity Directory API and the User and Role API can operate in a multi-LDAP identity store configuration (virtualize = true).

In this scenario, you can SSL-enable the connection from the identity store to the LDAP servers.

The procedure is as follows:

Create a keystore to contain the LDAP server certificate(s) for use by the service. You will need to provide passwords for the WebLogic Admin Server and the keystore, respectively.

Create the keystore using the script $MW_HOME/oracle_common/bin/libovdconfig.sh with the "-createKeystore" option:
```
libovdconfig.sh -host wls_host -port wls_adminserver_port -userName
wls_user_name -domainPath full_path_domain_home -createKeystore
```
where:
- host is the Oracle WebLogic Server host
- port is the Oracle WebLogic Server Admin Server port
- username is the Oracle WebLogic Server admin user name
- domainPath is the complete path to the domain home
Export the certificate from the LDAP directory using the appropriate export command.

Import this certificate into the keystore you created in Step 1.

Import the certificate to the keystore using the keytool command. The syntax is as follows, for a keystore named adapters.jks:

$JAVA_HOME/bin/keytool -importcert 
-keystore $DOMAIN_HOME/config/fmwconfig/ovd/default/keystores/adapters.jks 
-storepass keystore_password_used_in_libovdconfig.sh 
-alias alias_name 
-file full_path_to_LDAPCert_file 
-noprompt

Restart Oracle WebLogic Server.

7.5.3 Two-way SSL in a Multi-LDAP Scenario

To implement two-way SSL in a multi-LDAP identity store configuration, perform these steps:

Perform the procedure described in Section 7.5.2.
In the keystore that was created by Step 1 of Section 7.5.2, generate a new key pair, signed by a CA.
Export this certificate to a file.
Import the certificate into the server's keystore.