4
JAAS Provider Administration Tasks

This chapter describes how to manage the Oracle Application Server Containers for J2EE (OC4J) JAAS Provider.

This chapter contains these topics:

• JAAS Provider Management Overview

• Realm and Policy Management

• JAAS Provider Debug Logging

JAAS Provider Management Overview

Managing the JAAS Provider in the J2SE and J2EE environments involves creating and managing realms, users, roles, permissions, and policy. OC4J provides two tools for managing JAAS configuration: the JAAS Provider Admintool and Oracle Enterprise Manager (OEM). You can also manage JAAS programatically.

• Oracle Enterprise Manager

• Oracle Internet Directory Delegated Administrative Service (OID DAS)

• JAZN Admintool, a command-line tool

• JAAS Provider APIs

  Note: Configuration tasks differ by whether your application uses an XML-based or LDAP-based JAAS Provider.

Table 4-1 describes which tools can be used in the XML and LDAP provider environments.

Table 4-1 Tools For Managing XML-Based and LDAP-Based Provider Environments

Using This Tool	With XML-Based provider type	With LDAP-Based provider type
Oracle Enterprise Manager	Map security roles.	Map security roles.
OID DAS	Not applicable.	Manage users and groups.
JAZN Admintool	Manage users, roles, and policy.	Manage policy.

Realm and Policy Management

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

• The XML-based provider type used with an XML file, typically jazn-data.xml

• The LDAP-based provider type used with Oracle Internet Directory (OID)

  Note: To manage LDAP-based users and roles, use the Delegated Administration Service (DAS); see the Oracle Internet Directory Administrator's Guide. for details.

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

• JAAS Provider Realm Framework

• Realm Management in XML-Based Environments

• Realm Management in LDAP-Based Environments

• JAAS Provider Policy Administration

Realm and Policy Management Tools

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

Table 4-2 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 manage users, roles, and groups.	"JAAS and Enterprise Manager"
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: Uses the JAAS Provider API to perform functions Can be executed from the operating system command line 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: The Oracle Application Server 10g Installation Guide for information on installing the provider type you want to use.

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 oracle.security.jazn.realm 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:

• XML-based

  Provides a lightweight form of storage for realms and JAAS policy

• LDAP-based Oracle Internet Directory

  Provides centralized storage of realms and JAAS policy in a directory

Realm Management in XML-Based Environments

A realm provides user and role management. The XML-based provider offers a lightweight, less restrictive, and faster implementation of realms than does the LDAP-based provider.

XML-Based Realms

You can use the JAAS Provider to create one or more realms for an XML-based environment.

See Also: "Using the JAZN Admintool" for instructions on creating realms

XML-Based Realm and Policy Information Storage

The XML-based Provider enables you to:

• Create realms, users, and roles

• Grant roles to users and to other roles

• Assign permissions to specific users and roles (principals)

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

   <jazn-realm>
        <realm>
             <name>jazn.com</name>
             <users>
                  <user>
                       <name>admin</name>
                       <displayName>Realm Administrator</displayName>
                       <description>Administrator for this realm</description>
                 <credentials>
                   {903}ZcOsWfcw5YRI0Bsq4sNFuLioZgX3a6CF
                 </credentials>
                  </user>
                  <user>
                       <name>anonymous</name>
                       <description>The default guest/anonymous
                                user</description>
                  </user>
             </users>
             <roles>
                  <role>
                       <name>guests</name>
                       <members>
                            <member>
                                 <type>user</type>
                                 <name>admin</name>
                            </member>
                            <member>
                                 <type>user</type>
                                 <name>anonymous</name>
                            </member>
                       </members>
                  </role>
                  <role>
                       <name>administrators</name>  
                       <displayName>Realm Admin Role</displayName>
                       <description>Administrative role for this
                                    realm</description> 
                       <members>
                            <member>
                                 <type>user</type>
                                 <name>admin</name>
                            </member>
                       </members>
                  </role>
                  <role>
                       <name>users</name>  
                       <members>
                            <member>
                                 <type>user</type>
                                 <name>admin</name>
                            </member>
                       </members>
                  </role>
             </roles>
        </realm>
   </jazn-realm>

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

Note: Setting the <credentials> element as follows enables you to use clear (readable) passwords in the jazn-data.xml file. <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.

Realm Management in LDAP-Based Environments

A realm provides user and role management. You can manage the data in an LDAP-based realm:

• Internally by creating and managing user information with the JAAS Provider. See Chapter 4, "JAAS Provider Administration Tasks".

• Externally by creating and managing user and role information with Oracle Internet Directory and then integrating it with the JAAS Provider.

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-3 describes these realms.

Table 4-3 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-1
Identity Management Realm	Created through provisioning tools Used in hosting environments Supports external, read-only user and role management	In a hosting environment in which multiple customers or companies subscribe to shared services	Figure 4-2
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-3

When you use the LDAP-based JAAS provider with OracleAS Single Sign-On, you must use the Identity Management Realm. The External Realm and Application Realm are not supported when using OracleAS Single Sign-On.

Each realm type consists of:

• A role manager for role management

• A user manager for user management

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

Note: The JAAS Provider does not supply an internal user manager for creating users. You can create users with DAS or a command line tool such as ldapadd.

Figure 4-1 shows a sample LDAP 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-1 Simplified Directory Information Tree for the External Realm

Text description of the illustration jaz008.gif

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

Table 4-4 External Realm Responsibilities

External Realm Name	Role Management	User Management
abcRealm	Retrieves external, read-only roles	Retrieves external, read-only users

Figure 4-2 shows a sample LDAP DIT containing an Identity Management Realm that is registered as an instance with the JAAS Provider. The realm type is created below a Realms container.

Figure 4-2 Simplified Directory Information Tree for the Identity Management Realm

Text description of the illustration jaz007.gif

Table 4-5 describes the user and role management responsibilities of the Identity Management Realm.

Table 4-5 Identity Management Realm Responsibilities

Identity Management Realm Name	Role Management	User Management
BestCOMRealm	Retrieves external, read-only roles of a subscriber	Retrieves external, read-only users

Figure 4-3 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-3 Simplified Directory Information Tree for the Application Realm

Text description of the illustration jaz009.gif

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

Table 4-6 Application Realm Responsibilities

Application Realm Name	Role Management	User Management
devRealm	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-1.) 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 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. During 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.

Realm Hierarchy

As Figure 4-4 illustrates, the JAAS Provider stores its entries within the product container cn=JAZNContext. Beneath cn=JAZNContext is a cn=Realms container, which stores realm entries, and a cn=Policy container, which stores global JAAS Provider policies. The cn=Policy container in turn stores two types of entries, cn=Permissions and cn=Grantees.

Note that the JAAS Provider has its own Groups and Users containers. The Groups container contains the group JAZNAdminGroup. The Users container contains the users that populate these groups.

Figure 4-4 Global JAZNContext Subtree

Text description of the illustration dirig014.gif

Figure 4-5 shows the directory entries that are placed under the example realm cn=sampleRealm. The entry cn=usermgr stores information related to user management while the entry cn=rolemgr stores information related to role (group) management. The policy-related entries under cn=sampleRealm store realm-specific policies.

Figure 4-5 A Realm-Specific Subtree

Text description of the illustration dirig015.gif

In an identity management-based environment, a subscriber is registered as a realm. Using the subscriber DN, the JAAS Provider locates the subscriber-specific Oracle Context and creates a cn=JAZNContext subtree. In this case, the JAAS Provider stores the entries cn=usermgr and cn=rolemgr and policy-related entries under the subscriber's JAZNContext.

In Figure 4-6 cn=oracle is a subscriber.

Figure 4-6 Subscriber JAZNContext Subtree

Text description of the illustration dirig018.gif

ACLs and JAZN directory entries

JAAS Provider directory entries are protected by ACLs at the root of the product subtree. These ACLs grant the group JAZNAdminGroup and the JAAS Provider superuser JAZNAdminUser full privileges (read, write) for JAAS Provider directory objects. Non-superusers who are not JAZNAdminGroup members are denied access to JAAS Provider entries.

Because identity management JAZNContext subtrees are mirror images of their site-wide parents, the security measures that they use to protect entries are the same.

LDAP-Based Realm Permissions

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

• Realm name, also known as target name

• List of actions (permissions applicable to the realm, such as creating a realm, dropping a role, and so on)

  See Also: The JAAS Provider Javadoc

JAAS Provider Policy Administration

The JAAS Provider implementation of javax.security.auth.Policy 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 policy provider must be administered in a secure manner. There are several ways to administer the JAAS Provider policy:

• Oracle Enterprise Manager (LDAP environments only)

• JAAS Provider Admintool

• Oracle Internet Directory Administration

• AdminPermission Class

  See Also: Table 4-2 for information on Oracle Enterprise Manager and "Using the JAZN Admintool" for information on the JAZN Admintool

Oracle Internet Directory Administration

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

• The OID DAS and Oidadmin administrative tools

• Definition of access control lists in Oracle Internet Directory

Two possible administrative groups can manage the data:

• A JAAS Provider site-wide administrative group that is granted permissions to access and modify the site-wide JAZNContext and any identity management-specific JAZNContext

• A realm-specific administrative group for each realm instance or administrative user

In hosted application environments, part of the policy data may be partitioned along subscriber boundaries and 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 JAZNAdminGroup have read-access capabilities on provider data.

The LDAP-based environment caches provider policy data; for details, see "Configuring Caching (LDAP-Based Provider Only)".

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. Because 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-7 provides an example:

Table 4-7 ADMIN Permission Example

If User	Then User
frank is granted the AdminPermission for java.io.FilePermission("/tmp/*","read,write")	frank can further grant and revoke any permission implied by the embedded permission (that is, FilePermission in this instance).

 grant Principal com.oracle.security.jazn.JAZNPrincipal "frank" 
{ 
  permission com.oracle.security.jazn.policy.AdminPermission 
     "class=java.io.FilePermission, name=\"/tmp/*\", actions=\"read, write\"" 
};

The JAAS Provider does not support recursive embedding of AdminPermission (that is, an AdminPermission instance embedded within another AdminPermission instance). In the initial policy, the user is granted AdminPermission to java.security.AllPermission, enabling the JAAS Provider 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.

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.

Each 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).

JAAS Provider Debug Logging

To turn on 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 settings for your OC4J instance. In Oracle Application Server, you normally manage JVM settings via the <java-options> element in opmn.xml. In standalone mode, you set this property using JVM command-line options. For instance, 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 the log files associated with the OC4J instance.