Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
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
Creating Necessary Accounts and Granting Necessary Permissions
OC4J 10.1.3.x implementations support 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.
Beginning with OC4J 10.1.3.x implementations, external LDAP providers are supported in standalone OC4J as well as in an Oracle Application Server environment.
The concept of security realms is not supported when using external LDAP providers.
See "OracleAS JAAS Provider Policy Management" regarding subject-based policy management when using an external LDAP provider. The policy configuration must be in system-jazn-data.xml
.
See Also:
For information about user and role APIs that you can use with external LDAP providers, Chapter 12, "User and Role API Framework"
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" />
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:
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 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 directoryORACLE_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.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 (asoc4jadmin
, for example).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):
Go to the Select Security Provider task.
In the resulting Deployment Settings: Select Security Provider page, choose Third Party LDAP Server from the Security Provider dropdown list.
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 10-1, "Application Server Control External LDAP Provider Options"
Table 10-2, "Application Server Control External LDAP Connection Pool Options" (if you enable connection pooling)
Table 10-3, "Application Server Control External LDAP User Options"
Table 10-4, "Application Server Control External LDAP Role and Member Options"
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.
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.
Choose OK to finish the security provider selection.
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: |
oracle.security.jaas.ldap.lm.cache_enabled |
Enable Connection Pooling (checkbox) |
Default: |
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 |
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:
Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".
In the Security Provider page, choose Change Security Provider.
In the Change Security Provider page, select Oracle Security Provider for 3rd Party LDAP Server from the Security Provider Type dropdown.
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:
Table 10-1, "Application Server Control External LDAP Provider Options"
Table 10-2, "Application Server Control External LDAP Connection Pool Options" (if you enable connection pooling)
Table 10-3, "Application Server Control External LDAP User Options"
Table 10-4, "Application Server Control External LDAP Role and Member Options"
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.
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.
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.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:
"Settings in system-jazn-data.xml for Sun Java System Directory Server" for examples of some option settings
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://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 |
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 |
oracle.security.jaas.ldap.provider.connect.pool |
(Optional) Boolean indicating whether connection pooling is enabled. A |
oracle.security.jaas.ldap.lm.cache_enabled |
(Optional) Boolean indicating whether login module caching is enabled. A |
oracle.security.jaas.ldap.context.referral |
(Optional) Can have one of the following values: |
oracle.security.jaas.ldap.object.category |
(Optional) This is to be used only with Active Directory and specifies the |
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 |
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 |
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 |
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 " |
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 |
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 |
oracle.security.jaas.ldap.membership.searchscope |
Specifies how deep in the LDAP directory tree to search for role membership. Supported values are |
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 |
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.
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:
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.)
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.)
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.)
Grant these roles to the administrative user, using the appropriate tool.
Create the additional administrator roles oc4j-app-administrators
, ascontrol_appadmin
, and ascontrol_monitor
. (These do not have to be granted to the administrative user.)
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.
See Also:
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>
Any additional permission required by any external LDAP principal can be granted in the same way as RMI permission, shown in the preceding section.
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.
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 filesample_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.)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
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 an External LDAP 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>
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
.
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:"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).
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".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):
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
.
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:
"Using Keys and Certificates with OC4J and Oracle HTTP Server" and "Using SSL with Standalone OC4J" for introductory information about keytool
For detailed information about the keytool
utility:
http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html
Oracle Containers for J2EE Configuration and Administration Guide, in the chapter on OC4J runtime configuration, for general information about setting system properties