9 External LDAP Security Providers

This chapter discusses how to configure OC4J to use a non-Oracle ("third-party" or "external") LDAP server as the user repository. It is divided into the following sections:

• Overview of External LDAP Provider Configuration and Administration

• Configuring External LDAP Providers in Application Server Control

• External LDAP Provider Settings in system-jazn-data.xml

• Granting RMI Permission to an LDAP Principal

• Sample Configuration for Sun Java System Directory Server

The OC4J 10.1.3 implementation supports the following external LDAP providers:

• Active Directory (for Windows Server 2003)

• Sun Java System Directory Server (version 5.2)

Notes: Support for external LDAP providers requires JDK 1.4 or later. The concept of security realms is not supported when using external LDAP providers.

See Also: Chapter 8, "Login Modules"

Overview of External LDAP Provider Configuration and Administration

When you deploy an application using Application Server Control Console, you have the opportunity to specify an external (third-party) LDAP provider, as noted in "Specifying the Security Provider through Application Server Control".

(This assumes that you have already completed the prerequisite of installing and configuring Sun Java System Directory Server, formerly iPlanet, or Active Directory.)

Specifying an external LDAP provider automatically results in the following setting in orion-application.xml:

<jazn provider="XML">
   <property name="custom.ldap.provider" value="true" />
</jazn>

Notes: Note the setting provider="XML" is used for external LDAP providers as well as for the file-based provider. Be aware that when you use an external LDAP provider, role comparisons for authorization are not case-sensitive unless you add the following property setting to the <jazn> element in orion-application.xml: <property name="role.compare.ignorecase" value="false" />

Troubleshooting Tips: Note the following potential issues if you have trouble using an external LDAP provider: Be sure you are using the Distinguished Name (DN) of the LDAP user to connect to the LDAP server. This user must be an administrator with privileges to search users and groups. If you provide the correct user name and password for login, but still get an authentication failure for invalid credentials, ensure that the LDAP host and port are configured correctly. Using the ldapbind command to bind against the configured LDAP host and port will be a good way to check.

OC4J provides a login module, LDAPLoginModule, to use for authentication and authorization with an external LDAP provider. (Alternatively, you can provide a custom login module to use with any custom repository.) Configurable options for an external LDAP provider include the following:

• URL of the external LDAP provider

• LDAP principal DN to connect (user must have privileges to query role information for any user in the LDAP directory)

• Credential of the LDAP principal DN

• LDAP attribute that uniquely identifies a user

• User object classes, search bases, search scope

• Role object classes, search bases, search scope

• Enabling or disabling of connection pooling

• Enabling or disabling of login module caching

Option settings are reflected within a <login-module> element in system-jazn-data.xml, which configures LDAPLoginModule.

Note: Sample login module entries for Sun Java System Directory Server and Microsoft Active Directory are provided in the directory ORACLE_HOME/j2ee/home/jazn/config. A non-provider-specific login module entry is provided in the file ldap_login_module.template in the ORACLE_HOME/j2ee/home/jazn/config directory.

Configuring External LDAP Providers in Application Server Control

This section discusses the following topics for administering external LDAP providers using the Application Server Control Console:

• Specifying and Configuring an External LDAP Provider during Deployment

• Changing to an External LDAP Provider after Deployment

Note: Procedures discussed throughout this section assume you are logged in to Application Server Control as a user with required administrative permissions (as oc4jadmin, for example).

Specifying and Configuring an External LDAP Provider during Deployment

When you plan to use an external LDAP provider and deploy an application through Application Server Control, you have the opportunity to configure the external LDAP provider when you specify it as the security provider.

From the Deploy: Deployment Settings page (see "Deploying an Application through Application Server Control" for how to get to this page):

1. Go to the Select Security Provider task.

2. In the resulting Deployment Settings: Select Security Provider page, choose Third Party LDAP Server from the Security Provider dropdown list.

3. Under "Configuration of Oracle Security Provider for 3rd Party LDAP Server" (which appears after you choose Third Party LDAP Server), specify settings for the options documented in:

   • Table 9-1, "Application Server Control External LDAP Provider Options"

   • Table 9-2, "Application Server Control External LDAP Connection Pool Options" (if you enable connection pooling)

   • Table 9-3, "Application Server Control External LDAP User Options"

   • Table 9-4, "Application Server Control External LDAP Role and Member Options"

   Or, alternatively, choose Set Values to Vendor Defaults.

4. Choose OK to finish the security provider selection.

5. Back in the Deploy: Deployment Settings page, choose Deploy to complete the deployment, or choose another task, as desired. The list of tasks is noted in "Deploying an Application through Application Server Control".

Table 9-1 Application Server Control External LDAP Provider Options

Option	Required? Or Settings / Default	Equivalent Option in Table 9-5 (see for description)
LDAP Location	Required	oracle.security.jaas.ldap.provider.url
LDAP Directory Vendor	Active Directory, Sun Directory Server, or Other (from dropdown menu)	oracle.security.jaas.ldap.provider.type
User DN	Required	oracle.security.jaas.ldap.provider.principal
User Password	Required	oracle.security.jaas.ldap.provider.credential
Enable Caching (checkbox)	Default: true	oracle.security.jaas.ldap.lm.cache_enabled
Enable Connection Pooling (checkbox)	Default: true	oracle.security.jaas.ldap.provider.connect.pool

Table 9-2 Application Server Control External LDAP Connection Pool Options

Option	Default	Description
Initial Size of Connection Pool	2	Number of connections initially created in the pool for each connection identity
Maximum Size of Connection Pool	25	Maximum number of connections that can be concurrently maintained in the pool for each connection identity
Preferred Size of Connection Pool	10	Preferred number of connections in the pool for each connection identity
Idle Connection Timeout (milliseconds)	300000 (5 minutes)	The amount of time that an idle connection can remain in the pool before being removed

Note: The above connection pooling properties correspond to the following: com.sun.jndi.ldap.connect.pool.initsize com.sun.jndi.ldap.connect.pool.maxsize com.sun.jndi.ldap.connect.pool.prefsize com.sun.jndi.ldap.connect.pool.timeout As described at: http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html

Table 9-3 Application Server Control External LDAP User Options

Option	Required? Or Settings / Default	Equivalent Option in Table 9-6 (see for description)
User Search Base	Required	oracle.security.jaas.ldap.user.searchbase
User Search Scope	Subtree (default) or One Level (from dropdown menu) Note: Although the default in the dropdown menu is Subtree, the vendor default is One Level.	oracle.security.jaas.ldap.user.searchscope
LDAP User Name Attribute	Required	oracle.security.jaas.ldap.user.name.attribute
LDAP User Object Class	Required	oracle.security.jaas.ldap.user.object.class

Table 9-4 Application Server Control External LDAP Role and Member Options

Option	Required? Or Settings / Default	Equivalent Option in Table 9-7 (see for description)
Group Search Base	Required	oracle.security.jaas.ldap.role.searchbase
Group Search Scope	Subtree (default) or One Level (from dropdown menu) Note: Although the default in the dropdown menu is Subtree, the vendor default is One Level.	oracle.security.jaas.ldap.role.searchscope
LDAP Group Name Attribute	Required	oracle.security.jaas.ldap.role.name.attribute
LDAP Group Object Class	Required	oracle.security.jaas.ldap.role.object.class
LDAP Group Member Attribute	Required	oracle.security.jaas.ldap.member.attribute
Group Membership Scope Search	Direct (default) or Nested (from dropdown menu)	oracle.security.jaas.ldap.membership.searchscope

Changing to an External LDAP Provider after Deployment

You can select a security provider for your application at deployment time, as described above. You can also change to a different security provider after deployment. In particular, to change to an external LDAP provider:

1. Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

2. In the Security Provider page, choose "Change Security Provider".

3. In the Change Security Provider page, select Oracle Security Provider for 3rd Party LDAP Server from the Security Provider Type dropdown.

4. Under "Security Provider Attributes: Oracle Security Provider for 3rd Party LDAP Server" (which appears after you select 3rd Party LDAP Server in the dropdown), specify settings for the options documented in:

   • Table 9-1, "Application Server Control External LDAP Provider Options"

   • Table 9-2, "Application Server Control External LDAP Connection Pool Options" (if you enable connection pooling)

   • Table 9-3, "Application Server Control External LDAP User Options"

   • Table 9-4, "Application Server Control External LDAP Role and Member Options"

   Or, alternatively, choose Set Values to Vendor Defaults.

5. Choose OK to finish the change.

This takes you back to the Security Provider page, where you can examine the settings.

External LDAP Provider Settings in system-jazn-data.xml

Configuration of an external LDAP provider is reflected in a <login-module> element in system-jazn-data.xml that configures the LDAPLoginModule, the login module used for external LDAP providers in OracleAS JAAS Provider. Any <login-module> elements are subelements of the <login-modules> element under <jazn-loginconfig>.

Each option in a <login-module> element is represented by the <name> subelement of an <option> element and corresponds to a configuration setting in the external LDAP provider.

You can specify settings of these options through Application Server Control, as documented in "Specifying and Configuring an External LDAP Provider during Deployment", which also documents the correspondence between options listed in this section and what you see in the Application Server Control Console.

Supported options are listed in Table 9-5, Table 9-6 , and Table 9-7. Where applicable, the tables indicate default values that are used when you configure an external LDAP provider through Application Server Control and choose Set Values to Vendor Defaults. Except where noted otherwise, these options are required, either by specifying them directly or using vendor defaults.

Note: The <jazn-loginconfig> element can also appear in the orion-application.xml file, in which case it is copied from there into the system-jazn-data.xml file.

See Also: "Settings in system-jazn-data.xml for Sun Java System Directory Server" for examples of some option settings

Table 9-5 External LDAP Provider Options

Option Name	Meaning
oracle.security.jaas.ldap.provider.url	The URL of the LDAP provider, in the format ldap://host:port, such as: ldap://myhost.example.com:389
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 roles, and to invoke ldapcompare on a user password if the target directory supports that functionality.
oracle.security.jaas.ldap.provider.credential	The credential (generally a password) used to authenticate the LDAP user defined in: oracle.security.jaas.ldap.provider.principal
oracle.security.jaas.ldap.provider.type	(Optional) The product name of the LDAP provider. Supported values are sun directory server, active directory, and other. If you supply sun directory server or active directory, the login module is able to infer some LDAP properties and do some optimizations.
oracle.security.jaas.ldap.provider.connect.pool	(Optional) Boolean indicating whether connection pooling is enabled. A true setting (default) enables connection pooling; false disables it.
oracle.security.jaas.ldap.lm.cache_enabled	(Optional) Boolean indicating whether login module caching is enabled. A true setting (default) enables caching, false disables it.

Table 9-6 External LDAP 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. The default for Sun Java System Directory Server is uid; for Active Directory, it is sAMAccountName.
oracle.security.jaas.ldap.user.object.class	A list of one or more space-delimited LDAP schema object classes to represent a user. The default for either Sun Java System Directory Server or Active Directory is inetOrgPerson.
oracle.security.jaas.ldap.user.searchbase	A list of space-delimited distinguished names (DNs) in the LDAP directory that contains users. Here is a sample DN: cn=users,dc=us,dc=abc,dc=com
oracle.security.jaas.ldap.user.searchscope	Specifies how deep in the LDAP directory tree to search for users. Supported values are subtree or onelevel (default).

Table 9-7 External LDAP Role and Member 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. For either Sun Java System Directory Server or Active Directory, the default is "cn".
oracle.security.jaas.ldap.role.object.class	A list of one or more space-delimited LDAP schema object classes that is used to represent a role. The default for Sun Java System Directory Server is groupOfUniqueNames; for Active Directory, it is group.
oracle.security.jaas.ldap.role.searchbase	A list of space-delimited distinguished names (DN) in the LDAP directory that contains a role. For example: cn=groups,dc=us,dc=abc,dc=com
oracle.security.jaas.ldap.role.searchscope	Specifies how deep in the LDAP directory tree to search for roles. Supported values are subtree or onelevel (default).
oracle.security.jaas.ldap.membership.searchscope	Specifies how deep in the LDAP directory tree to search for role membership. Supported values are direct (default) or nested. A direct setting means the runtime will only get the roles directly assigned to the role or user in question, as opposed to nested roles within roles.
oracle.security.jaas.ldap.member.attribute	The attribute of a static LDAP role object specifying the distinguished names (DNs) of the members of the role. The default for Sun Java System Directory Server is uniqueMember; for Active Directory, it is member.

Granting RMI Permission to an LDAP Principal

When using an external LDAP provider, it may be necessary to grant RMI "login" permission for an LDAP principal.

The following example uses the OracleAS JAAS Provider Admintool to accomplish this:

% java -jar jazn.jar -grantperm oracle.security.jazn.realm.LDAPPrincipal hobbes \
       com.evermind.server.rmi.RMIPermission login 

This example would result in the following configuration in the system-jazn-data.xml file:

<jazn-policy>
   <grant>
      <grantee>
         <principals>
            <principal>
               <class>oracle.security.jazn.realm.LDAPPrincipal</class>
               <name>hobbes</name>
            </principal>
         </principals>
      </grantee>
      ...
      <permissions>
         <permission>
            <class>com.evermind.server.rmi.RMIPermission</class>
            <name>login</name>
         </permission>
         ...
      </permissions>
      ...
   </grant>
   ...
</jazn-policy>

Sample Configuration for Sun Java System Directory Server

This section provides the following sample configuration to use the Sun Java System Directory Server as an external LDAP provider:

• Sample LDIF Description

• Sample Entries in OC4J Configuration Files

The orion-application.xml and system-jazn-data.xml settings would be made automatically if you use Application Server Control Console as described earlier in this chapter.

Note: A template file containing a sample login module entry for Sun Java System Directory Server is provided in the file sample_login_module.sun in the ORACLE_HOME/j2ee/home/jazn/config directory. (Similarly, 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.)

Sample LDIF Description

Assume the following LDIF description is used for the Sun Java System Directory Server example:

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

Sample Entries in OC4J Configuration Files

This section shows OC4J configuration in the following files for an external LDAP provider:

• Settings in system-jazn-data.xml for Sun Java System Directory Server

• Settings in orion-application.xml for External LDAP Server

Settings in system-jazn-data.xml for Sun Java System Directory Server

Assume your Sun Java System Directory Server installation is described by the set of LDIF entries shown in Example 9-1. The corresponding <jazn-loginconfig> entries in the system-jazn-data.xml file are shown in the following example:

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

<jazn-data ... >
   ...
   <jazn-loginconfig>
      <application>
         <name>callerInfo</name>
         <login-modules>
            <login-module>
               <class>oracle.security.jazn.login.module.LDAPLoginModule</class>
               <control-flag>required</control-flag>
               <options>
                  <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>
   ...
</jazn-data>

Note: An option setting for an external LDAP location would look like the following: ... <options> ... <option> <name>oracle.security.jaas.ldap.provider.url</name> <value>ldap://myhost.example.com:389</value> </option> ... </options> ...

Settings in orion-application.xml for External LDAP Server

The following settings in orion-application.xml are used for any external LDAP provider:

<jazn provider="XML">
   <property name="custom.ldap.provider" value="true" />
</jazn>

You must restart OC4J to synchronize the login module information from system-jazn.data.xml.