Skip Headers

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

Previous | Next |

# 4 Overall Security Configuration

This chapter discusses tasks related to configuring the complete security system. It contains the following parts:

- Choosing the XML-Based or LDAP-Based Provider

- Locating jazn.xml, jazn-data.xml, and the <jazn> Element

- Admintool Overview

- Specifying an Alternate Policy Provider (Optional)

- Specifying OracleAS JAAS Provider Settings

- Enabling Debug Logging

- Specifying User Managers

- Customizing RealmLoginModule

- Specifying Authentication (auth-method)

- Configuring J2EE Authorization

- Removing Realm Names from Authentication Principals

- Configuring Third-Party LDAP Providers

- Permitting EJB RMI Client Access

- Creating a Java 2 Policy File

- Using the <principals> Element and principals.xml

## Choosing the XML-Based or LDAP-Based Provider

As part of installing OC4J, you determine whether to use the LDAP-based or XML-based provider. This section gives guidelines on how to make that choice.

- XML-based provider: Use the XML-based provider in development environments and in deployed applications with a small user population.

- LDAP-based provider: Use the LDAP-based provider in production environments.

  Compared to the XML-based provider, the LDAP-based provider offers better security and performance. The centralized Oracle Internet Directory server scales gracefully as the number of applications and users grows. We recommend you take advantage of a centralized Oracle Internet Directory server in your production deployments, both for better performance and to take advantage of such features as centralized account creation and management, single passwords, and credential management.

  The LDAP-based provider enables you to configure cache parameters to improve overall performance of authentication and authorization. If secure communications are needed between the Oracle Internet Directory server and OC4J, configure the system to use the level of security required.

When you install infrastructure, then associate the OC4J instance with a mid-tier Oracle Internet Directory or Oracle Application Server Single Sign-On instance, the installer automatically selects the LDAP-based provider. For details, see the Oracle Application Server Installation Guide . If you need to configure OC4J to use the LDAP-based provider, see the instructions in the Oracle Application Server Administrator's Guide.

## Locating jazn.xml, jazn-data.xml, and the <jazn> Element

To configure the OracleAS JAAS Provider, you must sometimes edit various configuration files using text editors. This section discusses how to locate the configuration files and the `<jazn>` element.

### Loc ating jazn.xml

The OracleAS JAAS Provider must locate a valid `jazn.xml` file before it can begin running. The `jazn.xml` file is used to configure the OracleAS JAAS Provider.

The `jazn.xml` file for the OC4J `home` instance, sometimes referred to as the bootstrap jazn.xml file, is in the `ORACLE_HOME``/j2ee/home/config` directory by default. The OracleAS JAAS Provider reads the information in this file before OC4J is started up, and certain settings can be made only in the bootstrap file. If changes are read after OC4J starts up, they have no effect on the OracleAS JAAS Provider.

There is also a `jazn.xml` file for each additional OC4J instance, in the `ORACLE_HOME``/j2ee/``instance_name``/config` directory.

See Also: "Alternative jazn.xml Locations"

### Locati ng jazn-data.xml

The file `jazn-data.xml` is the datastore for the XML-based JAAS provider. By default, for each OC4J instance, OC4J expects the file `jazn-data.xml` to be in the `ORACLE_HOME``/j2ee/``instance_name``/config` directory. There is also a `jazn-data.xml` file for the OC4J `home` instance, sometimes referred to as the bootstrap jazn-data.xml file, in the `ORACLE_HOME``/j2ee/home/config` directory.

You can also specify an alternate path for `jazn-data.xml` in the `<jazn>` element in `jazn.xml`, as follows:

    <jazn provider="xml" location="pathname">
       ...
    </jazn>

### Locating the <jazn> Element

The `<jazn>` element is used to configure the OracleAS JAAS Provider. Most often, the `<jazn>` element appears in one of two places:

1. The global `application.xml`, for global configuration

2. The application-specific `orion-application.xml`

The `<jazn>` element may also appear in the `jazn.xml` file when it is used to configure virtual machine properties. For details, see "Instance-Level jazn.xml File".

## Admintool Overview

This section discusses basic information needed to understand and use the JAZN Admintool. The JAZN Admintool is a lightweight tool used to manage user accounts stored in `jazn-data.xml`. To manage accounts in the LDAP-based provider, use the tools provided in the Oracle Delegated Administration Services.

Note: Changes made by the Admintool are not effective until the next OC4J restart.

### Admintool Prerequisites

When you use the JAZN Admintool, by default it edits the file `jazn-data.xml` under the `config` directory of the OC4J home instance. For details on locating `jazn-data.xml`, see "Locating jazn-data.xml". The password for the `admin` user is set during installation time to the same value as the Oracle Application Server administrator (`ias_admin`) password.

Before using the Admintool with the LDAP-based provider, be sure to set the correct environment settings as described in "Preparing to Use LDAP".

### Authenticating Yourself

If you are using the XML-based provider, you must authenticate yourself to the JAZN Admintool before making administrative changes. You authenticate by supplying a user name and password when prompted by the Admintool, as in:

    java -jar jazn.jar -listrealms
    >RealmLoginModule username: martha
    >RealmLoginModule password: mypass

Cautions: The Admintool does not require authentication when used with the LDAP-based provider; anyone who runs the tool can perform Admintool operations against the Oracle Internet Directory server. This means that it is vital to secure access to the production machine(s) on which OC4J uses the LDAP-based provider. If you specify the `-user` and `-password` options when using the LDAP-based provider, they are ignored. Although it is possible to supply the user name and password on the command line with `-user` and `-password` , we recommend that you avoid this; specifying passwords on command lines creates security vulnerabilities.

### Adding Clustering Support

    -clustersupport oracle_home

Specifying this option instructs the Admintool to propagate all JAAS configuration changes throughout a cluster. The `oracle_home` argument specifies the absolute path name of `ORACLE_HOME`, the Oracle home directory. You can combine `-clustersupport` with the `-shell` option.

Notes: In using the `-clustersupport` option, you must specify it before all other options on the command line. The `-clustersupport` option is meaningful only when using the XML-based provider.

For example:

    java -jar jazn.jar -clustersupport /oracle_home -shell

### Specifying an Admintool Login Module in jazn-data.xml

To specify which `LoginModule` the JAZN Admintool uses to authenticate its users, you must add a `<login-modules>` element to the `<application>` element in `jazn-data.xml`. For example:

    <application>
      <name>oracle.security.jazn.tools.Admintool</name>
      <login-modules>
        <login-module>
         <class>oracle.security.jazn.realm.RealmLoginModule</class>
          <control-flag>required</control-flag>
          <options>
             <option>
                <name>debug</name>
                <value>false</value>
             </option>
             <option>
                <name>addAllRoles</name>
                <value>true</value>
             </option>
          </options>
        </login-module>
      </login-modules>
    </application>

If you try to run the JAZN Admintool without specifying a `LoginModule`, the `RealmLoginModule` with the default options is used. The default options are shown in Table 4-2, "RealmLoginModule Options".

## Specifying an Alternate Policy Provider (Optional)

If you use the Java Virtual Machine shipped with Oracle Application Server, the OracleAS JAAS Provider is automatically specified as the JAAS policy provider. If you use another JVM, you must explicitly specify `oracle.security.jazn.spi.PolicyProvider` as the policy provider, because by default, the JVM uses the Sun JAAS provider.

Note: When you use OC4J, the JAAS configuration properties are set by default during OC4J startup, so in most circumstances you do not need to worry about setting these properties. You set them only when you are running a J2SE application outside OC4J.

You can specifying Oracle-specific JAAS properties in a separate file and passing them to the JVM on the command line. Oracle supplies a default file (`ORACLE_HOME``/j2ee/home/config/jazn.security.props`) that specifies the OracleAS JAAS provider.

- To replace all security properties with the Oracle properties:

      java -Djava.security.properties==propfile

- To append the Oracle-specific properties to the other properties:

      java -Djava.security.properties=propfile

## Specifying OracleAS JAAS Provider Settings

The `home` instance `jazn.xml` file is in the `ORACLE_HOME``/j2ee/home/config` directory. The OracleAS JAAS Provider reads the information in this file before OC4J is started up, and certain settings can be made only in this file. If changes are read after OC4J starts up, they have no effect on the OracleAS JAAS Provider. These properties are discussed in detail in Chapter 5, "Configuring the OC4J Instance".

## Enabling Debug Logging

To enable OracleAS JAAS Provider debug logging, set the system property `jazn.debug.log.enable` to `true` during Java Virtual Machine (JVM) startup.

You do this by modifying the JVM startup settings for your OC4J instance. In Oracle Application Server, you normally manage JVM settings with Oracle Enterprise Manager, using the Java Options textbox on the Server Properties page.

In standalone mode, you set this property using JVM command-line options. For example, you might start OC4J standalone with a command line such as:

    java -Djazn.debug.log.enable=true -jar oc4j.jar

Or you can start the Admintool shell in debug mode with the command:

    java -Djazn.debug.log.enable=true -jar jazn.jar -shell

In Oracle Application Server, the debug output is captured by OPMN and written to log files associated with each OC4J instance in the `ORACLE_HOME``/opmn/logs` directory.

## Specifying User Managers

The user manager, employing the user name and password, verifies the user's identity using information in the user repository. The user manager contains your definitions for users, groups, or roles. The default user manager is the `JAZNUserManager`.

You can define a user manager for all applications or for specific applications.

- Global user manager: The global (default) user manager is inherited by all applications within an instance that has not defined a specific user manager. The instance `UserManager` is defined in the `application.xml` file.

- Specific user manager: This user manager is defined in `orion_application.xml` solely for a single application. It is not used by any other application.

  Note: Within a single OC4J instance you can specify different values for the application-specific `UserManager` instance and the global `UserManager` instance. When you do this, we recommend that you not mix custom `UserManager` instances and Oracle-supplied `UserManager` instances. You can use different custom `UserManager` instances for the application and the global instance, and you can use different Oracle-supplied `UserManager` instances for the application and the global instance, but you should avoid using a custom `UserManager` for the one instance and an Oracle-supplied `UserManager` for the other.

- In some cases, if an application inherits from another application instead of inheriting from the global application, then the parent user manager of the application will be the global `UserManager` instance instead of the `UserManager` instance specified in the parent application.

### Specifying a User Manager

To specify a `UserManager` for an entire OC4J instance or for a specific application within that instance, use Enterprise Manager. For details, see the Enterprise Manager help topic "Modifying the User Manager for All Applications".

### Specifying a User Manager in orion-application.xml

Every application, including the top-level default application, has an associated `UserManager`. The primary function of the `UserManager` is to authenticate users who attempt to access Web pages and EJBs.

Note: We strongly encourage you to use `JAZNUserManager`. User-defined user managers will stop being supported in a future release.

The `UserManager` is used to authenticate users when connections are made to the application. These are specified using subelements within an `<orion-application>` element that define the configuration. There are three elements that can be used to specify a `UserManager`, as shown in Table 4-1.

Table 4-1 UserManager Elements

Tag | Meaning
--- | ---
`<user-manager>` | A user manager implemented by a user-defined class
`<jazn>` | `JAZNUserManager`
`<principals>` | A user manager defined in a `principals.xml` file See "Using the <principals> Element and principals.xml" .

#### Advanced Configuration

There may be more than one of the user-manager configuration within a single `<orion-application>` element. Which element determines the `UserManager` is determined by the order the elements appear in the table: `<user-manager>` takes precedence over `<jazn>`, which takes precedence over `<principals>`. For example, if both a `<jazn>` element and a `<principals>` element are present, the `UserManager` is based on the `<jazn>` element. If multiple elements with the highest-priority element are present, then the `UserManager` instances are chained together as parents. That is, the `UserManager` specified in the first element becomes the parent of the `UserManager` specified in the second, and so on. The last `UserManager` specified then becomes the `UserManager` of the application. The parent of the first `UserManager` is the `UserManager` associated with the parent application (if any) of the application. The default application does not have a parent application and the parent of its `UserManager` is null.

If no user manager is specified, then the `UserManager` is determined according to the following rules.

- For the default application, a JAAS `UserManager` is created based on `jazn-data.xml` in the directory containing the `application.xml` file. If no `jazn-data.xml` is present in that directory, one is created. The default realm of the created `jazn-data.xml` file is `jazn.com`.

- At deployment time, if the `UserManager` of the parent application is the JAAS `UserManager`, then a JAAS `UserManager` is created based on `jazn-data.xml`. If necessary, a `jazn-data.xml` file is created in the same way as in the previous bullet. A `<jazn>` element is written into the `orion-application.xml` file associated with the application.

- At application deployment time, if the `UserManager` of the parent application is based on `principals.xml`, then the `UserManager` of the application will be a principals `UserManager`. If a `principals.xml` file is not present, then an empty file is created. A `<jazn>` element is written into the `orion-application.xml` associated with the application.

- If the `UserManager` of the parent application is user-written, then the `UserManager` of the parent will become the `UserManager` of the application.

## Customizing RealmLoginModule

The `RealmLoginModule` class is the default `LoginModule` that is configured through the `jazn-data.xml` file. The `RealmLoginModule` class authenticates user login credentials before the user can access J2EE applications. Authentication is performed using OC4J container-based authentication (HTTP `BASIC`, `FORM`, and so on). You do not need to enable the `RealmLoginModule` class if your application uses OracleAS Single Sign-On authentication.

See Also: Oracle Application Server Installation Guide for OracleAS Single Sign-On configuration tasks

You can configure `RealmLoginModule` either using the JAZN Admintool or by editing `jazn-data.xml`. For details on using the Admintool, see "Adding and Removing Login Modules" .

The `<login-module>` element supports the following `<option>` values:

Table 4-2 RealmLoginModule Options

Name | Meaning | Default
--- | --- | ---
`debug` | If set to `true`, prints debugging messages. | `false`
`addRoles` | If set to `true`, the `RealmLoginModule` adds all directly granted roles of the user to the subject after successful authentication. | `true`
`addAllRoles` | If set to `true`, the `RealmLoginModule` adds all directly or indirectly granted roles of the user to the subject after successful authentication. | `true`
`storePrivateCredentials` | If set to `true`, the `RealmLoginModule` adds all private credentials (for example, password credentials) to the subject after successful authentication. | `false`
`supportCSIv2` | If set to `true`, the `RealmLoginModule` supports CSIv2. See Chapter 15, "Configuring CSIv2" for details. | `false`
`supportNullPassword` | (LDAP-based provider only.) If set to `true`, the `RealmLoginModule` does not check to see if the supplied password is null or empty. If set to `false`, authentication fails if the supplied password is null or empty. | `false`

### Enabling RealmLoginModule Using a Text Editor

Use a text editor to modify the login configuration file `jazn-data.xml` where needed.

The default configuration for the `RealmLoginModule` class setting in the `jazn-data.xml` file is as follows:

    <!DOCTYPE jazn-data (View Source for full doctype...)>
    <jazn-data>
        ...
    <!--  Login Module Data -->
     <jazn-loginconfig>
       <application>
         <name>oracle.security.jazn.oc4j.JAZNUserManager</name>
         <login-modules>
           <login-module>
              <class>oracle.security.jazn.realm.RealmLoginModule</class>
              <control-flag>required</control-flag>
              <options>
                 <option>
                   <name>addRoles</name>
                   <value>true</value>
                 </option>
             </options>
           </login-module>
         </login-modules>
       </application>
      </jazn-loginconfig>
    </jazn-data>

See Also: OracleAS JAAS Provider Javadoc: JAAS Provider API Reference "Adding and Removing Login Modules"

## Specifying Authentication (auth-method)

You specify the authentication method (`auth-method`) in one of several configuration files, using either the `<jazn-web-app>` or `<login-config>` elements. You must edit the configuration files by hand.

### Specifying auth-method in web.xml

To specify the authentication method at the Web module level, use the `<login-config>` element of `web.xml`. For example:

    <web-app>
       ...
       <login-config>
          <auth-method>BASIC</auth-method>
       </login-config>
       ...
    </web-app>

In `web.xml`, the `<auth-method>` element can have the values shown in Table 4-3. Note that these values can be overridden at the application level by using an attribute of the `<jazn-web-app>` element in `orion-application.xml`.

Table 4-3 Values for auth-method in web.xml

Setting | Meaning
--- | ---
`BASIC` (default) | The application uses basic authentication, the standard authentication. Note: Also use the `BASIC` setting if you want to use Oracle SSO or digest features, where the `web.xml` setting is overridden in a `<jazn-web-app>` setting. See "Specifying auth-method in orion-application.xml" immediately below. (This is how Oracle implements the optional digest mechanism, for the XML-based provider only, in the OC4J 10.1.2 implementation.)
`FORM` | The application uses form-based authentication.
`CLIENT-CERT` | The application requires the client to supply its own certificate for use with SSL.

### Specifying auth-method in orion-application.xml

An `auth-method` attribute setting supplied in a `<jazn-web-app>` element overrides the `auth-method` setting in `web.xml`. The OC4J 10.1.2 implementation supports `SSO` or `DIGEST` settings in `<jazn-web-app>`.

#### Specifying auth-method SSO

The setting `auth-method="SSO"` in the `<jazn-web-app>` element of the `orion-application.xml` file specifies that the application uses OracleAS Single Sign-On. If your installation includes LDAP, then Oracle Enterprise Manager automatically sets`auth-method="SSO"`. If you stop using OracleAS Single Sign-On, you must edit the file to remove this method.

To use the SSO authentication mechanism, use the `auth-method` setting `BASIC` in `web.xml`, as follows:

    <web-app>
       ...
       <login-config>
          <auth-method>BASIC</auth-method>
       </login-config>
       ...
    </web-app>

Then override it with settings in `orion-application.xml` such as the following:

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

#### Specifying auth-method Digest

To use the digest authentication mechanism, use the `auth-method` setting `BASIC` in `web.xml`, as follows:

    <web-app>
       ...
       <login-config>
          <auth-method>BASIC</auth-method>
       </login-config>
       ...
    </web-app>

Then override this with the setting `auth-method="DIGEST"` in the `orion-application.xml` file, as follows:

    <jazn>
       ...
       <jazn-web-app auth-method="DIGEST" />
       ...
    </jazn>

Important: Be aware of the following: In the OC4J 10.1.2 implementation, the digest mechanism is supported only for the JAZN XML-based provider. Older Web browsers may not support the digest mechanism. The OC4J digest feature is unrelated to the Oracle HTTP Server `mod_digest` feature.

## Configuring J2EE Authorization

J2EE defines a declarative authorization model that decouples applications from the underlying security infrastructure. This model allows the authorization policy of an application to be expressed in a portable manner in the application deployment descriptors. This model has proven to be hugely successful and suffices for most application needs.

In some advanced scenarios, however, the J2EE authorization model may seem too static and coarse-grained. In these cases, the JAAS authorization model can be used instead of (or in addition to) the J2EE security model. When compared to the J2EE authorization model, the JAAS authorization model is more powerful (fine-grained and dynamic) and more flexible (custom permission types supported). Such power and flexibility come at a cost, however, the JAAS authorization model is more complex to understand, deploy and administer than the J2EE authorization model.

Both models are fully supported in OC4J.

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

In most cases, URL authorization is sufficient for an application. However, if your application requires granular authorization, this extended authorization can be used to enforce JAAS Policy-based authorization at the method level.

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 contained in a `<jazn>` element in either the `orion-web.xml` or `orion-application.xml` file. To do this, you open the appropriate file in a text editor.

- The `subject.doAs()` method invokes the servlet using the privileges of a particular subject. A subject is defined by an instance of the `javax.security.auth.Subject` class and includes a set of facts regarding a single entity, such as a person. Such facts include identities and security-related attributes, such as passwords and cryptographic keys. The OracleAS JAAS Provider passes in the `Subject` instance in the method call.

  When the `doAs()` method is used, an `AccessControlContext` instance is retrieved from the current thread (from the server).

- The `subject.doAsPrivileged()` method uses the privileges of a particular subject without being limited by the access-control restrictions of the server.

  When the `doAsPrivileged()` method is used, the OracleAS JAAS Provider invokes the method with a null `java.security.AccessControlContext` instance, in order to start the action fresh and execute the servlet without the restrictions of the current server `AccessControlContext` instance.

The `runas-mode` and `doasprivileged-mode` attributes control whether the servlet is invoked with the `subject.doAsPrivileged()` method or the `subject.doAs()` method. By default, `runas-mode` is set to `false`, which means that neither `subject.doAsPrivileged()` nor `subject.doAs()` is invoked.

Note: The `runas-mode` attribute is unrelated to the `servlet.runAs()` method.

Table 4-4 Settings for runas-mode and doasprivileged-mode

If runas-mode is Set To | And doasprivileged-mode Is Set To | Then the servlet is invoked with:
--- | --- | ---
`false` (default) | `true` or `false` | No special privileges
`true` | `true` (default) | `subject.doAsPrivileged()`
`true` | `false` | `subject.doAs()`

Thus, to have your servlet invoked using `subject.doAsPrivileged()`, you should have a `<jazn-web-app>` element that looks like this:

    <jazn-web-app
        auth-method="SSO"
        runas-mode="true"
        doasprivileged-mode="true" />

### Mapping Logical Roles to Security Roles

You sometimes deploy a servlet into a container that uses different role names than expected by the servlet. You do this by mapping the logical role (the role name used by the servlet) to the security role (the role name used by the container) in the `web.xml` file.

For example, the following entity maps the security role `corpmanagers` to the logical role `mgmt`:

    <security-role-ref>
      <role-name>mgmt</role-name>
      <role-link>corpmanagers</role-link>
    </security-role-ref>

In this example, if a servlet running as a user belonging to `corpmanagers` invokes `isUserInRole("mgmt")`, the method will return `true`. Whenever the container finds no `security-role-ref` matching a security role, the container checks the `<role-name>` against the entire list of security roles for the Web application.

## Removing Realm Names from Authentication Principals

It is often desirable to avoid parsing the principal returned by various method calls. You can configure OracleAS JAAS Provider so that the returned principal contains no realm name. To do this, you add a `jaas.username.simple` property to the `<jazn>` element in the instance-level `jazn.xml` file, `ORACLE_HOME``/j2ee/``instance_name``/config/jazn.xml`. If this property is set to `true`, returned principals contain no realm name; if it is set to `false`, the default, returned principals contain the complete realm name.

The `jaas.username.simple` property affects only the specified OC4J instance. Setting this property in `orion-application.xml` has no effect.

This property affects the return values of the following methods:

- `javax.servlet.http.HTTPServletRequest`: `getRemoteUser()` and `getUserPrincipal()` methods

- `javax.ejb.EJBContext`: `getCallerIdentity()` and `getCallerPrincipal()` methods

By default, the principal returned by these methods is in the format `realm_name``/``simple_name`, such as `jazn.com/john`. When you set `jaas.username.simple` to `true`, the returned principal is in the format `simple_name`, such as `john`.

You set `jaas.username.simple` as follows:

1. Locate the instance-level `jazn.xml` file, `ORACLE_HOME``/j2ee/``instance_name``/config/jazn.xml`. Open the file in a text editor, and go to the `<jazn>` element within the file.

2. Search for a `<property>` subelement with `name="jaas.username.simple"` within the `<jazn>` element.

3. If the subelement exists, change `value` to `true` or `false`; if the subelement does not exist, create one. In either case, you should have a subelement that looks like this:

       <jazn provider="XML" location="./jazn-data.xml">
          <property name="jaas.username.simple" value="true" />
       </jazn>

   Note: Do not edit any `<jazn>` properties except as specified in this chapter.

## Configuring Third-Party LDAP Providers

See Chapter 9, "Configuring External LDAP Providers".

## Permitting EJB RMI Client Access

To enable fat client access to EJBs using RMI, you must grant the correct permissions using the JAZN Admintool. (For general information on using the Admintool, see "Admintool Overview" .) You must grant `RMIPermission` of `login` to your user, role, or group.

    java -jar jazn.jar -grantperm myrealm -role administrators \
      oracle.j2ee.server.rmi.RMIPermission login

## Creating a Java 2 Policy File

The Java 2 policy file grants permissions to trusted code or applications that you run. This enables code or applications to access Oracle support for JAAS or JDK APIs requiring specific access privileges.

A preconfigured Java 2 policy (`java2.policy`) is provided in `ORACLE_HOME``/j2ee/home/config`.

You need to modify the Java 2 policy file to grant permissions to trusted code or applications.

For example, the following section of a `java2.policy` file grants `java.security.AllPermission` to the trusted `jazn.jar`.

    /* grant the JAZN library AllPermission */
    grant codebase "file:${oracle.home}/j2ee/home/jazn.jar" {
        permission java.security.AllPermission;
    };

The following example grants specific permissions to all applications running in the `ORACLE_HOME``/appdemo` directory.

    /* Assuming you are running your application demo in $ORACLE_HOME/appdemo/, */
    /* Grant JAZN permissions to the demo to run JAZN APIs*/
    grant codebase "file:/${oracle.ons.oraclehome}/appdemo/-" {
       permission oracle.security.jazn.JAZNPermission "getPolicy";
       permission oracle.security.jazn.JAZNPermission "getRealmManager";
       permission oracle.security.jazn.policy.AdminPermission
         "oracle.security.jazn.realm.RealmPermission$*$createRealm,dropRealm,
         createRole, dropRole,modifyRealmMetaData";

## Using the <principals> Element and principals.xml

The `<principals>` element tells OC4J to use the `UserManager` described in a principals file, normally `principals.xml`. A `<principals>` element has one attribute,`<path>`, which specifies a path for the principals file, normally `principals.xml`.

For example:

    <principals path="myprincipals.xml" />

A `principals.xml` file also contains a `<principals>` element; this contains two subelements, `<groups>` and `<users>`. The `<groups>` element contains one or more `<group>` elements, and the `<users>` element contains one or more `<user>` elements.

Note: The `XMLUserManager` class is deprecated, and is supported for backward compatibility only. Oracle will cease to support `XMLUserManager` and `principals.xml` in a future release.

Table 4-5 Elements in principals.xml

Element | Can Contain | Attributes | Description
--- | --- | --- | ---
`<principals>` | `<groups>, <users>` | `NA` | The top-level element for principals.
`<groups>` | `<group>` |  | A list of groups known to this user manager.
`<group>` | `<description>, <permission>` | `name` | Identifies a single user group; `name` attribute specifies group name.
`<description>` |  |  | Not used by OracleAS JAAS Provider, but displayed in some circumstances.
`<permission>` |  | `name` | A `java.security.Permission` that is granted to principals. There are two special values: `administrator`, equivalent to `oracle.j2ee.security. AdministrationPermission()` `rmi:login`, equivalent to `oracle.j2ee.server.rm. RMIPermission("login")`
`<users>` | `<user>` |  | List of users known to the `UserManager`.
`<user>` | `<description>`, `<group-membership>` | `username`, `password`, `deactivated` | The `username` is a string to identify the user. The `password` is a cleartext password to authenticate the user. There is no mechanism for obfuscating this password. The `deactivated` attribute is either `true` or `false`. If `true`, then this user will not be found in lookups and cannot be authenticated.
`<group-membership>` |  | `group` | Name attribute of a group that contains this user.

Groups in `principals.xml` correspond to roles in the OracleAS JAAS Provider. The `principals.xml` file does not support any equivalent of the OracleAS JAAS Provider concept of realms. Permissions granted to groups may be checked explicitly, and OC4J does check for the special permissions listed above. However, group permissions are not integrated with the usual `Permission` checking performed by a `SecurityManager`.

The following is a sample `principals.xml` file.

    <?xml version="1.0" standalone='yes'?>
    <!DOCTYPE principals PUBLIC "//Evermind - Orion Principals//"
     "http://xmlns.oracle.com/ias/dtds/principals.dtd">

    <principals>
      <groups>
    <group name="guests">
        <description>users</description>
      </group>
      <group name="administrators">
        <description>administrators</description>
        <permission name="administration" />
      </group>
      </groups>
      <users>
      <user username="SCOTT" password="TIGER">
      <group-membership group="guests" />
      </user>
      <user username="anonymous" password="">
        <description>The default guest/anonymous user</description>
        <group-membership group="guests" />
      </user>
      <user username="admin" password=""  deactivated="true">
        <description>The default administrator</description>
        <group-membership group="users" />
        <group-membership group="administrators" />
      </user>
      </users>
    </principals>