Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
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
Steps to Use the Oracle Identity Management Security Provider
Settings for Authentication Method with Oracle Identity Management
Be aware of the following notes regarding the use of Oracle Identity Management with OC4J:
Beginning with OC4J 10.1.3.x implementations, the LDAP-based provider is supported in standalone OC4J as well as in an Oracle Application Server environment.
The OracleAS JAAS Provider supports the identity management realm type in Oracle Internet Directory. (This realm type is discussed in "Overview of OracleAS JAAS Provider Realms for Oracle Identity Management".) The external and application realm types are deprecated. Specifically, in package oracle.security.jazn.realm
, APPLICATION_REALM
and EXTERNAL_REALM
are deprecated in the RealmType
class; _extRealm
and _appRealm
are deprecated in the InitRealmInfo
class. External realms and application realms will be desupported in future releases.
Managing users and roles in Oracle Internet Directory is beyond the scope of this document. Consult the Oracle Identity Management Guide to Delegated Administration.
OC4J provides a login module, LDAPLoginModule
, for use with LDAP servers. For Oracle Internet Directory, however, use the default RealmLoginModule
. (Configuring LDAPLoginModule
for use with Oracle Internet Directory would result in the loss of optimizations and integrations that are otherwise available.)
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:
For information about migrating from a file-based repository to an Oracle Internet Directory repository, "OracleAS JAAS Provider Migration Tool"
For information about user and role APIs that you can use with Oracle Internet Directory, Chapter 12, "User and Role API Framework"
"Creating a New Administrator Account" if you want to use an administrator account other than oc4jadmin
.
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:
See Also:
Oracle Identity Management Infrastructure Administrator's Guide
Oracle Identity Management Application Developer's Guide
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.
See Also:
Oracle Internet Directory Administrator's Guide
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.
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:
Oracle Application Server Single Sign-On Administrator's Guide
Oracle Identity Management Application Developer's Guide (particularly the chapter on developing applications for single sign-on)
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
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.
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.
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).
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).
The security provider retrieves the Oracle Single Sign-On user.
See Also:
Oracle Application Server Single Sign-On Administrator's Guide for details on Oracle Single Sign-On
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.
This section documents the steps involved in setting up Oracle Identity Management as your security provider, optionally using Oracle Single Sign-On for authentication:
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.
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:
In the OC4J Home page for your instance, choose the Administration tab.
In the resulting Administration page, choose the Identity Management task (one of the Security tasks).
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".)
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.
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.
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.
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.
As in the previous section, "Associating Oracle Internet Directory with OC4J", navigate to the Identity Management page.
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.)
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.
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.
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:
"Predefined Accounts" for additional information about the OC4J accounts
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 ofJAZNAdminGroup
.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.
This step is required only if you want to use Oracle Single Sign-On functionality with Oracle Identity Management. The following subtopics are covered:
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.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 |
---|---|
|
The absolute path to the |
|
Name of the Web site, such as |
|
A |
|
A URL consisting of the host name and port where your application will run: http://www.example.com:7777 |
|
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 |
|
Desired location of the 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:
Oracle Application Server Single Sign-On Administrator's Guide for additional information about the ssoreg
utility, including options not mentioned here
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.
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
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 thesso.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.You must restart Oracle HTTP Server and OC4J for the registration to take effect.
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
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):
Go to the Select Security Provider task.
In the resulting Deployment Settings: Select Security Provider page, choose Oracle Identity Management from the Security Provider dropdown list.
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.
Choose OK to finish the security provider selection.
Confirm the JAAS mode setting, as appropriate:
Back in the Deploy: Deployment Settings page, under "Advanced Deployment Plan Editing", choose Edit Deployment Plan.
In the Deploy: Deployment Settings: Edit Deployment Plan page, in the Edit OC4J Descriptor tab, for the jazn
descriptor, choose Edit jazn.
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.
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.
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.
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:
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 Identity Management Security Provider from the Security Provider Type dropdown.
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.
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.
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:
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.
Before using digest authentication with Oracle Identity Management as your security provider, you must complete the following preparatory steps:
Using Oracle Directory Manager, update the Oracle Internet Directory password policy for your realm:
Launch Oracle Directory Manager with the oidadmin
command.
In the Oracle Directory Manager "System Objects" window, under "Oracle Internet Directory Servers", look for the appropriate server (if there are more than one).
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
".
In the Oracle Directory Manager "Password Policy for Realm..." window, enable Userpassword Reversible Encryption.
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).
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.)
This section discusses realm management for the LDAP-based provider, Oracle Identity Management. The following topics are covered:
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:
Relation of JAAS Provider Realms to Oracle Internet Directory Realms
Access Control Lists and OracleAS JAAS Provider Directory Entries
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
.
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
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
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.
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:
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.
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:
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.
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.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):
Create the realms, as summarized immediately above.
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.
Enable hosting on the single sign-on server. This is accomplished through a script called enblhstg.csh
.
Create an entry for each realm in the Oracle Single Sign-On database. This is accomplished through a script called addsub.csh
.
Update the sample login page to create a version of the page for multiple realms.
Stop and restart the Oracle Single Sign-On middle tier.
Grant administrative privileges for multiple realms. This is also discussed in the Oracle Application Server Single Sign-On Administrator's Guide.
Configure Oracle Single Sign-On as described in "Configure SSO (Optional)".
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.
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 thejazn.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.Oracle Identity Management Guide to Delegated Administration for information about creating users and roles, through the Oracle Delegated Administration Services (DAS), when using Oracle Identity Management
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 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 |
|
Obfuscated password for the LDAP user name. For example:
See Also: "Password Obfuscation in OC4J Configuration Files" for details on obfuscation. |
|
Determines whether to use SSL. (By default, SSL is used.) Supported settings are " Note: As an alternative to the " |
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.
See Also:
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>
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 |
---|---|---|
|
Number of times the security provider attempts to create an LDAP connection before giving up. |
5 |
|
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 |
---|---|---|
|
Initial size of the LDAP JNDI connection pool. |
5 |
|
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 |
|
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.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 |
---|---|---|
|
If set to |
|
|
If set to |
|
|
If set to |
|
|
Initial capacity for the hashmap. This property affects performance; it is important to not set it too low. |
20 |
|
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 |
|
String containing an integer that represents the number of milliseconds the daemon thread waits before it starts checking for expired objects. |
3600000 (one hour) |
|
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.
Important issues when troubleshooting the Oracle Identity Management LDAP-based provider include:
Using ldapsearch to Retrieve Realm Names from Oracle Internet Directory
Avoiding OC4J Restart for Oracle Internet Directory Changes to Take Effect
To verify that your usage of Oracle Identity Management has been configured properly, do the following:
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.
Go to the Security Provider page, as described in "Navigating to the Security Provider Page for Your Application".
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.
Issue the Admintool -listrealms
command to verify that data can be retrieved from Oracle Internet Directory.
% java -jar jazn.jar -listrealms
If the Admintool responds with the message "Communication Error
", then it is likely that Oracle Internet Directory is down.
If the Admintool responds with the message "Invalid Credentials
", then the LDAP users and credentials are incorrectly configured.
Note:
In thejazn.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.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.
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
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:
Oracle Internet Directory Administrator's Guide for information about the ldapsearch command
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.
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:
Oracle Application Server Single Sign-On Administrator's Guide for additional information about the Oracle Single Sign-On administration pages