Skip Headers

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

Previous | Next |

# 2 Overview of JAAS in Oracle Application Server

This chapter further discusses the Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider, first mentioned in the preceding chapter, in OC4J. The OracleAS JAAS Provider enables application developers to integrate authentication, authorization, and delegation services with their applications.

This chapter contains these topics:

- The OracleAS JAAS Provider

- What Is JAAS?

- JAAS Framework Features

- User Managers

- Capability Model of Access Control

- Role-Based Access Control (RBAC)

- Changes Since Release 9.0.4

## The OracleAS JAAS Provider

The Oracle Application Server supports JAAS with the OracleAS JAAS Provider. The OracleAS JAAS Provider implements user authentication, authorization, and delegation services that developers can integrate into their application environments. Instead of devoting resources to developing these services, application developers can focus on the presentation and business logic of their applications.

Note: Some class and component names contain the word "JAZN", which is a shortened name for the OracleAS JAAS Provider.

The JAAS framework and the Java 2 Security model form the foundation of JAAS. The OracleAS JAAS Provider implements support for JAAS policies. Policies contain the rules (permissions) that authorize a user to use resources, such as reading a file. Using JAAS, services can authenticate and enforce access control upon resource users. The OracleAS JAAS Provider is easily integrated with J2SE and J2EE applications that use the Java 2 Security model.

### Provider Types

The OC4J JAAS implementation supports two different provider types. Each provider type implements a repository for secure, centralized storage, retrieval, and administration of provider data. This data consists of realm (users and roles) and JAAS policy (permissions) information.

- XML-based provider

  The XML-based provider is used for lightweight storage of information in XML files. The XML-based provider stores user, realm, and policy information in an XML file, normally `jazn-data.xml.`

  Note: XML files are used as property and configuration files by both LDAP-based and XML-based provider types. However, only the XML-based provider stores users, realms, and policies in an XML file, `jazn-data.xml`.

- LDAP-based provider

  The LDAP-based provider is based on the Lightweight Directory Access Protocol (LDAP) for centralized storage of information in a directory. The LDAP-based provider stores user, realm, and policy information in the LDAP-based Oracle Internet Directory.

  Note: We recommend that you use the LDAP-based provider in a production environment; the XML-based provider is suitable for prototyping only.

## What Is JAAS?

JAAS is a Java package that enables applications to authenticate and enforce access controls upon users. The OracleAS JAAS Provider is an implementation of the JAAS interface.

JAAS is designed to complement the existing code-based Java 2 security. JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework. This enables an application to remain independent from the authentication service.

JAAS extends the access control architecture of the Java 2 Security Model to support principal-based authorization.

This section describes JAAS support for the following authentication, authorization, and user community (realm) features. The OracleAS JAAS Provider enhances some of these features.

- Login Module Authentication

- Roles

- Realms

- Applications

- Policies and Permissions

  See Also: "JAAS Framework Features" for information on how the OracleAS JAAS Provider enhances the JAAS framework to explicitly define key authorization, authentication, and user community (realm) features JAAS documentation at the following Web site for more specific discussions of key JAAS features: `http://java.sun.com/products/jaas/`

### Login Module Authentication

To associate a principal (such as `frank`) with a subject, a client attempts to log in to an application. In login module authentication, the `LoginContext` class provides the basic methods used to authenticate subjects such as users, roles, or computing services. The `LoginContext` class consults configuration settings to determine whether the authentication modules (known as login modules) are configured for use with the particular application that the subject is attempting to access. Different login modules can be configured with different applications; furthermore, a single application can use multiple login modules.

Because the `LoginContext` separates the application code from the authentication services, you can plug a different login module into an application without affecting the application code.

Actual authentication is performed by the `LoginContext.login()` method. If authentication succeeds, then the authenticated subject can be retrieved by invoking the `LoginContext.getSubject()` method. The real authentication process can involve multiple login modules. The JAAS framework defines a two-phase authentication process to coordinate the login modules configured for an application.

After retrieving the subject from the `LoginContext`, the application then performs work as the subject by invoking the `Subject.doAs()` or `Subject.doAsPrivileged()` method.

### Roles

The JAAS framework does not explicitly define roles or groups. Instead, roles or groups are implemented as concrete classes that use the `java.security.Principal` interface.

The JAAS framework does not define how to support the role-based access control (RBAC) role hierarchy, in which you can grant a role to a role.

### Realms

The JAAS framework does not explicitly define user communities. However, the J2EE reference implementation (RI) defines a similar concept of user communities called realms. A realm provides access to users and roles (groups) and optionally provides administrative functionality. A user community instance is essentially a realm that is maintained internally by the authorization system. The J2EE RI Realm API supports user-defined realms through subclassing.

### Applications

The JAAS framework does not explicitly define an application or subsystem for partitioning authorization rules.

### Policies and Permissions

A policy is a repository of JAAS authorization rules. The policy includes grants of permissions to principals, thus answering the question: "Given a grantee, what are the granted permissions of the grantee?"

Policy information is supplied by the OracleAS JAAS Provider. The JAAS framework does not define an administrative API for policy administration. The administrative API provided by the OracleAS JAAS Provider is an Oracle extension.

Table 2-1 describes the Sun Microsystems implementation of policy file parameters.

Table 2-1 Policy File Parameters

Parameter | Defined As | Example
--- | --- | ---
Subject | One or more principal(s) | duke
Codesource | `codebase``,` `signer` | `http://www.example.com, mysigner`

#### XML-Based Example

The JAAS XML-based provider can store policy data in the file `jazn-data.xml`. In the following example, a segment of the `jazn-data.xml` file grants the `admin` principal permission to log in.``

    <jazn-policy>
      <grant>
       <grantee>
         <principals>
          <principal>
            <class>oracle.security.jazn.samples.SampleUser</class>
            <name>admin</name>
          </principal>
        </principals>
       </grantee>
       <permissions>
         <permission>
           <class>oracle.j2ee.server.rmi.RMIPermission</class>
           <name>login</name>
         </permission>
       </permissions>
      </grant>
    </jazn-policy>

See Also: "Sample: jazn-data.xml Configuration" to view a complete `jazn-data.xml` file

## JAAS Framework Features

Table 2-2 contains the JAAS framework features implemented by the OracleAS JAAS Provider.

Table 2-2 OracleAS JAAS Provider Features

Feature | Description | See Also
--- | --- | ---
Authentication | Integrates with Oracle Application Server Single Sign-On for login authentication in J2EE application environments. Supplies an out-of-the-box `RealmLoginModule` class for non-OracleAS Single Sign-On environments, such as OracleAS Core or Java Edition. Supports any JAAS-compliant custom `LoginModule`. | Chapter 3, "Understanding OC4J Security"
Declarative Model | Integrates J2EE deployment descriptors, such as. `web.xml`, with JAAS security. Supports programmatic model as well. | Chapter 4, "Overall Security Configuration"
Authorization | Provides centralized role-based access control, including support for hierarchical roles. | "Role-Based Access Control (RBAC)"
Realms | Organizes users and roles (groups) around user communities. An Oracle API package (`oracle.security.jazn.realm`) is provided to support user and role management. This API includes a `RealmPrincipal` interface that extends from `java.security.Principal` and associates a realm with users and roles. | "Realms"
Management | Manages settings and data using command-line tool (Admintool) or Oracle Enterprise Manager 10g. Supports a centrally managed provider type with Oracle Internet Directory. |
`JAZNUserManager` | Provides an implementation of the OC4J `UserManager` that integrates with both the XML-based and the LDAP-based providers. | "JAZNUserManager"

## User Managers

OC4J security employs a user manager to authenticate and authorize users and groups that attempt to access a J2EE application. You base your choice of user manager on performance and security needs.

All `UserManager` classes implement the `com.evermind.security.UserManager` interface. `UserManager` classes manage users, groups, and passwords through methods such as `createUser()`, `getUser()`, and `getGroup()`.

See Also: OracleAS JAAS Provider Javadoc for further information: JAAS Provider API Reference

OC4J provides two predefined user managers, `JAZNUserManager` and `XMLUserManager`. `JAZNUserManager` supports both XML-based and LDAP-based providers. We recommend using `JAZNUserManager` because it is based on the JAAS specification and is integrated with Oracle Application Server Single Sign-On and Oracle Internet Directory. `JAZNUserManager` is the default security provider, because it offers powerful and flexible security control. Customers can also supply their own classes that implement the `UserManager` interface, although this will be deprecated at a future release.

See Also: For a discussion of creating a custom `UserManager`: `http://www.oracle.com/technology/sample_code/tech/xml/xmlnews/News_Security.html`.

Table 2-3 lists the user managers provided by OC4J.

Table 2-3 OC4J User Managers and Repositories

User Manager Class | User Repository
--- | ---
`oracle.security.jazn.oc4j.JAZNUserManager` | Several types: Using the XML-based provider, `jazn-data.xml` Using the LDAP-based provider, Oracle Internet Directory Using a third-party LDAP provider
`com.evermind.server.XMLUserManager` | The `principals.xml` file
Custom user manager | Customized user repository

See "Specifying a User Manager in orion-application.xml" for directions on how to define the default `UserManager` for all applications or a single `UserManager` for a specific application.

The following sections describe the JAZN and XML user managers:

- Using JAZNUserManager

- Using XMLUserManager

### Using JAZNUserManager

The `JAZNUserManager` class is the default user manager. The primary purpose of the `JAZNUserManager` class is to leverage the OracleAS JAAS Provider as the security infrastructure for OC4J.

There are two JAAS providers supplied with OC4J security: XML-based and LDAP-based.

- The XML-based provider is a fast, lightweight implementation of the JAAS Provider API. This provider type uses XML to store user names and encrypted passwords. The user repository is stored in the `jazn-data.xml` file, in a location specified in the `jazn.xml` file. For details, see Chapter 8, "Configuring the XML-Based Provider".

  Select JAZN-XML as the user manager in the Enterprise Manager. Configure its users, roles, and groups using the JAZN Admintool.

- The LDAP-based provider is scalable, secure, enterprise-ready, and integrated with OracleAS Single Sign-On. The LDAP-based provider is the only OracleAS JAAS Provider that supports OracleAS Single Sign-On.

  Select JAZN-LDAP as the user manager in the Enterprise Manager. Configure its users and groups using the Oracle Delegated Administration Services from Oracle Internet Directory. The user repository is an Oracle Internet Directory instance, which requires that the application server instance be associated with an infrastructure. If it the server is not associated with an Oracle Internet Directory instance, then the LDAP-based provider is not a security option.For information on configuring the LDAP-based provider, see Chapter 7, "Configuring the LDAP-Based Provider".

Figure 2-1 shows the two different JAAS providers supplied with OC4J.

Figure 2-1 OC4J Security Architecture under the JAZNUserManager Class

Description of "Figure 2-1 OC4J Security Architecture under the JAZNUserManager Class"

### Using XMLUserManager

The `XMLUserManager` class is a simple user manager that manages users, groups, and roles in an XML-based system. It stores user passwords in the clear, and therefore is not as secure as the `JAZNUserManager`. All `XMLUserManager` configuration information is stored in the `principals.xml` file, which is the user repository for the `XMLUserManager` class.

Note: The `XMLUserManager` class is supported for backward compatibility only, and will be desupported in a forthcoming release. Oracle strongly recommends that you use one of the OracleAS JAAS Provider types.

## Capability Model of Access Control

The capability model is a method for organizing authorization information. The OracleAS JAAS Provider is based on the Java 2 Security Model, which uses the capability model to control access to permissions. With the capability model, authorization is associated with the principal (a user named `frank` in the following example). Table 2-4 shows the permissions that user `frank` is authorized to use:

Table 2-4 User Permissions

User | File Permissions
--- | ---
`frank` | Read and write permissions on a file named `salaries.txt` in the `/home/user` directory

When user `frank` logs in and is successfully authenticated, the permissions described in Table 2-4 are retrieved from the OracleAS JAAS Provider (whether the LDAP- based Oracle Internet Directory or XML-based provider) and granted to user `frank`. User `frank` is then free to execute the actions permitted by these permissions.

## Role-Based Access Control (RBAC)

RBAC enables you to assign permissions to roles. You grant users permissions by making them members of appropriate roles. Support for RBAC is a key JAAS feature. This section describes the following RBAC features:

- Role Hierarchy

- Role Activation

### Role Hierarchy

RBAC simplifies the management problems created by direct assignment of permissions to users. Assigning permissions directly to multiple users is potentially a major management task. If multiple users no longer require access to a specific permission, you must individually remove that permission from each user.

Instead of directly assigning permissions to users, permissions are assigned to a role, and users are granted their permissions by being made members of that role. Multiple roles can be granted to a user. A role can also be granted to another role, thus forming a role hierarchy that provides administrators with a tool to model enterprise security policies. Figure 2-2 provides an example of role-based access control.

Figure 2-2 Role-Based Access Control

Description of "Figure 2-2 Role-Based Access Control"

When a user's responsibilities change (for example, through a promotion), the user's authorization information is easily updated by assigning a different role to the user instead of a massive update of access control lists containing entries for that individual user.

For example, if multiple users no longer require write permissions on a file named `salaries` in the `/home/user` directory, those privileges are removed from the `HR` role. All members of the `HR` role then have their permissions and privileges automatically updated.

### Role Activation

A user is typically granted multiple roles. However, not all roles are enabled by default. An application can selectively enable the required roles to accomplish a specific task in a user session with the `run-as` security identity and `Subject.doAS()` method. Selectively enabling roles upholds the principle of least privilege—the application is not enabling permissions or privileges unnecessary for the task. This limits the damage that can potentially result from an accident or error.

## Changes Since Release 9.0.4

- The correct setting for the environment variable controlling loading of dynamic libraries (for example, `LD_LIBRARY_PATH` in Solaris) is now `ORACLE_HOME``/lib32` instead of `ORACLE_HOME``/lib`). Table 2-5 shows the complete settings.

  Table 2-5 Dynamic Library Path Settings

  Operating System | Variable | Value
  --- | --- | ---
  Solaris | `LD_LIBRARY_PATH` `LD_LIBRARY_PATH_64` | `ORACLE_HOME``/lib32` `ORACLE_HOME``/lib`
  HP/UX | `SHLIB_PATH` `LD_LIBRARY_PATH` | `ORACLE_HOME``/lib32` `ORACLE_HOME``/lib`
  AIX 32-bit applications | `LIBPATH` `LD_LIBRARY_PATH` | `ORACLE_HOME``/lib32` Null
  AIX 64-bit applications | `LIBPATH` `LD_LIBRARY_PATH` | `ORACLE_HOME``/lib` Null
  Windows | Not applicable | Not applicable

- The Java Development Kit 1.3 default installation does not include JAAS support. To use JAAS with JDK1.3, you must download JAAS 1.0_01 from the Sun Web site `http://java.sun.com/products/jaas/index-10.html` and follow the installation and deployment instructions.

  Note: When you develop applications using JDK 1.3, you should be aware of a JDK class loader issue. The class loader can locate custom login modules only if you deploy the JAR containing them as a standard extension in the `ORACLE_HOME``/jre/lib/ext` directory. This problem will be fixed at the next release.

- At this release, Oracle supports third-party LDAP providers. See Chapter 9, "Configuring External LDAP Providers", for details.

- At this release, Oracle supplies a default file (`jazn.security.props`) in the directory `ORACLE_HOME``/j2ee/home/startup` that specifies the OracleAS JAAS provider to be used for JAAS login configuration and policy. Note that these properties are set by default during OC4J startup, so in most circumstances you do not need to worry about setting these properties. For details, see "Specifying an Alternate Policy Provider (Optional)".

- Custom `UserManager` classes are still supported at this release, but will be deprecated at a future release.

- The file `principals.xml` will no longer be supported at a future release. We strongly encourage you to migrate your existing applications from using `principals.xml` to using `JAZNUserManager`. For instructions, see "Migrating Principals from the principals.xml File".

- The interface for retrieving the SSL client certificate has changed. You now use the following:

      servletRequest.getAttribute("javax.servlet.request.X509Certificate");

  Instead of:

      servletRequest.getAttribute("javax.security.cert.X509certificate");