Skip Headers
Oracle® Containers for J2EE Security Guide
10g (10.1.3.5.0)

Part Number E13977-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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

OC4J 10.1.3.x implementations support the following external LDAP providers:

Notes:

See Also:

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".

Note:

This is assuming 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 that by convention, the <jazn> setting provider="XML" is used for external LDAP providers.

  • 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 would 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:

Option settings to configure LDAPLoginModule are reflected within a <login-module> element under <jazn-loginconfig> in system-jazn-data.xml.

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:

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:

    Or, alternatively, choose Set Values to Vendor Defaults for the vendor specified through the LDAP Directory Vendor setting. Apart from this, you must still specify LDAP Location, User DN, User Search Base, and Group Search Base.

  4. You can optionally choose Test LDAP Authorization prior to deployment. This tests whether the LDAP session can successfully be created, thereby confirming key settings such as the LDAP host, port, administrative user, and password.

  5. Choose OK to finish the security provider selection.

  6. 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 10-1 Application Server Control External LDAP Provider Options

Option Required? Or Settings / Default Equivalent Option in Table 10-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

No default

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 10-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

These are described at:

http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html

Table 10-3 Application Server Control External LDAP User Options

Option Required? Or Settings / Default Equivalent Option in Table 10-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 10-4 Application Server Control External LDAP Role and Member Options

Option Required? Or Settings / Default Equivalent Option in Table 10-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 in the preceding section. 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 the following tables in the preceding section:

    Or, alternatively, choose Set Values to Vendor Defaults for the vendor specified through the LDAP Directory Vendor setting. Apart from this, you must still specify LDAP Location, User DN, User Search Base, and Group Search Base.

  5. You can optionally choose Test LDAP Authorization prior to deployment. This tests whether the LDAP session can successfully be created, thereby confirming key settings such as the LDAP host, port, administrative user, and password.

  6. Choose OK to finish the change.

This takes you back to the Security Provider page, where you are prompted to restart your application for the changes to take effect.

Important:

Also confirm that role mapping is set up appropriately, to correctly map deployment roles (roles defined in the external LDAP provider) to J2EE logical roles. Refer to "Mapping Security Roles" for additional information.

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 setting in a <login-module> element is specified in an <option> element (subelement of <options>) and corresponds to a configuration setting in the external LDAP provider. The <name> subelement of an <option> element specifies the name of the option, and the <value> subelement specifies the corresponding value.

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 10-5, Table 10-6 , and Table 10-7 following. 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:

Table 10-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.

oracle.security.jaas.ldap.context.referral

(Optional) Can have one of the following values: follow, throw, or ignore. It indicates how referrals are handled by the login module. If not specified, the provider's default one will be used. By default, this property is not specified.

oracle.security.jaas.ldap.object.category

(Optional) This is to be used only with Active Directory and specifies the objectCategory used in the group search filter. If not specified, objectCategory will not be included in the filter. By default, this property is not specified.


Table 10-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 semicolon-delimited distinguished names (DNs) in the LDAP directory that contains users. Here is a sample DN:

ou=bpelgroup,dc=ad,dc=vm,dc=oracle,dc=com;ou=applgroup,dc=ad,dc=vm,dc=oracle,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 10-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 semicolon-delimited distinguished names (DN) in the LDAP directory that contains roles. For example:

ou=bpelgroup,dc=ad,dc=vm,dc=oracle,dc=com;ou=applgroup,dc=ad,dc=vm,dc=oracle,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.


Here is an example:

<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.provider.url</name>
                     <value>ldap://myhost.example.com:389</value>
                  </option>
                  ...more options...
               </options>
            </login-module>
            ...
         </login-modules>
      </application>
      ...
   </jazn-loginconfig>
   ...
</jazn-data>

See "Settings in system-jazn-data.xml for Sun Java System Directory Server" for the complete example.

Creating Necessary Accounts and Granting Necessary Permissions

This section discusses steps you must take when using an external LDAP provider to create necessary accounts and grant necessary permissions, covering the following topics:

Creating the Administrative User and Roles and Granting RMI Permission

When you use an external LDAP provider, you must define an administrative user account and administrator roles, grant the roles to the user, and grant necessary permissions to the roles. (These steps are handled automatically in the file-based security provider and Oracle Internet Directory.)

  1. Create an administrative user account in the external LDAP directory, using the appropriate tool for the security provider. (The name oc4jadmin is used for the administrator account by convention, but you can use any name.)

  2. Create the administrator roles oc4j-administrators and ascontrol_admin in the external LDAP directory, using the appropriate tool. These roles must be under the group search base configured for the LDAP provider. (See Table 10-4 and Table 10-7 for information about the group search base.)

  3. Grant these roles to the administrative user, using the appropriate tool.

  4. Create the additional administrator roles oc4j-app-administrators, ascontrol_appadmin, and ascontrol_monitor. (These do not have to be granted to the administrative user.)

  5. If the administrator must access EJBs, grant these roles RMI permission "login". You can use the OracleAS JAAS Provider Admintool for this, as in the following example:

    % java -jar jazn.jar -grantperm myrealm -role oc4j-administrators \
         com.evermind.server.rmi.RMIPermission login
    

    Be aware that although the roles are defined in the external LDAP provider, these permission grants are stored in the system-jazn-data.xml file.

Granting RMI Permission to an LDAP Principal

When using an external LDAP provider for an EJB application, it is necessary to grant RMI permission "login" for the appropriate LDAP principal for EJB access.

The following example uses the OracleAS JAAS Provider Admintool to accomplish this for an LDAP principal hobbes:

% 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, assuming that is your policy repository.

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

Granting Additional Permissions to External LDAP Principals

Any additional permission required by any external LDAP principal can be granted in the same way as RMI permission, shown in the preceding section.

Using JAAS Mode with External LDAP Providers

The use of OC4J JAAS mode is supported for an application that uses an external LDAP provider, in case that is required by your application in checking authorizations with respect to the permissions you have granted. It is configured as shown in the following example:

<orion-application ... >
   ...
   <jazn ... jaas-mode="doAsPrivileged" />
   ...
</orion-application>

Refer to "Introduction to JAAS Mode" and "Configuring and Using JAAS Mode" to gain an understanding of when and how to use this mode.

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:

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 10-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

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

Example 10-2 JAAS Login Module Configuration Corresponding to Example 10-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.provider.url</name>
                     <value>ldap://myhost.example.com:389</value>
                  </option>
                  <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>

Settings in orion-application.xml for an 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.

Using SSL with External LDAP Providers

This section discusses how to use Secure Sockets Layer communication when using an external LDAP provider with OC4J, covering the following topics:

See Also:

For information about OC4J server-side SSL support:

Initial SSL Considerations for External LDAP Providers

"SSL Authentication" discusses the various authentication modes for Secure Sockets Layer communication—no authentication, one-way authentication, and two-way authentication. Be aware that most LDAP providers do not support "no authentication" mode (although Oracle Internet Directory does).

Configuring OC4J to Use SSL with an External LDAP Provider

To enable SSL communication to an external LDAP provider, set the LDAP provider option oracle.security.jaas.ldap.provider.url to a URL value that specifies the LDAPS protocol, the host name, and an appropriate port for SSL communication. The syntax is similar to that for plain LDAP URLs discussed earlier, but the default port for LDAPS is 636 instead of 389.

When you use the Application Server Control Console for external LDAP provider configuration, this option corresponds to the setting for LDAP Location, as noted in "Specifying and Configuring an External LDAP Provider during Deployment". This option is also discussed in "External LDAP Provider Settings in system-jazn-data.xml".

For example, setting LDAP Location to ldaps://myhost.example.com:636 results in oracle.security.jaas.ldap.provider.url being set in system-jazn-data.xml as follows:

<login-module>
      <class>oracle.security.jazn.login.module.LDAPLoginModule</class>
      <control-flag>...</control-flag>
      <options>
         <option>
            <name>oracle.security.jaas.ldap.provider.url</name>
            <value>ldaps://myhost.example.com:636</value>
         </option>
         ...more options...
      </options>
   </login-module>

Important:

This configuration is sufficient for SSL in "no authentication" mode, but any external LDAP provider presumably requires at least one-way authentication (for communication to the LDAP server). The additional steps for that are discussed in the next section, "Configuring the External LDAP Provider for SSL".

Configuring the External LDAP Provider for SSL

SSL communication between OC4J and an external LDAP provider requires the following:

  • The external LDAP provider must be configured to use SSL. It must have a wallet or keystore that contains its certificate as well as the certificate of the CA that issued its certificate (issued the external LDAP provider certificate).

  • OC4J must be configured to use SSL, as discussed in Chapter 15, "SSL Communication with OC4J". Its wallet or keystore must contain a certificate that identifies the container, as well as the certificate of the CA that issued its certificate (issued the OC4J certificate).

  • All trustpoints (CAs) used in the process must be imported into the wallets or keystores used by the external LDAP provider and by OC4J. If different CAs are used to sign the OC4J and external LDAP provider certificates, then the OC4J and external LDAP provider wallet or keystore each must contain a copy of the certificate of each of these CAs.

You can use the following general steps to configure an external LDAP provider, such as Active Directory or Sun Java System Directory Server, for SSL using standard JSSE functionality and one-way authentication (two-way authentication is not supported for use with external LDAP providers in the current release):

  1. Import the root CA certificate from the directory server to your local machine. For example, create your own keystore and then import the root CA certificate to this keystore. You can accomplish this using the JSSE keytool.

  2. Set Java system properties as necessary for your truststore:

    • Set the -Djavax.net.ssl.trustStore property to indicate the path to your wallet or keystore that serves as truststore.

    • If you need to secure the truststore, also set the -Djavax.net.ssl.trustStorePassword property. (This may not necessary for one-way authentication, as the truststore would typically contain only public keys.)

    For standalone OC4J, accomplish this on the JVM command line. In an Oracle Application Server environment, accomplish this through Java property settings for the OC4J instance in the opmn.xml file.

Here is a sample opmn.xml entry for the OC4J home instance:

<ias-component id="OC4J">
   <process-type id="home" module-id="OC4J" status="enabled">
      <module-data>
         <category id="start-parameters">
            <data id="java-options" value="-Xrs -server
                  -Djava.security.policy=
                      $ORACLE_HOME/j2ee/home/config/java2.policy
                  -Djava.awt.headless=true 
                  -Dhttp.webdir.enable=false"
                  -Djavax.net.ssl.trustStore=pathtotruststore/>
         </category>
         ...
      </module-data>
      ...
   </process-type>
</ias-component>

See Also: