Skip Headers
Oracle® Containers for J2EE Security Guide
10g (10.1.3.5.0)
E13977-01
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

8 Oracle Identity Management

In Oracle Application Server, Oracle Identity Management with Oracle Internet Directory and (optionally) Oracle Single Sign-On is the LDAP-based security provider.

This chapter is for those who use or plan to use Oracle Identity Management as the security provider, and covers the integration of Oracle Identity Management with OC4J. The following topics are covered:

Initial Considerations for OC4J Support of Oracle Identity Management

Be aware of the following notes regarding the use of Oracle Identity Management with OC4J:


Notes:

  • Be aware that with the LDAP-based provider, role comparisons for authorization are not case-sensitive.

  • After you add or modify a user account in Oracle Internet Directory, you should be able to log in without restarting OC4J, assuming you have associated Oracle Internet Directory with OC4J as described in "Associate Oracle Internet Directory with OC4J".



See Also:


Overview of Oracle Identity Management Key Components

Oracle Identity Management provides an enterprise infrastructure for securing distributed enterprise applications. It is an integrated package that includes the LDAP-based Oracle Internet Directory, Oracle Single Sign-On, and additional security and user management functionality.

To use Oracle Identity Management as your security provider, you must consider the underlying Oracle Internet Directory and Oracle Single Sign-On. This section provides an overview of these features, covering the following topics:

Overview of Oracle Internet Directory

Oracle Internet Directory provides Windows integration, password policy options, partial replication, and other important security features, including the following.

  • Windows integration capabilities: Provides a preconfigured directory synchronization solution for Windows Active Directory Services. This feature allows users to have a single identity and password credential across Oracle and Windows environments. It also includes directory plug-ins that support mastering and changing passwords stored in the Windows environment, thereby relieving customers of overhead and potential security concerns associated with synchronizing passwords across the two environments.

  • Flexible password policy: Supports password policy options. In addition, Oracle Internet Directory plug-in support allows customers to implement an almost unlimited variety of site-specific password policies.

  • Partial replication: Supports replication models, enabling improved scalability and performance in large network configurations.

  • Other features include support for dynamic groups, an expanded Oracle Internet Directory Self-Service Console, easy synchronization of directory data with database tables, and features to permit user identity synchronization with the Oracle e-Business Suite Release 11i.

When using Oracle Internet Directory with OC4J 10.1.3.x implementations, the basic, digest, client-cert, username token, X.509 token, and SAML token authentication methods are supported.

About Distinguished Names

The term distinguished name, or DN, is used frequently in this chapter. This is a standard LDAP concept. A DN comprises a set of one or more relative distinguished names (RDNs) separated by commas. An RDN can be any of the following:

  • DC (domain component)

  • CN (common name)

  • OU (organizational unit name)

  • O (organization name)

  • STREET (street address)

  • L (locality name)

  • ST (state or province)

  • C (country)

  • UID (user ID)

RDNs most often consist of common names or domain components in the discussion in this chapter. A common name could be something like "Jeff Smith" or "Oracle", for example.

Overview of Oracle Single Sign-On

Oracle Single Sign-On supports multilevel authentication. This allows customers to establish more than one authentication mechanism, and indicates the way in which a user is authenticated to single sign-on enabled applications. Applications can take advantage of this to grant different degrees of privilege to users, depending on how they authenticated.

For example, users may get partial privileges if they authenticate using a password, but more complete privileges if they use stronger authentication, such as X.509v3.

There is also support for global logout and session timeout.


See Also:


SSO-Enabled J2EE Environment: Typical Scenario

Oracle Single Sign-On lets a user access multiple applications with a single set of login credentials. Figure 8-1 shows JAAS integration in an application running in an SSO-enabled J2EE environment.

Figure 8-1 Oracle Single Sign-On and J2EE Environments

Description of Figure 8-1 follows
Description of "Figure 8-1 Oracle Single Sign-On and J2EE Environments"

The following steps describe the responsibilities of Oracle components when an HTTP client request is initiated in a J2EE environment with Oracle Single Sign-On enabled.

  1. An HTTP client attempts to access a Web application, WebApp A1, hosted by OC4J (the Web container for executing servlets). Oracle HTTP Server (using an Apache listener) handles the request.

  2. Oracle HTTP Server/mod_osso receives the request and:

    • Determines that WebApp A1 application requires Web-based Oracle Single Sign-On for authenticating HTTP clients.

    • Redirects the HTTP client request to the Web-based Oracle Single Sign-On (because it has not yet been authenticated).

  3. The HTTP client is authenticated by OracleAS Single Sign-On through a user name and password or through a user certificate. OracleAS Single Sign-On then:

    • Validates the user's stored login credentials.

    • Sets the Oracle Single Sign-On cookie (including the user's distinguished name and realm).

    • Redirects back to the WebApp A1 application (in OC4J).

  4. The security provider retrieves the Oracle Single Sign-On user.


See Also:


Prerequisite: Oracle Application Server Infrastructure

Oracle Identity Management is part of the Oracle Application Server infrastructure. Using Oracle Identity Management as security provider requires a suitable version of the infrastructure to be installed. This is in a separate ORACLE_HOME from OC4J.

For using Oracle Identity Management (with Oracle Internet Directory) as the security provider under OracleAS JAAS Provider in the OC4J 10.1.3.1 implementation, the supported versions of the Oracle Application Server infrastructure are 10.1.2.0.1, 10.1.2.0.2, and 10.1.4.x.

For information about installing Oracle Application Server infrastructure, refer to the appropriate Oracle Application Server Installation Guide for your platform.

Steps to Use the Oracle Identity Management Security Provider

This section documents the steps involved in setting up Oracle Identity Management as your security provider, optionally using Oracle Single Sign-On for authentication:

  1. Associate Oracle Internet Directory with OC4J

  2. Configure SSO (Optional)

  3. Configure Oracle Identity Management as the Security Provider

Associate Oracle Internet Directory with OC4J

This section discusses the step of associating an Oracle Internet Directory instance with your OC4J instance, which you must do before you can specify Oracle Identity Management as the security provider. It also shows the corresponding XML configuration. The following subtopics are covered:


Important:

  • When you associate an OC4J instance with an Oracle Internet Directory instance, the <jazn> element configuration in the jazn.xml file of the OC4J home instance is rewritten and any previous settings are lost.

  • Associating an Oracle Internet Directory instance with an OC4J instance results in provider settings at the instance level—such as the provider and location attribute settings in the <jazn> element of the jazn.xml file. If you deploy an application to the OC4J instance, and the application configures a different provider, the result would be a mixed usage where the provider configured in orion-application.xml would be the identity store used for authentication, while the provider specified in jazn.xml would be the policy store used for authorization.


Associating Oracle Internet Directory with OC4J

Use the Application Server Control Console to associate your OC4J instance with an instance of the LDAP-based Oracle Internet Directory (OID), the repository for Oracle Identity Management. Here are the steps:

  1. In the OC4J Home page for your instance, choose the Administration tab.

  2. In the resulting Administration page, choose the Identity Management task (one of the Security tasks).

  3. In the resulting Identity Management page, choose Configure. (This assumes no Oracle Internet Directory instance was previously associated with the OC4J instance, so that the Oracle Internet Directory host name and port are listed as "not configured". If a different Oracle Internet Directory instance was previously associated with this OC4J instance, see the next section, "Changing the Oracle Internet Directory Association".)

  4. In the resulting Configure Identity Management: Connection Information page, do the following:

    • Specify the fully qualified host name for the Oracle Internet Directory instance (myoid.oracle.com, for example).

    • Specify the distinguished name for the Oracle Internet Directory user, such as cn=orcladmin (see note below). The user specified here must belong to the iASAdmins role in the Oracle Internet Directory instance.

    • Specify the password for the Oracle Internet Directory user. This will also be set as the default password for the oc4jadmin user created in Oracle Internet Directory (unless the oc4jadmin account had previously been created, due to associating a different OC4J instance with the Oracle Internet Directory instance).

    • Specify whether to use SSL connections or non-SSL connections to the Oracle Internet Directory instance, and the appropriate port to use. The port for SSL is typically 636; for non-SSL it is typically 389. (To change the SSL or port setting later, you would have to redo the OC4J-OID association, as described in the next section, "Changing the Oracle Internet Directory Association".)

    • When you are done, go to the next page.

  5. In the Configure Identity Management: Application Server Control page, you can optionally specify Oracle Identity Management as the security provider for Application Server Control. (If you do this, only users and roles defined in the Oracle Internet Directory instance will be able to access Application Server Control.)

    When you are done, go to the next page.

  6. In the Configure Identity Management: Deployed Applications page, you can optionally specify Oracle Internet Directory (actually, Oracle Identity Management), with or without SSO, as the security provider for each deployed application in the OC4J instance.

    When you are done, choose Configure. This completes the OC4J-OID association process and takes you back to the Identity Management page.


Notes:

  • Using SSL requires appropriate SSL configuration for OC4J and Oracle Internet Directory, as discussed in Chapter 15, "SSL Communication with OC4J", and the Oracle Internet Directory Administrator’s Guide, respectively.

  • Because Oracle Internet Directory is associated at OC4J instance level, OracleAS JAAS Provider picks up the Oracle Internet Directory host, port, password, and SSL settings only from the jazn.xml file of a given OC4J instance, not from any application-level configuration.

  • Each user in a directory must have a unique distinguished name.


Changing the Oracle Internet Directory Association

This section describes the steps to change the OC4J-OID association to use a different Oracle Internet Directory instance, or to change the port or SSL configuration. A new OracleAS JAAS Provider administrator account (for internal use) is created in Oracle Internet Directory.

  1. As in the previous section, "Associating Oracle Internet Directory with OC4J", navigate to the Identity Management page.

  2. In the Identity Management page, choose Change. (This is in the same place as Configure would be if there had been no previous OC4J-OID association.)

  3. In the Change Identity Management page, as for the Configure Identity Management page in the previous section, specify the Oracle Internet Directory host name, the distinguished name and password of the Oracle Internet Directory user, whether to use SSL connections, and the port number for connections.

  4. Choose OK. This completes the OC4J-OID reassociation process and brings you back to the Identity Management page. You are prompted to restart OC4J for the change to take effect.

Required Accounts Created in Oracle Internet Directory

Oracle Internet Directory does not by default include certain accounts that are required by OC4J and Application Server Control 10.1.3.x implementations. Therefore, the accounts listed below are created automatically, under the default identity management realm, as part of the OC4J-OID association process. This occurs the first time an OC4J instance is associated with the Oracle Internet Directory instance. On any subsequent associations of the same or any other OC4J instance with the same Oracle Internet Directory instance, these accounts are not changed. In fact, if any of these accounts are found to already exist in Oracle Internet Directory at the time of the OC4J-OID association process, the account creation step is skipped.

  • oc4jadmin user

  • oc4j-administrators role, with member oc4jadmin

  • oc4j-app-administrators role

  • ascontrol_admin (administrative role for all SOA controls, including Application Server Control), with member oc4jadmin

  • ascontrol_appadmin (Application Server Control required role)

  • ascontrol_monitor (Application Server Control required role)


Notes:

  • In addition, the JAZNAdminGroup role with its OracleAS JAAS Provider administrator member are shipped with Oracle Internet Directory for internal use.

  • The file oidConfigForOc4j.sbs in directory ORACLE_HOME/j2ee/home/jazn/install contains the OC4J accounts and permissions for default users and roles that are created in Oracle Internet Directory the first time an OC4J instance is associated with that Oracle Internet Directory instance. Do not modify or delete this file, as these accounts are required for normal OC4J operations. Also, do not modify or delete any of these default accounts or their permissions once they are created.



See Also:


Oracle Internet Directory Association in jazn.xml

OC4J-OID association is effective at the level of the OC4J home instance. After you have associated OC4J with Oracle Internet Directory, the location, user, password, and LDAP protocol configurations are reflected in the jazn.xml file of the OC4J home instance. Here is a sample entry:

<jazn provider="LDAP" location="ldap://myoid.oracle.com:389" default-realm="us" >
   <property
      name="ldap.user" 
      value="orclApplicationCommonName=jaznadmin1,cn=JAZNContext,cn=products,
             cn=OracleContext"/>
   <property name="ldap.password" 
             value="{903}3o4PTHbgMzVlzbVfKITIO5Bgio6KK9kD"/>
   <property name="ldap.protocol" value="no-ssl"/>
</jazn>

The default realm "us" corresponds to the default identity management realm in Oracle Internet Directory. Supported ldap.protocol settings are "ssl" or "no-ssl", according to whether you use SSL connections. The default is to use SSL, so if you specify SSL when you use Application Server Control, this does not actually result in any ldap.protocol setting.


Note:

At runtime, the LDAP-based provider connects as the OracleAS JAAS Provider administrator to Oracle Internet Directory. This user is a member of JAZNAdminGroup.

Considering Multiple OC4J Instances when Associating Oracle Internet Directory

If you are using Oracle Internet Directory in an environment with multiple OC4J instances (such as the home and SOA instances in a SOA installation), then after you complete the steps for OC4J-OID association detailed earlier (in "Associating Oracle Internet Directory with OC4J"), you must manually copy the relevant <jazn> element configuration from the jazn.xml file of the home instance to the jazn.xml file of any other instance. This includes settings of the provider and location attributes, and any relevant property settings in <property> subelements.

Consider the following example, shown earlier:

<jazn provider="LDAP" location="ldap://myoid.oracle.com:389" default-realm="us" >
   <property
      name="ldap.user" 
      value="orclApplicationCommonName=jaznadmin1,cn=JAZNContext,cn=products,
             cn=OracleContext"/>
   <property name="ldap.password" 
             value="{903}3o4PTHbgMzVlzbVfKITIO5Bgio6KK9kD"/>
   <property name="ldap.protocol" value="no-ssl"/>
</jazn>

All of this configuration would have to be copied. Be careful, however, to not overwrite any special settings in the jazn.xml file of the target instance.

Configure SSO (Optional)

This step is required only if you want to use Oracle Single Sign-On functionality with Oracle Identity Management. The following subtopics are covered:

  1. Run the SSO Registration Tool

  2. Transfer the osso.conf File to the OC4J Instance

  3. Run the osso1013 Script

  4. Synchronization of OracleAS JAAS Provider User Context with Servlet Sessions

  5. Restart the Oracle HTTP Server and OC4J Instances


Important:

Do not confuse this SSO with Java SSO, which is a separate feature (documented in Chapter 14, "OC4J Java Single Sign-On"). You can use one SSO product or the other, but not both.

Run the SSO Registration Tool

The first task in configuring Oracle Single Sign-On is to register your application as a partner application with the single sign-on server in your infrastructure. This is a post-installation step. Accomplish this by running the ssoreg utility in your infrastructure installation (the SSO server system) to create an (obfuscated) osso.conf file.

The ssoreg utility is ORACLE_HOME/sso/bin/ssoreg.sh in a Linux installation or ORACLE_HOME\sso\bin\ssoreg.bat in a Windows installation.

Here is the syntax for ssoreg options required for this usage, with options described in Table 8-1:

-oracle_home_path path
-site_name name
-config_mod_osso TRUE
-mod_osso_url url
-remote_midtier
-config_file path

Table 8-1 Key ssoreg Options

Option Description

oracle_home_path

The absolute path to the ORACLE_HOME location in your infrastructure installation.

site_name

Name of the Web site, such as www.example.com.

config_mod_osso

A TRUE setting (which is what you want) indicates that mod_osso, the Apache mod for Oracle Single Sign-On, is effectively the application being registered. (Actually, your application is being registered through mod_osso.) This results in an obfuscated osso.conf file being generated.

mod_osso_url

A URL consisting of the host name and port where your application will run:

http://www.example.com:7777

remote_midtier

When present on the command line, specifies that the application being registered is on a remote middle tier. Because your OC4J installation is on a different tier (with a different ORACLE_HOME) than your infrastructure, including Oracle Single Sign-On, you must include this option.

config_file

Desired location of the osso.conf file, typically something like:

ORACLE_HOME/Apache/Apache/conf/osso/osso.conf

Here is an example (assume that $ORACLE_HOME has been set properly).

% $ORACLE_HOME/sso/bin/ssoreg.sh -oracle_home_path $ORACLE_HOME \
  -site_name myhost.mydomain.com -config_mod_osso TRUE \
  -mod_osso_url http://myhost.mydomain.com:7777 -remote_midtier \
  -config_file $ORACLE_HOME/Apache/Apache/conf/osso/osso.conf

Important:

To use Oracle Single Sign-On with Oracle Identity Management as the security provider under OracleAS JAAS Provider in a 10.1.2.0.x infrastructure, you must upgrade to 10.1.2.0.1 or higher. Older versions do not support the -remote_midtier option, and ignoring this option may cause unintended changes in Oracle Application Server Distributed Configuration Management (DCM) on the infrastructure host where you run the command.


See Also:


Transfer the osso.conf File to the OC4J Instance

Transfer, such as by FTP, the osso.conf file produced during SSO registration (at your infrastructure installation, after installation) to a desired location on the OC4J middle tier.

Run the osso1013 Script

At your OC4J installation, run a script called osso1013 to complete the SSO registration process, specifying the location where you placed the osso.conf file.

% osso1013 path/osso.conf

This script is located in the ORACLE_HOME/Apache/Apache/bin directory.

On Windows, you may have to run it through Perl:

% perl osso1013 path/osso.conf

Synchronization of OracleAS JAAS Provider User Context with Servlet Sessions

For situations where a Web application is used with the Oracle Identity Management security provider and with Oracle Single Sign-On (acting as the login, timeout, and logout service), OC4J 10.1.3.x implementations support synchronization between the OracleAS JAAS Provider user context and the servlet session.

With this synchronization, if there is an SSO logout or timeout, after which the user tries to access a protected resource, he or she receives the SSO login prompt again. (This does not occur if the user is only trying to access a public resource.)

This synchronization is disabled by default. You can enable it (or explicitly disable it) through the sso.session.synchronize property, which can be set under the <jazn-web-app> element either in the orion-application.xml file or in the orion-web.xml file that is used to configure a single Web application. In the event of competing settings, the orion-web.xml setting takes precedence for the particular Web application.

The following example enables the synchronization in the orion-application.xml file:

<orion-application ... >
   ...
   <jazn ... >
      ...
      <jazn-web-app auth-method="SSO" >
         <property name="sso.session.synchronize" value="true" />
      </jazn-web-app>
      ...
   </jazn>
   ...
</orion-application>

If the sso.session.synchronize property is set to true, then the ldap.cache.session.enable property must also be set to true. For example:

<jazn-web-app auth-method="SSO">
   <property name="sso.session.synchronize" value="true" />
   <property name="ldap.cache.session.enable" value="true" />
</jazn-web-app>

The synchronization feature depends on the session to retrieve a previously stored authenticated user and assumes that the LDAP session cache is enabled. Setting the ldap.cache.session.enable property to false effectively disables using the session to store authenticated users. See "Configuring LDAP Caching Properties" for more information on setting Oracle Internet Directory caching properties.


Note:

If the sso.session.syncronize property is set to true and the ldap.cache.session.enable property is set to false, then the application eventually becomes unable to authenticate using Oracle Identity Management/Oracle Single Sign-On and the OC4J instance must be restarted.

Restart the Oracle HTTP Server and OC4J Instances

You must restart Oracle HTTP Server and OC4J for the registration to take effect.

Configure Oracle Identity Management as the Security Provider

This section covers the step of specifying Oracle Identity Management as the security provider for your application, using the Application Server Control Console. The following subtopics are covered:


Notes:

  • 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).

  • To enable application access to EJBs over RMI, you must grant RMI permission "login" to your user or role. When using the Oracle Identity Management security provider, you can accomplish this through the OracleAS JAAS Provider Admintool. For example:

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

Specifying Oracle Identity Management during Deployment

Assuming you have completed the OC4J-OID association as discussed earlier, you can specify Oracle Identity Management (the LDAP-based provider) as the security provider when you deploy an application through Application Server Control.

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 Oracle Identity Management from the Security Provider dropdown list.

  3. Under "Configuration of Oracle Identity Management Security Provider" (which appears after you choose Oracle Identity Management from the dropdown), do the following:

    • Confirm the Oracle Internet Directory host and port are correct, as established earlier when you associated the Oracle Internet Directory instance with your OC4J instance.

    • Optionally enable Oracle Single Sign-On authentication. This results in the configuration auth-method="SSO" in orion-application.xml for your application, as discussed in "OC4J Configuration for Oracle Single Sign-On Authentication".

      Important: Do not confuse this with enabling Java SSO, which is a separate feature (documented in Chapter 14, "OC4J Java Single Sign-On") that has its own Application Server Control configuration page. You can use one SSO product or the other, but not both.

  4. Choose OK to finish the security provider selection.

  5. Confirm the JAAS mode setting, as appropriate:

    1. Back in the Deploy: Deployment Settings page, under "Advanced Deployment Plan Editing", choose Edit Deployment Plan.

    2. In the Deploy: Deployment Settings: Edit Deployment Plan page, in the Edit OC4J Descriptor tab, for the jazn descriptor, choose Edit jazn.

    3. In the Deploy: Deployment Settings: Edit Deployment Plan: jazn page, be sure the jaasMode attribute is set appropriately (such as to doAsPrivileged if your application requires that mode). Then choose Continue.

    4. Back in the Deploy: Deployment Settings: Edit Deployment Plan page, choose OK.

    Refer to "Introduction to JAAS Mode" and "Configuring and Using JAAS Mode" for more information on when and how to use this mode.

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


Notes:

  • Specifying Oracle Identity Management as the security provider for your application results in the setting provider="LDAP" in the <jazn> element in orion-application.xml.

  • During deployment, there is no need to specify the Oracle Internet Directory location, since this was already specified when you associated OC4J with Oracle Internet Directory (and is reflected in the <jazn> element in jazn.xml).

  • The default realm is the default Oracle Identity Management realm. This is determined when Oracle Internet Directory is installed.


Changing to Oracle Identity Management 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. Assuming you have completed the OC4J-OID association discussed earlier, you can change to the Oracle Identity Management security provider as follows:

  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 Identity Management Security Provider from the Security Provider Type dropdown.

  4. Under "Security Provider Attributes: Oracle Identity Management Security Provider" (which appears after you select Oracle Identify Management in the dropdown):

    • Confirm the Oracle Internet Directory host and port are correct, as established earlier when you associated the Oracle Internet Directory instance with your OC4J instance.

    • Optionally enable Oracle Single Sign-On authentication. This results in the configuration auth-method="SSO" for your application, as discussed in "OC4J Configuration for Oracle Single Sign-On Authentication".

      Important: Do not confuse this with enabling Java SSO, which is a separate feature (documented in Chapter 14, "OC4J Java Single Sign-On") that has its own Application Server Control configuration page. You can use one SSO product or the other, but not both.

  5. Choose OK to finish the change.

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

Settings for Authentication Method with Oracle Identity Management

This section discusses Oracle-specific settings for certain authentication methods you can use when Oracle Identity Management is the security provider for a Web application:

OC4J Configuration for Oracle Single Sign-On Authentication

For use of Oracle Single Sign-On for authentication, the auth-method attribute is set to "SSO" in the <jazn-web-app> element (a subelement of the <jazn> element) in the OC4J orion-application.xml file.

Here is a sample entry:

<orion-application ... >
   ...
   <jazn provider="LDAP" >
      <jazn-web-app auth-method="SSO"/>
      ...
   </jazn>
   ...
</orion-application>

Important:

If you switch from the file-based provider to Oracle Identity Management at any time for any application through Application Server Control, the <jazn> element in orion-application.xml for the application is replaced with the following. Any prior settings within the <jazn> element would be lost and would have to be redone.
<jazn provider="LDAP" />


Notes:

  • You do not need an <auth-method> setting in the web.xml file. Any setting in web.xml would be overridden by the "SSO" setting in orion-application.xml.

  • The auth-method="SSO" setting is automatically written to the orion-application.xml file when you specify Oracle Identity Management with single sign-on when deploying an application through Application Server Control.

  • The <jazn-web-app> element is also supported in the orion-web.xml file. In the event of conflict, orion-web.xml takes precedence over orion-application.xml for the particular Web application in question.


Using Digest Authentication with Oracle Internet Directory

Before using digest authentication with Oracle Identity Management as your security provider, you must complete the following preparatory steps:

  1. Using Oracle Directory Manager, update the Oracle Internet Directory password policy for your realm:

    1. Launch Oracle Directory Manager with the oidadmin command.

    2. In the Oracle Directory Manager "System Objects" window, under "Oracle Internet Directory Servers", look for the appropriate server (if there are more than one).

    3. For the appropriate server, under "Password Policy Management", select "Password Policy" for the appropriate realm that you have configured for the security provider. If your realm is "us", for example, this would be "Password Policy for Realm dc=us,dc=oracle,dc=com".

    4. In the Oracle Directory Manager "Password Policy for Realm..." window, enable Userpassword Reversible Encryption.

  2. Create users and assign roles in Oracle Internet Directory. Do not do this until you have completed step 1. You can administer users and roles through Oracle Delegated Administration Services (DAS).

  3. In the OracleAS JAAS Provider configuration, ensure that SSL has not been disabled for LDAP. Under the <jazn> element in the jazn.xml file of the OC4J home instance, be sure that the ldap.protocol property does not have a setting of "no-ssl". (SSL is enabled by default.)

Realm Management for the LDAP-Based Provider

This section discusses realm management for the LDAP-based provider, Oracle Identity Management. The following topics are covered:

Overview of OracleAS JAAS Provider Realms for Oracle Identity Management

The OracleAS JAAS Provider supports the identity management realm type in Oracle Internet Directory.

The realm framework provides a means for registering Oracle Internet Directory realm instances with the OracleAS JAAS Provider and managing their information.

This section covers the following topics:

Realm Hierarchy for the OracleAS JAAS Provider

As Figure 8-2 illustrates, the OracleAS JAAS Provider stores directory entries within the product container cn=JAZNContext. Beneath cn=JAZNContext is the cn=Realms container, which stores realm entries, and a cn=Policy container, which stores global OracleAS JAAS Provider policies. The cn=Policy container in turn stores two types of entries, cn=Permissions and cn=Grantees.

Figure 8-2 Global JAZNContext Subtree

Description of Figure 8-2 follows
Description of "Figure 8-2 Global JAZNContext Subtree"

Note that the OracleAS JAAS Provider has its own Groups and Users containers. The Groups container contains the role JAZNAdminGroup. The Users container contains the OracleAS JAAS Provider administrative user that populates this role. Both the role and its member user are for internal use only, and note that the administrative user JAZNAdminUser is deprecated. An administrative user is created for each Oracle Application Server middle tier associated with the Oracle Internet Directory. A typical DN for the administrative user is something like the following:

orclapplicationcommonname=jaznadmin1,cn=jazncontext,cn=products,cn=oraclecontext

Using the identity management realm DN, the OracleAS JAAS Provider locates the realm-specific Oracle context and creates a corresponding cn=JAZNContext subtree.

In Figure 8-3, cn=oracle is an identity management realm. The OracleAS JAAS Provider stores the cn=usermgr entry, cn=rolemgr entry, and policy-related entries under the JAZNContext entry corresponding to the identity management realm.

Figure 8-3 Identity Management Realm JAZNContext Subtree

Description of Figure 8-3 follows
Description of "Figure 8-3 Identity Management Realm JAZNContext Subtree"

Relation of JAAS Provider Realms to Oracle Internet Directory Realms

For each identity management realm that you use, a corresponding OracleAS JAAS Provider realm is created. This is the mechanism through which identity management realms in Oracle Internet Directory are visible to the OracleAS JAAS Provider.

In OracleAS JAAS Provider, as shown earlier, a Realms container object exists under the site-wide JAAS context. For each Oracle Internet Directory realm instance, a corresponding realm entry is created under the Realms container to store the realm attributes. The directory hierarchy is known to the OracleAS JAAS Provider, which enables it to create new realm entries in the appropriate directory location and find all the registered realms at runtime.

Oracle Internet Directory has a default identity management realm, depending on the system domain. In United States locations, for example, the default realm has a distinguished name such as "dc=us,dc=abc,dc=com" for company abc. OracleAS JAAS Provider creates a corresponding realm called "us", under cn=Realms,cn=JAZNContext,cn=OracleContext in the directory information tree. This is shown in Figure 8-4 below.

During runtime, the OracleAS JAAS Provider finds each Oracle Internet Directory realm and its attributes (name, user manager implementation class, role manager implementation class, and their properties) and instantiates the realm implementation class with the realm properties for initialization.

Figure 8-4 Simplified Directory Information Tree for the Identity Management Realm

Description of Figure 8-4 follows
Description of "Figure 8-4 Simplified Directory Information Tree for the Identity Management Realm"

Access Control Lists and OracleAS JAAS Provider Directory Entries

OracleAS JAAS Provider directory entries are protected by access control lists (ACLs) at the root of the product subtree. These ACLs grant full read and write privileges for OracleAS JAAS Provider directory objects to the role JAZNAdminGroup and its member OracleAS JAAS Provider administrative superuser (both for internal use only). Non-superusers who are not JAZNAdminGroup members are denied access to OracleAS JAAS Provider entries.

Because identity management JAZNContext subtrees are mirror images of their site-wide parents, the security measures that they use to protect entries are the same.

Realm Management for Oracle Identity Management

This section discusses realm management when you use the LDAP-based provider (Oracle Identity Management), requiring administration tools of the Oracle Internet Directory. The following topics are covered:

Managing Realms in Oracle Internet Directory

Manage users and roles in an Oracle Internet Directory identity management realm by using administrative features of the Oracle Delegated Administration Services (DAS), as detailed in the Oracle Identity Management Guide to Delegated Administration.

In addition, perform any further configuration of an Oracle Internet Directory realm through DAS as well. For example, this includes configuration of the user search base, group search base, user creation base, group creation base, and user nickname attribute.

OracleAS JAAS Provider itself does not perform any management of Oracle Internet Directory realms; it merely looks up existing information in Oracle Internet Directory as necessary.

Changing Your Default Realm

Oracle Internet Directory is shipped with a default realm, but you can optionally use a different realm as your default realm, using the following basic steps:

  1. Create a new identity management realm in Oracle Internet Directory to use as your default realm. This is accomplished through DAS, as detailed in the Oracle Identity Management Guide to Delegated Administration. When you do this, the corresponding OracleAS JAAS Provider realm is provisioned automatically.

  2. Set the OracleAS JAAS Provider default-realm attribute to the desired realm, as described in "Default Realm with the File-Based Provider or Oracle Identity Management".


Important:

Do not use the OracleAS JAAS Provider Admintool to create realms for Oracle Internet Directory. Realms created with this tool are suitable for the file-based provider only, and would not include sufficient information for use with Oracle Internet Directory.

Using Multiple Realms and Oracle Single Sign-On with OC4J

Creating additional identity management realms in Oracle Internet Directory is accomplished much as noted in the preceding section, "Changing Your Default Realm". Use DAS, as detailed in the Oracle Identity Management Guide to Delegated Administration. The corresponding OracleAS JAAS Provider realm is provisioned automatically.


Important:

  • Multiple Oracle Internet Directory realms are supported by OracleAS JAAS Provider only in conjunction with the use of Oracle Single Sign-On.

  • Do not use the OracleAS JAAS Provider Admintool to create realms for Oracle Internet Directory. Realms created with this tool are suitable for the file-based provider only, and would not include sufficient information for use with Oracle Internet Directory.

  • When you add a realm, you may need to make existing applications aware of it. The procedure for doing this is specific to each application; refer to the application documentation.



See Also:

For important additional information about using multiple realms with the OracleAS JAAS Provider:

Additional steps are required for using Oracle Single Sign-On in a multi-realm environment, to make the Oracle Single Sign-On server aware of the realms. In all, using multiple realms with Oracle Single Sign-On consists of the following steps, documented elsewhere (as referenced):

  1. Create the realms, as summarized immediately above.

  2. Configure the single sign-on server for multiple realms. This consists of the following steps, covered in detail in the Oracle Application Server Single Sign-On Administrator’s Guide.

    1. Enable hosting on the single sign-on server. This is accomplished through a script called enblhstg.csh.

    2. Create an entry for each realm in the Oracle Single Sign-On database. This is accomplished through a script called addsub.csh.

    3. Update the sample login page to create a version of the page for multiple realms.

    4. Stop and restart the Oracle Single Sign-On middle tier.

  3. Grant administrative privileges for multiple realms. This is also discussed in the Oracle Application Server Single Sign-On Administrator’s Guide.

  4. Configure Oracle Single Sign-On as described in "Configure SSO (Optional)".

  5. Configure the SSO authentication method setting in OC4J, as described in "OC4J Configuration for Oracle Single Sign-On Authentication".

The authentication sequence for single sign-on to multiple realms is much the same as it is for single sign-on in a single, default realm. The only difference from the user's perspective is that, when a user affiliated with the first type of realm is presented with the login screen, the user must enter not only a user name and password but also a new credential, the realm nickname.

Once a user has entered his credentials, both his realm nickname and user name are mapped to entries in Oracle Internet Directory. More specifically, the single sign-on server uses directory metadata to find the realm entry in the directory. Once it finds this entry, the single sign-on server uses realm metadata to locate the user. Once the user's entry is found, his password, an attribute of his entry, is validated. And once his password is validated, he is authenticated.

LDAP-Based Provider Settings in OC4J Configuration Files

This section describes how to configure aspects of the LDAP-based Oracle Internet Directory, covering the following topics:


Important:

Do not make property settings in the jazn.xml file of the OC4J home instance until after you have associated the OC4J instance with the Oracle Internet Directory instance. When you do the association, the <jazn> element configuration in the home instance jazn.xml file is rewritten and any previous settings are lost.


See Also:


Configuring LDAP User and SSL Properties

Table 8-2 summarizes LDAP user and SSL properties, supported through <property> subelements under the <jazn> element in the jazn.xml file of the OC4J home instance. These parameters are set as appropriate through your configuration in Application Server Control Console when you associate OC4J with Oracle Internet Directory, described earlier in this chapter.


Note:

This discussion assumes appropriate SSL configuration has been completed for OC4J and Oracle Internet Directory, as discussed in Chapter 15, "SSL Communication with OC4J", and the Oracle Internet Directory Administrator’s Guide, respectively.

The resulting configuration is as follows:

<jazn ... >
   ...
   <property name="propname" value="propvalue" />
   ...
</jazn>

You must restart OC4J for the changes to take effect.

Table 8-2 LDAP SSL Properties and Related Properties

Property Name Property Definition

ldap.user

LDAP user name or distinguished name. This element is populated automatically; you should not change the contents. For example:

orclApplicationCommonName=jaznadmin1,cn=JAZNContext,
cn=products,cn=OracleContext

ldap.password

Obfuscated password for the LDAP user name. For example:

{903}oZZYqmGc/iyCaDrD4qs2FHbXf3LAWtMN

See Also: "Password Obfuscation in OC4J Configuration Files" for details on obfuscation.

ldap.protocol

Determines whether to use SSL. (By default, SSL is used.) Supported settings are "ssl" (typically used with port 636) or "no-ssl" (typically used with port 389).

Note: As an alternative to the "ssl" setting, you can use the protocol "ldaps://" in the LDAP URL.


Oracle Internet Directory supports null authentication for SSL communication. Data are encrypted with the Anonymous Diffie-Hellman cipher suite, but no certificates are used for authentication.

Here is a sample configuration:

<jazn provider="LDAP" location="ldap://www.example.com:389" default-realm="us">
   <property name="ldap.protocol" value="no-ssl"/>
   ...
</jazn>

Configuring LDAP Connection Properties

Table 8-3 summarizes LDAP connection properties. Table 8-4 summarizes properties for the LDAP JNDI connection pool. You can set these properties in <property> subelements under the <jazn> element in the instance-level jazn.xml file, as follows:

<jazn ... >
   ...
   <property name="propname" value="propvalue" />
   ...
</jazn>

You must restart OC4J for the changes to take effect.

Table 8-3 LDAP Connection Properties

Property Name Property Definition Default Value

ldap.connect.max.retry

Number of times the security provider attempts to create an LDAP connection before giving up.

5

ldap.connect.sleep.time

Number of milliseconds the security provider waits before retrying a failed LDAP connection attempt.

5000


Table 8-4 LDAP JNDI Connection Pool Properties

Property Name Property Definition Default Value

jndi.ctx_pool.init_size

Initial size of the LDAP JNDI connection pool.

5

jndi.ctx_pool.inc_size

Pool increment size for the LDAP JNDI connection pool—number of connections added to pool whenever the supply of connections in the pool is exhausted.

10

jndi.ctx_pool.timeout

Timeout value, in milliseconds, for the LDAP JNDI connection pool. (This may be useful, for example, when there is a firewall between the middle tier, including the OracleAS JAAS Provider, and the Oracle Internet Directory. The timeout on the firewall connection could be coordinated with the timeout of the directory connection.)

0 (no timeout)



Note:

The configurations discussed here must be performed manually; there is currently no support for these in Application Server Control.

Configuring LDAP Caching Properties

Oracle Internet Directory supports caching, which allows improved performance and scalability. There are three separate caches:

  • Policy cache, which stores grantees and permissions

  • Realm cache, which stores realms, users and roles, and a role graph

  • Session cache, which stores users and role graphs in an HTTP session object (available only to Web-based clients with cookies enabled)

The caching service maintains a global hashmap (java.util.HashMap instance) that is used to store and retrieve cached objects. Expired objects in the hashmap are periodically invalidated and cleaned up automatically, as appropriate. Objects in the cache expire based on a time-to-live algorithm; expiration time can be set through the cache properties described below.


Note:

Only Oracle Internet Directory supports these caches. The file-based provider defaults to caching the entire XML document.

Table 8-5 describes LDAP caching properties and their default values. You can set these properties in <property> subelements under the <jazn> element in the instance-level jazn.xml file, as follows:

<jazn ... >
   ...
   <property name="propname" value="propvalue" />
   ...
</jazn>

Table 8-5 LDAP Cache Properties

Property Description Default

ldap.cache.policy.enable

If set to true, enables policy cache; if set to false, disables policy cache.

true

ldap.cache.realm.enable

If set to true, enables realm cache; if set to false, disables realm cache.

true

ldap.cache.session.enable

If set to true, enables session cache; if set to false, disables the session cache. This property must be set to true when synchronizing the user context with a servlet session. See "Synchronization of OracleAS JAAS Provider User Context with Servlet Sessions".

true

ldap.cache.initial.capacity

Initial capacity for the hashmap. This property affects performance; it is important to not set it too low.

20

ldap.cache.load.factor

Load factor for the hashmap. This is a measure of how full to allow the cache to get before the capacity is automatically increased. This property affects performance; it is important to not set it too high.

0.7

ldap.cache.purge.initial.delay

String containing an integer that represents the number of milliseconds the daemon thread waits before it starts checking for expired objects.

3600000 (one hour)

ldap.cache.purge.timeout

String representation of an integer that represents the number of milliseconds an object remains in cache before being invalidated and removed. It is also the sleep time for the daemon thread between each run looking for expired objects.

3600000 (one hour)


Caching is enabled by default. You should disable the caches when performing certain management and administrative tasks. In particular:

  • Disable the realm cache when managing realms. This includes adding realms, dropping realms, granting roles, and revoking roles.

  • Disable the session cache when you disable HTTP session cookies.

The following example disables all three caches:

<jazn provider="LDAP" location="ldap://myhost.example.com:636" >
   ...
   <property name="ldap.cache.session.enable" value="false" />
   <property name="ldap.cache.realm.enable" value="false" />
   <property name="ldap.cache.policy.enable" value="false" />
   ...
</jazn>

Or, as startup parameter settings:

-Dldap.cache.session.enable=false
-Dldap.cache.realm.enable=false
-Dldap.cache.policy.enable=false

The following example leaves all caches enabled, and sets a cache size of 100 and a 10,000-millisecond timeout:

<jazn provider="LDAP" location="ldap://myhost.example.com:636" >
   <property name="ldap.cache.initial capacity" value="100" />
   <property name="ldap.cache.purget.timeout" value="10000" /> 
</jazn> 

Notes:

  • The OracleAS JAAS Provider Admintool automatically disables caching while it is in operation, then reenables caching when it finishes.

  • The configurations discussed here must be performed manually; there is currently no support for these in Application Server Control.


Tips and Troubleshooting for the LDAP-Based Provider

Important issues when troubleshooting the Oracle Identity Management LDAP-based provider include:

Checking Configuration (JAZN-LDAP)

To verify that your usage of Oracle Identity Management has been configured properly, do the following:

  1. Use Application Server Control to verify that OC4J is associated with an Oracle Internet Directory instance and that the security provider is specified as Oracle Identity Management.

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

    2. In the Security Provider page, confirm that the security provider type is listed as Oracle Identity Management Security Provider, and that the host and port listed for Oracle Internet Directory under the security provider attributes are correct.

  2. Issue the Admintool -listrealms command to verify that data can be retrieved from Oracle Internet Directory.

    % java -jar jazn.jar -listrealms
    
  3. If the Admintool responds with the message "Communication Error", then it is likely that Oracle Internet Directory is down.

  4. If the Admintool responds with the message "Invalid Credentials", then the LDAP users and credentials are incorrectly configured.


Note:

In the jazn.xml file of the OC4J home instance, the <jazn> element has the setting provider="LDAP" to use the LDAP-based provider. This element also reflects the Oracle Internet Directory location and port.

Using ldapsearch to Retrieve Realm Names from Oracle Internet Directory

As an alternative to the OracleAS JAAS Provider Admintool, you can use LDAP search commands to retrieve a realm name from Oracle Internet Directory, as follows.

  1. Start with a command such as the following, specifying the port, host, user DN, and password. This will return values for orclSubscriberNicknameAttribute and orclSubscriberSearchbase.

    % ldapsearch -p port -h host -D dn_of_user -w password \
            -b "cn=common, cn=products,cn=oraclecontext" -s base "objectclass=*" \
            orclSubscriberNicknameAttribute orclSubscriberSearchbase
    
  2. Next, use the values of orclSubscriberNicknameAttribute and orclSubscriberSearchbase to get the realm name:

    % ldapsearch -p port -h host -D dn_of_user -w password \
               -b "orclSubscriberSearchbase" \
               -s sub "orclSubscriberNicknameAttribute=*" \
               orclSubscriberNicknameAttribute
    

This will return the Oracle Internet Directory realm, which is useful if you use multiple identity management realms in Oracle Internet Directory and would like to configure a specific nondefault realm for J2EE applications.


See Also:


Avoiding OC4J Restart for Oracle Internet Directory Changes to Take Effect

When doing administration to Oracle Internet Directory, such as adding grantees, permissions, or groups, you should disable LDAP caching. If caching is left enabled, your changes will not take effect until you stop and restart OC4J. See "Configuring LDAP Caching Properties" for how to disable caching.

Accessing the Oracle Single Sign-On Administration Pages

In the Oracle Identity Management 10.1.4 implementation, you can access the Oracle Single Sign-On administration pages as follows:

http://host:port/sso

You can use this to check Oracle Single Sign-On setup.


Note:

In previous releases, the administration pages were accessed as follows:
http://host:port/pls/orasso


See Also: