Skip Headers

Oracle9iAS Containers for J2EE Services Guide
Release 2 (9.0.2)

Part Number A95879-01
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index

Go to previous page Go to next page

Overview of JAAS in Oracle 9iAS

This chapter introduces support for Java Authentication and Authorization (JAAS), in Oracle9iAS Containers for J2EE (OC4J). JAAS enables application developers to integrate authentication, authorization, and delegation services with their applications.

This chapter contains these topics:

Support for JAAS

JAAS is a Java package which enables applications to authenticate and enforce access control.

Oracle9iAS supports JAAS by implementing a JAAS provider. The JAAS provider provides application developers with user authentication, authorization, and delegation services to 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.


Some class and component names contain the word "JAZN", which is the internal code name for "JAAS provider".

What are Authentication, Authorization, and Delegation?

Authentication is the process of verifying the identity of a user, device, or other entity in a computer system, often as a prerequisite to granting this entity access to resources in a system. For example, when a user enters a username and password to access resources on a computer, such as a database, the user must first be authenticated (verified) by means of the login information before being permitted access to these resources.

Once a user's username and password have been authenticated, the authorization process occurs. Authorization is the process of determining the following for the authenticated user: Who has the right to perform an operation on an object (such as updating a table in a database)?

Delegation provides support for impersonation of a specified user. An application can be configured to run with the permissions associated with specified user by means of the run-as element.

Foundations of the JAAS Provider

The JAAS framework and the Java2 Security model form the foundation of the JAAS provider. That is, the JAAS provider implements JAAS and integrates with J2SE and J2EE applications that use the Java2 Security model.


The JAAS provider implements support for JAAS policies. Policies contain the rules (permissions) that authorize a user to use resources, such as reading a file. JAAS enables services to authenticate and enforce access control upon users of these resources.

Java2 Security Model

The JAAS provider integrates with J2SE and J2EE applications that use the Java2 Security Model. Unlike the original Java security model, under Java2 security, many levels of restrictions can be configured.

See Also:

Java Application Environments

Developers can easily integrate the JAAS provider with these applications for quick development and deployment:

Provider Types

The JAAS provider supports two types of repository providers, referred to as provider types.

These provider types are repositories for secure, centralized storage, retrieval, and administration of provider data. This data consists of realm (users and roles) and JAAS policy (permissions) information.

Use the provider type appropriate to your environment.

LDAP-Based Provider Type

The LDAP-based provider type is based on the Lightweight Directory Access Protocol (LDAP) for centralized storage of information in a directory. Oracle9iAS only uses the LDAP-based Oracle Internet Directory.

Use this provider type if you are using Oracle9iAS and Oracle Internet Directory.

XML-Based Provider Type

The XML-based provider type is used for lightweight storage of information in XML files.

Use this provider type if you are using an XML file, such as jazn-data.xml, to store your user and realm information.


Don't confuse the XML-based provider type with XML files in general. XML files are used as property and configuration files in both LDAP-based and XML-based provider types or environments. If an XML file such as jazn-data.xml is used to store realm and user information, then the provider type is called XML-based.

See Also:

"JAAS Provider Realm and Policy Management"

What is the Java2 Security Model?

Sun's Java2 Security Model is fundamental to the JAAS provider.

The Java2 Security Model enables configuration of security at all levels of restriction. This provides developers and administrators with increased control over many aspects of enterprise applet, component, servlet, and application security.

The Java2 Security Model is capability-based and enables you to establish protection domains, and set security policies for these domains. When the JAAS provider is integrated with applications developed for the J2SE or J2EE environments, these environments use the Java2 Security Model to different degrees.

Permissions are the basis of the Java2 Security Model. All Java classes (whether run locally or downloaded remotely) are subject to a configured security policy that defines the set of permissions available for those classes. Each permission represents a specific access to a particular resource. Table 4-1 identifies the elements that comprise a Java permission instance:

Table 4-1 Java Permission Instance Elements
Element Description Example

Class name

The permission class


The target name (resource) to which this permission applies

Directory /home/*


The actions associated with this target

Read, write, and execute permissions on directory /home/*

Each Java class, when loaded, is associated with a protection domain. Protection domains can be configured for all levels of restriction (from complete restriction on resources to full access to all resources). Each protection domain is assigned a group of permissions based on a configured security policy at Java virtual machine (JVM) startup.

At runtime, the authorization check is done by stack introspection. This consists of reviewing the runtime stack and checking permissions based on the protection domains associated with the classes on the stack. This is typically triggered by a call to either:

The permission set in effect is defined as the intersection of all permission sets assigned to protection domains at the moment of the security check.

Figure 4-1 shows the basic model for authorization checking at runtime.

Figure 4-1 Java2 Security Model

Text description of jazdg005.gif follows.

Text description of the illustration jazdg005.gif

Table 4-2 describes the permission classes provided by the JAAS provider that enables you to enforce access upon users of resources.

Table 4-2 JAAS Provider Permission Classes
Permission Part of Package... Description See Also...


Represents the right to administer a permission (that is, grant or revoke another user's permission assignment)

"AdminPermission" for specific syntax examples


The grantee of this permission is granted the right to further grant/revoke the target role.



For authorization permissions. JAZNPermission contains a name (also called a target name), but no actions list; you either have or do not have the named permission.

"JAZNPermission" for a list of target names for JAZNPermission, what the permissions allow, and the risks of granting the permission


Represents permission actions for a realm (such as createRealm, dropRealm, and so on). RealmPermission extends from, and is used like any regular Java permission.

"RealmPermission" for a list of permission actions

See Also:

What is JAAS?

The JAAS interface is implemented by the JAAS provider. JAAS is a Java package that enables applications to authenticate and enforce access controls upon users.

JAAS is designed to complement the existing code-based security in JDK 1.3. 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 Java2 Security Model to support principal-based authorization.

This section describes JAAS support for the following authorization, authentication, and user community (realm) features. Some of these features are fully supported in this release of JAAS, while others are not explicitly defined. The JAAS provider provides enhancements to some of these features.


A principal is a specific identity, such as a user named frank or a role named hr. A principal is associated with a subject upon successful authentication to a computing service.

A principal is represented by an instance of a concrete class that implements the interface. Each class defines a namespace for its instances, within which each principal instance has a unique name. The name and class of a principal instance uniquely describes the instance.

For LDAP-based environments, an X500Principal class is defined that accepts the X.500 style name as the name of the principal.


A subject represents a grouping of related information for a single user of a computing service, such as a person, computer, or process. Such information includes the subject's identities and security-related attributes (such as passwords and cryptographic keys).

Subjects can have multiple identities, where principals represent identities in the subject. A subject becomes associated with a principal (user frank) upon successful authentication to a computing service, that is, the subject provides evidence (such as a password) to prove its identity.

Principals bind names to a subject. For example, a person subject, user frank, may have two principals:

Both principals refer to the same subject.

Subjects can also own security-related attributes (known as credentials). Sensitive credentials requiring special protection, such as private cryptographic keys, are stored in a private credential set. Credentials intended to be shared, such as public key certificates or Kerberos server tickets are stored in a public credential set. Different permissions are required to access and modify different credential sets.

Subjects are represented by the class.

To perform work as a particular subject, an application invokes the method Subject.doAs(Subject, PrivilegedAction) (or one of its variations). This method associates the subject with the current thread's AccessControlContext, and then executes the specified request.

Login Module Authentication

To associate a principal (such as frank) with a subject, a client attempts to log into 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.

Since the LoginContext separates the application code from the authentication services, a different login module can be plugged in under an application without affecting the application code.

Actual authentication occurs with the method LoginContext.login(). If authentication succeeds, the authenticated subject can be retrieved by invoking LoginContext.getSubject(). The real authentication process can involve multiple login modules. JAAS 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 Subject.doAs().

See Also:


JAAS does not explicitly define roles or groups. Instead, roles or groups are implemented as concrete classes that use interface

JAAS does not define how to support the RBAC role hierarchy (granting a role to a role). The Sun provider of recognizes a special type of principal, as defined by the PrincipalComparator interface. However, PrincipalComparator is not fully integrated with the JAAS provider, and is therefore not supported.

For LDAP-based environments, an X500GroupPrincipal class is defined that accepts an X.500 style name as the name of the group.


JAAS 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. The J2EE RI Realm API, however, is:


JAAS does not explicitly define an application or subsystem for partitioning authorization rules. However, JAAS meets many of the requirements for the subsystem concept. For example, JAAS defines the notion of a codebase (plus a signer) as the target and grantee of a grant statement. This enables permissions to be granted application-specific code. The Java notion of namespace partitioning through packages also allows for partitioning of permission classes in an application-specific manner.

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 JAAS provider. JAAS does not define an administrative API for policy administration. The administrative API is implementation specific.

Table 4-3 describes Sun's implementation of policy file parameters.

Table 4-3 Policy File Parameters
Where... Is Defined As... Example


one or more principal(s)



codebase, signer, foo

File-based Policy Example

The following example shows a typical entry in the JAAS policy file as implemented by Sun's implementation of the JAAS file-based policy provider:

 grant   CodeBase "",
        Principal "duke" 
        permission "/home/duke", "read, write"; 

Code from, signed by foo, and running as a SolarisPrincipal with the username duke, has the permission that permits the executing code to read and write files in /home/duke.

XML-Based Example

The JAAS provider also provides an XML file to store policy information. In the following example, a segment of the jazn-data.xml file grants the /administrators various permissions:

<!--JAZN Policy Data -->
RealmPermission$$modifyrealmmetadata</name> </permission> <permission> <class></class> <name>
RealmPermission$$droprealm</name> </permission> <permission> <class></class> <name>$jazn. com$createrole</name> </permission> <permission> <class></class> <name></name> <actions>createrealm</actions> </permission> </permissions> </grant> </jazn-policy>

See Also:

JAAS Provider Features

Table 4-4 lists the JAAS features provided by Oracle9iAS.

Table 4-4 JAAS Provider Features
Feature Description See Also...


Realms provide access to user and role information. An Oracle proprietary Realm API package ( realm) is provided to support user and role management. This API includes a RealmPrincipal interface that extends from and associates a realm with users and roles


"JAAS Provider Realm Framework"

Role-based access control (RBAC)

Support is provided for secure, centralized, and customizable RBAC management

"Role-Based Access Control (RBAC)"

Login Module Authentication

  • Provides a RealmLoginModule class for non-SSO environments

  • Integrates with Oracle9iAS Single Sign-On (SSO) for SSO login authentication in J2EE application environments

Chapter 8, "Developing Secure J2SE Applications"

Chapter 9, "Developing Secure J2EE Applications"

JAAS provider type management

Several methods for managing JAAS provider type information are available:

  • An Admintool command line tool that supports management of information in both provider types

  • An Oracle Enterprise Manager graphical user interface (GUI) tool that supports management of information in LDAP-based Oracle Internet Directory

  • Programmatic level management of both provider types

"JAAS Provider Policy Administration"

Chapter 7, "Managing the JAAS Provider"


JAZNUserManager is an implementation of the OC4J UserManager that integrates with both LDAP-based and XML-based provider types.

"JAAS Provider Integration in J2SE Application Environments"

Chapter 9, "Developing Secure J2EE Applications"

JAAS Provider User Services

The Oracle9iAS implementation of JAAS provides these user services for application developers to integrate into their applications. This section describes several JAAS provider authorization features.

Capability Model of Access Control

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

Table 4-5 User Permissions
User Has These File Permissions...


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 4-5 are retrieved from the JAAS provider (whether the LDAP- based Oracle Internet Directory or XML-based provider type) and granted to user frank. User frank is then free to execute the actions permitted by these permissions.

See Also:

Role-Based Access Control (RBAC)

RBAC enables you to assign permissions to roles. Users are then granted their permissions by being made members of appropriate roles. Support for RBAC is a key JAAS provider feature. This section describes the following RBAC features:

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 4-2 provides an example.

Figure 4-2 Role-Based Access Control

Text description of jazdg006.gif follows.

Text description of the illustration jazdg006.gif

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. The user can selectively enable the required roles to accomplish a specific task in a user session with the run-as security identity and Subject.doAS(). This ensures the principle of least privilege. This way, the user is not enabling permissions or privileges unnecessary for the task. This limits the damage that can potentially result from an accident or error.

See Also:

Sun Java documentation by visiting the following URL:

JAAS Provider Realm and Policy Management

The JAAS provider supports two types of repository providers, referred to as provider types:

OiD and jazn-data.xml are repositories used to store realm (users and roles) and policy (permissions) information. This section discusses the following topics in relation to the two different provider types:

Realm and Policy Management Tools

Several tools are provided for managing realm and policy information. Table 4-6 describes these tools and indicates the environment in which they operate.

Table 4-6 Realm and Policy Management Tools
Method/Environment Description See Also...

Oracle Enterprise Manager

LDAP-based only

A graphical user interface tool that enables you to create principals (known as grantees) and assign permissions to these grantees.

"Using the Oracle Enterprise Manager Interface with the JAAS Provider"

JAZN Admintool

Both LDAP and XML-based environments

A command line interface tool that enables administrators to create and manage users, realms, roles, and policies. The JAZN Admintool:

The JAZN Admintool has the same capabilities and limitations as the JAAS Provider APIs. For example, you cannot create users with the JAZN Admintool if your provider type is LDAP-based Oracle Internet Directory. However, you can create users if your provider type is XML-based.

"Using the JAZN Admintool"

See Also:

  • "What JAAS Provider Components Do You Need to Install?" in the Oracle9i Application Server Installation Guide for information on installing the provider type you want to use

  • "Realms"

  • "Package"

JAAS Provider Realm Framework

The J2EE environment defines the concept of user communities. A user community instance is essentially a realm maintained internally by the authorization system.

The API package is provided to support realms. This API package is an enhancement to the JAAS policy provider.

Realms can be managed in both provider type environments:

Realm Management in LDAP-Based Environments

A realm provides user and role management. An LDAP-based realm's data can be managed:

LDAP-Based Realm Types

The JAAS provider supports three types of realms for LDAP-based environments. Each realm provides different user and role management capabilities. Table 4-7 describes these realms.

Table 4-7 Implementation of Realm Types
Realms Type Description Use This Realm... See Also...

External Realm

  • Supports external, read-only user and role management

  • Integrates existing user communities with the JAAS provider

For non-hosting environments

Figure 4-3

"Creating an External Realm"

Subscriber Realm

  • Created through provisioning tools

  • Used in hosting environments

  • Supports external, read-only user and role management

In a hosting environment (with subscriber-based customers) where multiple customers or companies subscribe to shared services

Figure 4-4

Application Realm

  • Supports external, read-only user management

  • Supports internal roles management

If you want to use the JAAS provider role management feature

Figure 4-5

"Creating an Application Realm"

Each realm type consists of:

User and role managers internally perform their duties (through JAAS provider permissions) or externally (through OiD Delegated Administration Service (DAS)).


The JAAS provider does not provide an internal user manager for creating users. Instead, you can create users with DAS or a command line tool such as ldapadd.

Figure 4-3 shows a sample LDAP directory information tree (DIT) containing an External Realm that is registered as an instance with the JAAS provider. The realm type is created below a Realms container.

Figure 4-3 Simplified Directory Information Tree for the External Realm

Text description of jazdg008.gif follows.

Text description of the illustration jazdg008.gif

Table 4-8 describes the user and role management responsibilities of the External Realm.

Table 4-8 External Realm Responsibilities
External Realm Name Role Management User Management


Retrieves external, read-only roles

Retrieves external, read-only users

Figure 4-4 shows a sample LDAP directory information tree (DIT) containing a Subscriber Realm that is registered as an instance with the JAAS provider. The realm type is created below a Realms container.

Figure 4-4 Simplified Directory Information Tree for the Subscriber Realm

Text description of jazdg007.gif follows.

Text description of the illustration jazdg007.gif

Table 4-9 describes the user and role management responsibilities of the Subscriber Realm.

Table 4-9 Subscriber Realm Responsibilities
Subscriber Realm Name Role Management User Management


Retrieves external, read-only roles of a subscriber

Retrieves external, read-only users of a subscriber

Figure 4-5 shows a sample LDAP directory information tree (DIT) containing an Application Realm that is registered as an instance with the JAAS provider. The realm type is created below a Realms container.

Figure 4-5 Simplified Directory Information Tree for the Application Realm

Text description of jazdg009.gif follows.

Text description of the illustration jazdg009.gif

Table 4-10 describes the user and role management responsibilities of the Application Realm.

Table 4-10 Application Realm Responsibilities
Application Realm Name Role Management User Management


Internally creates and manages modifiable roles

Retrieves external, read-only users

LDAP-Based Realm Data Storage

The realm framework provides a means for registering realm instances with the JAAS Provider and managing their information.

A Realms container object is created under the site-wide JAAS context. (For example, see the Realms container in Figure 4-3.) For each registered realm instance, a corresponding realm entry is created under the Realms container that stores the realm's attributes. This directory hierarchy is known to the JAAS provider, which enables the JAAS provider to create new realm instances in the desirable directory location and find all the registered realms in runtime.

For example, the distinguished name (DN) for a realm called oracle can be "cn=oracle,cn=realms,cn=JAZNContext,cn=site root".

Upon successful installation of the JAAS provider, a default realm (External Realm) instance is installed. Predefined realm properties are configured for starting the default realm. Any realm type must provide concrete implementations for the system defined Java interfaces UserManager and RoleManager. In runtime, the JAAS provider finds all the registered realms and their attributes (name, user manager implementation class, role manager implementation class, and their properties) from the provider type (Oracle Internet Directory) and instantiates the realm's implementation class with the properties for initialization.

LDAP-Based Realm Permissions

A RealmPermission class is defined to represent realm permissions. RealmPermission extends from Permission. It is used like any regular Java permission. RealmPermission has the following characteristics:

Realm Management in XML-Based Environments

A realm provides user and role management. For XML-based environments, realm management is less restrictive and faster: a more lightweight implementation than LDAP-based realm management.

XML-Based Realm Types

The JAAS provider enables you to create a single realm type for an XML-based environment.

See Also:

"Using the JAZN Admintool" for instructions on creating realm types.

XML-Based Realm and Policy Information Storage

An XML-based realm enables you to:

This information is stored in an XML file, typically, jazn-data.xml. The following example shows the structure used in a jazn-data.xml file to create realms, users, and roles.

<!--JAZN Realm Data -->

                       <displayName>Realm Administrator</displayName>
                       <description>Administrator for this realm</description>
                       <description>The default guest/anonymous
                       <displayName>Realm Admin Role</displayName>
                       <description>Administrative role for this

See Also:

"Sample jazn-data.xml Code" for a completed jazn-data.xml file.


Setting the <credentials> element as follows enables you to use clear (readable) passwords in the jazn-data.xml file the first time.

  • <credentials clear="true">welcome</credentials>

  • <credentials>!welcome</credentials>

This enables the administrator to directly edit jazn-data.xml with a text editor. When the file is read and persistence occurs, the password in jazn-data.xml is obfuscated and becomes unreadable.

JAAS Provider Policy Administration

The JAAS provider implementation of uses either an LDAP-based Oracle Internet Directory or XML-based provider type for storing policy (authorization rules). The JAAS provider administrator uses various grant and revoke methods of the JAZNPolicy class to create authorization policies for principals.

The provider must be administered in a secure manner. There are several ways to administer the JAAS provider policy:

Oracle Internet Directory Administration

For LDAP-based application environments, you manage realm and policy data as Oracle Internet Directory entries through:

Two possible administrative groups can manage the data:

In hosted application environments, part of the policy data may be partitioned along subscriber boundaries and thus stored in a subscriber subtree. That policy data cannot be administered by the realm-specific administrative group. The same is true with role information.

With the JAAS provider policy data (including realm data), only users that belong to JAZNClientGroup or JAZNAdminGroup have read-access capabilities on provider data.

The LDAP-based environment caches provider policy data; for details, see "Managing JAAS Provider Policy" on page 36.

See Also:

Oracle Internet Directory Administrator's Guide

AdminPermission Class

The AdminPermission class can be used in either LDAP-based or XML-based environments.

The AdminPermission class represents the right to administer a permission. This enables a grantee (such as a user named frank) to further grant and revoke the granted right/permission to other grantees. Instances of this permission class include instances of other permissions. Since this is a permission about permission, it varies slightly from the permission definition, which includes a simple name, actions pair. This variation is resolved by encoding a permission instance as a string and using that as the name of the AdminPermission instance. Table 4-11 provides an example:

Table 4-11 ADMIN Option Example
If User... Then User...

frank is granted the AdminPermission for"/tmp/*","read,write")

frank can further grant and revoke any permission implied by the embedded permission (that is, FilePermission in this instance).

When expressed in the format recognized by the policy provider, this results in the following:

 grant Principal "frank" 
     ", name=\"/tmp/*\", actions=\"read, write\"" 

Note that another permission instance is encoded in the target name for this AdminPermission instance.

Recursive embedding of AdminPermission (that is, an AdminPermission instance embedded within another AdminPermission instance) is not supported. In the initial policy, the JAAS user is granted AdminPermission to, enabling the JAAS user to grant and revoke all permissions to anyone.

A RoleAdminPermission class is defined for roles. This means that when role hr is granted to frank, frank is granted both role hr and a RoleAdminPermission that enables frank to further grant and revoke role hr.

See Also:

"Policies and Permissions" for an example of an XML-based policy file

Policy Partitioning

The JAAS provider supports policy partitioning among realms (that is, each realm has its own realm-specific policy). This realm-specific policy is administered by the realm-specific administrative group.

In a hosted environment, a subscriber is represented by a realm and the subscriber-specific information subtree is stored under a subscriber-specific JAZNContext. This subscriber-specific subtree, however, is primarily administered by the JAAS Provider administrative group from the perspective of the LDAP server (Oracle Internet Directory).

Go to previous page Go to next page
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index