A Tips and Troubleshooting for OC4J Security

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

• Best Practices for OC4J Security

• General OC4J Security Tips and Troubleshooting

• Logging

Note:

There are also troubleshooting notes and sections elsewhere in this book, particular to the topics of the chapters where they appear.

Best Practices for OC4J Security

This section describes best practices in the following areas:

• JAAS Best Practices

• HTTPS Best Practices

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 Oracle Single Sign-On and Oracle Internet Directory) out of the box. Refer to "Migrating Principals from the principals.xml File".

• 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 10.1.3.x releases), you will have more time to focus on business logic instead of infrastructure code if you leverage the rich functionality provided by the OracleAS JAAS Provider, Oracle Single Sign-On, and Oracle Internet Directory. Both Oracle 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. (Alternatively, use one of the external LDAP providers that Oracle supports.)

• Use Oracle Single Sign-On as the authentication mechanism with the OracleAS JAAS Provider. Various authentication options are available; however, we strongly recommend leveraging the Oracle 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.

  (Alternatively, use Java SSO if your installation does not include Oracle Application Server infrastructure.)

• Use the OracleAS JAAS Provider declarative features to reduce programming. Because most of the features in the OracleAS JAAS Provider are controlled declaratively (through configuration), 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.

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

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

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

• Tune the Oracle HTTP ServerSSLSessionCacheTimeout 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.

See Also:

• Oracle HTTP Server Administrator's Guide

General OC4J Security Tips and Troubleshooting

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

• File jazn.xml Not Found

• Authentication Issues

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

Authentication Issues

If you attempt to log in to a protected application and authentication fails, but you know the user and password are properly configured in the identity repository, confirm by some other means that the identity repository is up and available, and is in the location specified in the <jazn> element location attribute in orion-application.xml or jazn.xml (as applicable).

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

Then the OracleAS JAAS Provider is probably not specified as the JAAS policy provider.

See Also:

• "Specification of the Oracle 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.

Logging

This section discusses logging features to aid in debugging:

• Using Oracle Diagnostic Logging with the OracleAS JAAS Provider

• Using Standard JDK Logging with the OracleAS JAAS Provider Admintool

See Also:

• The following location for an overview of standard Java logging:

  http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html
  

• Javadoc for the java.util.logging package:

  http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html
  

• Oracle Containers for J2EE Developer's Guide and Oracle Containers for J2EE Configuration and Administration Guide for information about logging features and logging configuration in OC4J

Using Oracle Diagnostic Logging with the OracleAS JAAS Provider

OC4J and the 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

The OracleAS JAAS Provider Admintool uses standard JDK logging. To run logging with the Admintool, change the logging level from INFO to FINE, FINER, or FINEST. (Most log messages from the Admintool are logged at level FINE or FINER.) 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.