Skip Headers

Oracle® Application Server Containers for J2EE Security Guide 10g Release 2 (10.1.2) B14013-02 |
| Library | Product | Contents | Index

Previous | Next |

# 16 Troubleshooting Security Issues

This chapter discusses techniques for locating security problems in your OC4J application. It is divided into the following sections:

- Alternative jazn.xml Locations

- JAZN Admintool

- Custom Login Modules

- LDAP-Based Provider Issues

- Servlets, runas-mode, and doasprivileged-mode

- Creating Realms

- Removing Realm Names from Principals

- Specifying the JAAS Provider

## Alternative jazn.xml Locations

When the OracleAS JAAS Provider starts, it searches for a `jazn.xml` file. The `jazn.xml` file can be in a variety of locations, but is normally in the `ORACLE_HOME``/j2ee/home/config` directory. However, if you specify the location of this file in a system property, the file in the system property takes precedence.

When the OracleAS JAAS Provider starts, it searches for `jazn.xml` in order through the directories specified by:

1. `oracle.security.jazn.config` (system property)

2. `java.security.auth.policy` (system property)

3. `J2EE_HOME``/config` (`J2EE_HOME` is specified by the system property `oracle.j2ee.home`)

4. `ORACLE_HOME``/j2ee/home/config` (`ORACLE_HOME` is specified by the system property `oracle.home`)

5. `./config`

The OracleAS JAAS Provider stops searching after locating a `jazn.xml` file. If no file is found, you receive the error message "`JAZN has not been properly configured`".

## JAZN Admintool

Before using the Admintool, you must set the environment variable controlling loading of dynamic libraries (for example, `LD_LIBRARY_PATH` in Solaris). See Table 2-5, "Dynamic Library Path Settings" for details.

Caution: The Admintool does not require authentication when used with the LDAP-based provider; anyone who runs the tool is granted all rights. This means that it is vital to secure the Admintool in production environments; you normally do this by using file system properties. If you specify the `-user` and `-password` options when using LDAP, they are ignored.

If you are attempting to grant a permission and the Admintool gives the error message "`Permission class not found`", it means that the permission you wish to grant is not in the classpath. You must place the JAR containing the permission class in the `jdk/jre/lib/ext` directory so that the Admintool can locate it.

## Custom Login Modules

When writing a custom `LoginModule`, 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/groups that the authenticated user belongs to) to the subject during the `commit` phase of the JAAS authentication process.

### J2EE Security Integration

The custom `LoginModule` framework supports the J2EE security 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.

## LDAP-Based Provider Issues

The following issues are important when troubleshooting the LDAP-based provider:

- Checking JAZN-LDAP Configuration

- Enabling and Disabling Caching

### Checking JAZN-LDAP Configuration

When you associate an Oracle Application Server instance with Oracle Application Server Infrastructure, either during installation or using Enterprise Manager, the instance is automatically configured to use the LDAP-based provider. The Oracle Internet Directory location and port are determined by the `ORACLE_HOME``/config/ias.properties` file.

To verify that the LDAP-based provider has been configured property, do the following:

1. Use Enterprise Manager to verify that the user manager is set to "LDAP".

2. Issue the JAZN Admintool `-listrealms` command to verify that the LDAP-based provider can retrieve data 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.

### Enabling and Disabling Caching

LDAP caching is enabled by default; caching is per-JVM, not per-application. Before using JAAS Admintool management commands, such as granting permissions or roles, you must disable caching. After you use the Admintool, you should re-enable caching.

See Also: "Configuring LDAP Caching" for details on enabling and disabling caching

## Servlets, runas-mode, and doasprivileged-mode

If you want a servlet to be invoked using `subject.doAs()` or `subject.doAsPrivileged()`, you must set the `runas-mode` and `doasprivileged-mode` attributes of the `<jazn-web-app>` element in the `orion-web.xml` or `orion-application.xml` file.

See Also: "Configuring J2EE Authorization"

## Creating Realms

It is important to use the appropriate tool to create realms. In general, if you use the LDAP-based provider or Oracle Application Server Single Sign-On, use Oracle Delegated Administration Services to create realms. If you use the XML-based provider, create realms with the JAAS Admintool. The realms you create with the JAAS Admintool are external or application realms; they are located in a different place in the realm tree than identity management realms.

## Removing Realm Names from Principals

In some applications, you prefer to avoid parsing the principal returned by various method calls. You can configure the OracleAS JAAS Provider so that the returned principal contains no realm name. To do this, you add the property `jaas.username.simple` to the `<jazn>` element in the instance-level `ORACLE_HOME``/j2ee/``instance_name``/config/jazn.xml` file, such as in the following example:

    <property name="jaas.username.simple" value="true" />

This property affects the return values of the following methods:

- In `javax.servlet.http.HTTPServletRequest`, the `getRemoteUser()` and `getUserPrincipal()` methods

- In `javax.ejb.EJBContext`, the `getCallerIdentity()` and `getCallerPrincipal()` methods

## Specifying the JAAS Provider

Consider an exception and stack trace similar to the following:

    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

In this circumstance, you have probably failed to specify the OracleAS JAAS Provider as the JAAS policy provider, as discussed in "Specifying an Alternate Policy Provider (Optional)".