Skip Headers

Oracle® Containers for J2EE Security Guide 10g Release 3 (10.1.3) B14429-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# A Tips and Troubleshooting for OC4J Security

This appendix discusses best practices for the OC4J security, as well as issues to be aware of and related hints:

- Best Practices for OC4J Security

- OC4J Security Issues and Hints

- Logging

## Best Practices for OC4J Security

This section describes best practices in the following areas:

- HTTPS Best Practices

- Overall Security Best Practices

- JAAS Best Practices

### HTTPS Best Practices

Oracle HTTP Server has several features that provide security to an application without requiring you to modify the application. You should evaluate and leverage these features before coding similar features yourself. HTTP security features include:

- Authentication: Oracle HTTP Server can authenticate users and pass the authenticated user ID to an application in a standard manner (`REMOTE_USER`). It also supports single sign-on, thus reusing existing login mechanisms.

- Authorization: Oracle HTTP Server has directives that can allow access to your application only if the end user is authenticated and authorized. Again, no code change is required.

- Encryption: Oracle HTTP Server can provide transparent SSL communication to end customers without any code change on the application.

Other suggestions for securing HTTPS:

- Configure Oracle Application Server to fail attempts to use weak encryption. You can configure Oracle Application Server to use only specified encryption ciphers for HTTPS connections. For example, your application could reject connections from non-128-bit client-side SSL libraries. This ability is especially useful for banks and other financial institutions because it provides server-side control of the encryption strength for each connection.

- Use HTTPS to HTTP appliances for accelerating HTTP over SSL. Use HTTPS everywhere you need to. However, the huge performance overhead of HTTPS forces a trade-off in some situations.

  These appliances provide much better solutions than adding mathematics or cryptography cards to UNIX, Windows, or Linux systems.

- Ensure that sequential HTTPS transfers are requested through the same Web server. Most CPU time in initiating SSL sessions is spent in the key exchange logic, where the bulk encryption key is exchanged. If the accesses are routed to the same Web server, caching the bulk encryption will significantly reduce CPU overhead on subsequent accesses.

- Keep secure pages on separate servers from pages not requiring security. Although it may be easier to place all pages for an application on one HTTPS server, this strategy has enormous performance costs. Reserve your HTTPS server for pages needing SSL, and put the pages not needing SSL on an HTTP server.

  If secure pages are composed of many GIF, JPEG, or other files to be displayed on the same screen, it is probably not worth the effort to segregate secure from unsecured static content. The SSL key exchange (a major consumer of CPU cycles) is likely to be called exactly once in any case, and the overhead of bulk encryption is not that high.

### Overall Security Best Practices

The following general security practices are recommended.

- When assigning privileges to modules, use the lowest levels that are adequate to perform the module functions. Using low-level privileges provides "fault containment"; if security is compromised, it is contained within a small area of the network and cannot invade the entire intranet.

- Tune the SSLSessionCacheTimeout directive if you are using SSL. Oracle HTTP Server caches a client's SSL session information by default. With session caching, only the first connection to the server incurs high latency.

  The default `SSLSessionCacheTimeout` is 300 seconds. Note that the duration of an SSL session is unrelated to the use of HTTP persistent connections. You can change the `SSLSessionCacheTimeout` directive in the `httpd.conf` file to meet your application needs.

### JAAS Best Practices

The following JAAS practices are recommended:

- Migrate your user management from principals.xml to the OracleAS JAAS Provider. In earlier releases of Oracle Application Server, the J2EE application server component stored all user information in a file called `principals.xml` (including storing passwords in cleartext). The OracleAS JAAS Provider uses a similar security model as a default, without storing passwords in cleartext. The OracleAS JAAS Provider also offers tight integration with Oracle Application Server infrastructure (including OracleAS Single Sign-On and Oracle Internet Directory) out of the box.

- Avoid writing custom UserManager classes. The OC4J container continues to supply several methods and levels of extending security providers. Although you can still implement the `UserManager` interface (deprecated in the 10.1.3 release), leveraging the rich functionality provided by the OracleAS JAAS Provider, OracleAS Single Sign-On, and Oracle Internet Directory gives you more time to focus on business logic instead of infrastructure code. Both OracleAS Single Sign-On and Oracle Internet Directory provide APIs to integrate with external authentication servers and directories, respectively. If you require custom functionality, you can use a custom login module instead of a custom `UserManager` implementation.

- Use Oracle Internet Directory as the central repository for the OracleAS JAAS Provider in production environments. Although the OracleAS JAAS Provider supports a file-based repository, it should be configured to use Oracle Identity Management, which uses Oracle Internet Directory as its repository, for most production environments. Oracle Internet Directory provides standard LDAP features for modeling administrative meta data and is built on the Oracle database platform, inheriting all the database properties of scalability, reliability, manageability, and performance.

- Use OracleAS Single Sign-On as the authentication mechanism with the OracleAS JAAS Provider. Various authentication options are available; however, we strongly recommend leveraging the OracleAS Single Sign-On server whenever possible because:

  - It is the default mechanism for most Oracle Application Server components, such as Portal, Forms, Reports, and Wireless.

  - It is easy to set up in a declarative fashion and does not require any custom programming.

  - It provides seamless PKI integration.

- Use the OracleAS JAAS Provider declarative features to reduce programming. Because most of the features in the OracleAS JAAS Provider are controlled declaratively, particularly in the area of authentication, developers can postpone setup until deployment time. This not only reduces the programming tasks for integrating a JAAS-based application, it enables the deployer to use environment-specific security models for that application.

- Use the fine-grained access control offered by the OracleAS JAAS Provider and the Java permission model. Unlike the J2EE authorization model as it exists today, the OracleAS JAAS Provider integrated with OC4J allows any protected resource to be modeled using Java permissions. The Java permission model (and associated `Permission` class) is extensible and allows a flexible way to define access control.

- Take advantage of the authorization features of the OracleAS JAAS Provider. In addition to the authorization functionality defined in the JAAS 1.0 specification, the OracleAS JAAS Provider supports:

  - Hierarchical, role-based access control

  - Ability to partition security policy by subscriber (that is, each user community)

  These extensions provide a more scalable and manageable framework for security policies covering a large user population.

## OC4J Security Issues and Hints

Be aware of the following issues and how to handle them:

- File jazn.xml Not Found

- Issues for Custom Login Modules

- Issues for Oracle Identity Management

- Failure to Specify OracleAS JAAS Provider as the JAAS Provider

- Realm Issues

### File jazn.xml Not Found

Without a valid `jazn.xml` file, the OracleAS JAAS Provider cannot begin running. If no `jazn.xml` file is found, the following error message is generated.

    "JAZN has not been properly configured"

See Also: "The jazn.xml File"

### Issues for Custom Login Modules

When implementing a custom login module, you should be aware of the following issues:

- Subject-Based Authorization

- J2EE Security Integration

#### Subject-Based Authorization

When an application uses a custom login module, the subject (and the principals it contains) are used as the sole basis for authorization, including the evaluation of J2EE security constraints. To ensure that all relevant principals are taken into consideration during authorization, the login module should add the relevant principals (including any roles that the authenticated user belongs to) to the subject during the `commit` phase of the authentication process.

#### J2EE Security Integration

The custom login module framework supports the J2EE declarative security model. That is, the J2EE security constraints declared in application deployment descriptors, such as `web.xml` and `ejb-jar.xml`, are enforced using subject-based authorization.

We encourage J2EE developers to take advantage of the J2EE security model whenever possible, rather than writing their own security implementation; this ensures forward compatibility with future releases.

### Issues for Oracle Identity Management

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

- Checking Configuration (JAZN-LDAP)

- Using ldapsearch to Retrieve Realm Names from Oracle Internet Directory

- Avoiding OC4J Restart for Oracle Internet Directory Changes to Take Effect

#### 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: The Oracle Internet Directory location and port are reflected in the bootstrap `jazn.xml` file.

#### Using ldapsearch to Retrie ve Realm Names from Oracle Internet Directory

In case the OracleAS JAAS Provider Admintool is unavailable, you can use LDAP search commands to retrieve a realm name from Oracle Internet Directory, as follows. (If the Admintool is available, use its `-listrealms` command instead, as shown in the preceding section.)

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: Oracle Identity Management Guide to Delegated Administration

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

### Failure to Specify OracleAS JAAS Provider as the JAAS Provider

If you receive an exception and stack trace similar to:

    Exception in thread "main" java.lang.SecurityException: Unable to locate a login configuration
    at com.sun.security.auth.login.ConfigFile.<init>(ConfigFile.java:97)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance

You have probably failed to specify the OracleAS JAAS Provider as the JAAS provider.

See Also: "Specifying an Alternate JAAS Policy Provider"

### Realm Issues

This section discusses the following troubleshooting issues related to the use of realms:

- Realm Names Omitted from User Names

- Specifying Default Realm to Solve Authentication Failure

#### Realm Names Omitted from User Names

The OC4J property `jaas.username.simple` determines whether realm names are prefixed in user names for returned principals from key methods such as `getUserPrincipal()` or `getRemoteUser()` for servlets, or `getCallerPrincipal()` for EJBs. With the default "`true`" setting, realm names are not prefixed.

If you configure and use custom realms, you must explicitly set this property to "`false`" to ensure that OracleAS JAAS Provider authentication and authorization work properly. See "Omitting the Realm Name When Retrieving an Authenticated Principal" for details.

#### Specifying Default Realm to Solve Authentication Failure

If authentication fails but your configuration seems correct, confirm whether you need to specify your default realm. You must configure a default realm (in the `<jazn>` element of the `orion-application.xml` file) if you use a default realm other than what is specified in the instance-level `jazn.xml` file.

This can apply to either the file-based provider or LDAP-based provider.

## Log ging

This section discusses logging features to aid in debugging:

- Using Oracle Diagnostic Logging with OracleAS JAAS Provider

- Using Standard JDK Logging with the OracleAS JAAS Provider Admintool

- See Also: Oracle Containers for J2EE Developer's Guide for an introduction and overview of standard Java logging features Oracle Containers for J2EE Configuration and Administration Guide for information for about logging configuration and logging levels Javadoc for the java.util.logging package:
      http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html

### Using Oracle Diagnostic Logging with OracleAS JAAS Provider

OC4J and OracleAS JAAS Provider support the Oracle Diagnostic Logging framework, or ODL, which provides plug-in components that complement the standard Java logging framework to automatically integrate log data with Oracle log analysis tools.

As with OC4J in general, change the logging level in `ORACLE_HOME``/j2ee/home/config/j2ee-logging.xml` from the default `NOTIFICATION:1` to some appropriate error or debug level. Two levels often used with OracleAS JAAS Provider are `FINE` and `FINER`, which correspond to `TRACE:1` and `TRACE:16`, respectively.

OracleAS JAAS Provider logging entries are in `ORACLE_HOME``/j2ee/``instance_name``/logs/oc4j/log.xml`, where relevant entries are the ones with a `COMPONENT_ID` of `j2ee` and a `MODULE_ID` of `security`, as in the following sample message:

    <MESSAGE>
     <HEADER>
       <TSTZ_ORIGINATING>2005-12-14T11:41:08.974-08:00</TSTZ_ORIGINATING>
       <COMPONENT_ID>j2ee</COMPONENT_ID>
       <MSG_TYPE TYPE="TRACE"></MSG_TYPE>
       <MSG_LEVEL>16</MSG_LEVEL>
       <HOST_ID>www.example.com</HOST_ID>
       <HOST_NWADDR>555.55.5.555</HOST_NWADDR>
       <MODULE_ID>security</MODULE_ID>
       <THREAD_ID>10</THREAD_ID>
       <USER_ID>nmuralid</USER_ID>
     </HEADER>
     <CORRELATION_DATA>
       <EXEC_CONTEXT_ID>
          <UNIQUE_ID>555.55.5.555:30508:1134589268971:0</UNIQUE_ID><SEQ>0</SEQ>
       </EXEC_CONTEXT_ID>
     </CORRELATION_DATA>
     <PAYLOAD>
       <MSG_TEXT>location=system-jazn-data.xml</MSG_TEXT>
     </PAYLOAD>
    </MESSAGE>

Alternatively, if you want only OracleAS JAAS Provider messages logged in the first place, you can add configuration to `j2ee-logging.xml` to set the logger name to `oracle.j2ee.security`, as in the following example:

    <logger name="oracle.j2ee.security" level="NOTIFICATION:32"
            useParentHandlers="false">
       <handler name="oc4j-handler"/>
       <handler name="console-handler"/>
    </logger>

### Using Standard JDK Logging with the OracleAS JAAS Provider Admintool

OracleAS JAAS Provider supports standard JDK logging. To run logging with the OracleAS JAAS Provider Admintool, change the logging level from `INFO` to `FINE`, `FINER`, or `FINEST`. You can accomplish this either by editing the `JAVA_HOME``/jre/lib/logging.properties` file, or by providing an updated copy of the file on the Admintool command line. The following command executes the Admintool and provides a properties file to set an appropriate logging level. Messages will be logged according to the configured log handler.

    % java -jar jazn.jar -Djava.util.logging.config.file=modified_logging_properties

Note: The `jazn.debug.log.enable` flag, used in previous releases, is no longer supported.