9 Configuring External LDAP Providers

This chapter discusses how to configure OC4J to use non-Oracle LDAP servers. It is divided into the following sections:

Prerequisites
Creating a <login-module> Element in jazn-data.xml
Sample LDIF Description
Configuring Sun Java System Application Server as LDAP Provider
Configuring Microsoft Active Directory as LDAP Provider

Notes:

You must use JDK1.4 or later to take advantage of non-Oracle LDAP servers.
OC4J provides a JAAS login module to authenticate and authorize against non-Oracle LDAP servers. Do not configure the non-Oracle LDAP server JAAS login module to authenticate and authorize against the Oracle Internet Directory (OID). If you did that, you would lose optimizations and integrations that are available when you use the native LDAP provider. See Chapter 7, "Configuring the LDAP-Based Provider" for how to configure Oracle Internet Directory using the native LDAP provider.

Prerequisites

Before you configure OC4J, you must complete the following prerequisites:

Install and configure Sun Java System Application Server (formerly iPlanet) or Active Directory.
Install and configure OC4J.
Locate the jazn-data.xml file associated with your OC4J instance. This is normally in the ORACLE_HOME/j2ee/instance_name/config directory. You will be editing this file using a text editor.

Note:
The jazn-data.xml file for the OC4J home instance, in ORACLE_HOME/j2ee/home/config, serves as the default repository for JAAS login modules.
Locate the orion-application.xml file that controls your application. This file will normally be located in the following directory:
```
ORACLE_HOME/j2ee/instance_name/application-deployments/application_name
```
You will be editing this file using a text editor.

Notes:

Sample login module entries for Sun Java System Application Provider and Microsoft Active Directory are in the ORACLE_HOME/j2ee/home/jazn/config directory. A non-provider-specific login module entry is provided in the file ldap_login_module.template in the same directory.
Be aware of the following when you make grants to principals, in jazn-data.xml, when using non-Oracle LDAP servers: If you specify the name of a principal using a full Distinguished Name (DN), you must specify the DN exactly as it appears in the LDAP server, and with no white space. For example:
```
cn=jdoe,dc=us,dc=example,dc=com
```

Creating a <login-module> Element in jazn-data.xml

Each option within a <login-module> element corresponds to a configuration setting in the LDAP provider. The supported options are listed in Table 9-1, Table 9-2 , and Table 9-3. Unless marked (optional), all options must be explicitly specified.

Table 9-1 Login Module Provider Options

Option name	Meaning
`oracle.security.jaas.ldap.provider.url`	The URL of the LDAP provider in the format `hostname:portname`.
`oracle.security.jaas.ldap.provider.principal`	The Distinguished Name (DN) of the LDAP user that is used to connect to the LDAP server. This user must be an administrator with privileges to search users and groups, and to invoke `ldapcompare` on a user password if the target directory supports this.
`oracle.security.jaas.ldap.provider.credential`	The credential (generally a password) used to authenticate the LDAP user defined in `principal`.
`oracle.security.jaas.ldap.provider.type`	(Optional) The product name of the LDAP provider. Supported values are `iplanet`, `active directory`, and `other`. If you supply `iplanet` or `active directory`, the login module is able to infer some LDAP properties (for example, the group object class for active directory is "group") and do some optimizations.
`oracle.security.jaas.ldap.provider.connect.pool`	(Optional) A boolean to determine whether connection pooling is enabled. A `true` setting enables connection pooling; `false` disables it.
`oracle.security.jaas.ldap.lm.cache_enabled`	(Optional) A boolean to determine whether login module caching is enabled. A `true` setting (default) enables caching; `false` disables it.

Table 9-2 Login Module User Options

Option name	Meaning
`oracle.security.jaas.ldap.user.name.attribute`	The name of the LDAP attribute that uniquely identifies the name of the user. In Sun Java System Application Server, `uid`; on Active Directory, `sAMAccountName`.
`oracle.security.jaas.ldap.user.objectclass`	A list of space-separated LDAP schema object classes to represent a use. On Sun Java System Application Server, `inetOrgPerson`.
`oracle.security.jaas.ldap.user.searchbase`	A list of space-separated base distinguished names (DN) in the LDAP directory that contains users. For example: cn=users,dc=us,dc=abc,dc=com
`oracle.security.jaas.ldap.user.searchscope`	Specifies how deeply into the LDAP directory tree to search for users. Supported values: `subtree`, `onelevel`.

Table 9-3 Login Module Role Options

Option name	Meaning
`oracle.security.jaas.ldap.role.name.attribute`	The name of the LDAP attribute that uniquely identifies the name of the role. In iPlanet, this would be `uniqueMember`; in Active Directory, it would be `member`.
`oracle.security.jaas.ldap.role.object.class`	A list of space-separated LDAP schema object classes that is used to represent a group. On Sun Java System Application Server, `groupOfUniqueNames`. On Active Directory, `group`.
`oracle.security.jaas.ldap.role.searchbase`	A list of space-separated distinguished names (DN) in the LDAP directory that contains group. For example: cn=groups,dc=us,dc=abc,dc=com
`oracle.security.jaas.ldap.role.searchscope`	Specifies how deeply into the LDAP directory tree to search for roles. Supported values: `subtree`, `onelevel`.
`oracle.security.jaas.ldap.role.membership.searchscope`	Specifies how deeply into the LDAP directory tree to search for role membership. Supported values: `direct`, `nested`.
`oracle.security.jaas.ldap.role.member.attribute`	The attribute of a static LDAP group object specifying the distinguished names (DN) of the members of the group. On Sun Java System Application Server, `uniqueMember`; on Active Directory, `member`.

Sample LDIF Description

Example 9-1 contains sample declarations for a user object and role object; each of the next two sections discusses how to map those objects to an LDAP provider.

Example 9-1 Sample LDIF Defining a User and Role

# An example user object entry
uid= jdoe,dc=us,dc=example,dc=com
uid= jdoe
givenName=John
sn=Doe
cn=John Doe
userPassword={SSHA}zD/44JbZY33osry4mzfLn0du7nBhIIAHKDG5Fg==
uidNumber=1
gidNumber=1
homeDirectory=c:\
objectClass=top
objectClass=person
objectClass=organizationalPerson
objectClass= inetOrgPerson
objectClass=posixAccount
 
# An example role object entry
cn=managers,ou=groups,dc=us,dc=example,dc=com
objectClass=top
objectClass= groupOfUniqueNames
cn=managers
uniqueMember=uid=jdoe,dc=us,dc=example,dc=com

Configuring Sun Java System Application Server as LDAP Provider

At this release, you must configure Sun Java System Application Server as your LDAP provider by editing the jazn-data.xml file to add a <login-module> element corresponding to the Sun product. This section discusses the necessary changes.

Note:

A template file containing a sample login module entry for Sun Java System Application Server is provided in the file sample_login_module.sun in the ORACLE_HOME/j2ee/home/jazn/config directory.

Open your jazn-data.xml file (see "Prerequisites") using a text editor.
Locate the <application> element representing your application. If there is no <application> element, create one.
Locate the <login-modules> section within the <application> element. If there is no <login-modules> element, create one.
Open your orion-application.xml file (see "Prerequisites") using a text editor.
Locate the <jazn> element within orion-application.xml. Set the provider property to "XML" and add a <property> element setting custom.ldap.provider to true. The edited <jazn> element should look like this:
```
 <jazn provider="XML">
     <property name="custom.ldap.provider" value="true"/>
 </jazn>
```
Restart the OC4J instance using Enterprise Manager.

SunOne Example

Suppose that your Sun Java System Application Server installation is described by the set of LDIF entries shown in Example 9-1.

The corresponding <jazn-loginconfig> entity is shown in Example 9-2.

Example 9-2 JAAS Login Module Configuration Corresponding to Example 9-1

<jazn-loginconfig>
   <application>
      <name>callerInfo</name>
      <login-modules>
         <login-module>
            <class>oracle.security.jazn.login.module.LDAPLoginModule</class>
            <control-flag>required</control-flag>
            <options>
               ... irrelevant options omitted ...
               <option>
                  <name>oracle.security.jaas.ldap.user.name.attribute</name>
                  <value>uid</value>
               </option>
               <option>
                  <name>oracle.security.jaas.ldap.user.object.class</name>
                  <value>inetOrgPerson</value>
               </option>
               <option>
                  <name>oracle.security.jaas.ldap.user.searchbase</name>
                  <value>dc=us,dc=example,dc=com</value>
               </option>
               <option>
                  <name>oracle.security.jaas.ldap.role.name.attribute</name>
                  <value>cn</value>
               </option>
               <option>
                  <name>oracle.security.jaas.ldap.role.object.class</name>
                  <value>groupOfUniqueNames</value>
               </option>
               <option>
                  <name>oracle.security.jaas.ldap.role.searchbase</name>
                  <value>ou=groups,dc=us,dc=example,dc=com</value>
               </option>
               <option>
                  <name>oracle.security.jaas.ldap.member.attribute</name>
                  <value> uniqueMember </value>
               </option>
            </options>
         </login-module>
      </login-modules>
   </application>
</jazn-loginconfig>

Configuring Microsoft Active Directory as LDAP Provider

At this release, you must configure Microsoft Active Directory as your LDAP provider by editing the jazn-data.xml file to add a <login-module> element corresponding to the Microsoft product. This section discusses the necessary changes.

Note:

A template file containing a sample login module entry for Active Directory is provided in the file sample_login_module.ad in the ORACLE_HOME/j2ee/home/jazn/config directory.

Locate the <application> element representing your application. If there is no <application> element, create one.
Locate the <login-modules> section within the <application> element. If there is no <login-modules> element, create one.
Edit the <option> elements to specify appropriate values for Microsoft Active Directory. Save the edited file.
Open your orion-application.xml file (see "Prerequisites") using a text editor.
Locate the <jazn> element within orion-application.xml. Set the provider property to "XML" and add a <property> element that sets custom.ldap.provider to true. The edited <jazn> element should look like this:
```
 <jazn provider="XML">
     <property name="custom.ldap.provider" value="true"/>
 </jazn>
```
Restart the OC4J instance using Enterprise Manager.