7
Managing the JAAS Provider

This chapter describes how to manage the Oracle9iAS Containers for J2EE (OC4J) JAAS Provider in Java2 Platform, Standard Edition (J2SE) and Java2 Platform, Enterprise Edition (J2EE) environments.

This chapter contains these topics:

• JAAS Provider Management Overview

• Using the Oracle Enterprise Manager Interface with the JAAS Provider

• Using the JAZN Admintool

• Managing LDAP Provider Data with Java Programs

• Managing XML-Based Provider Data with the XML Schema

• Other Utilities

JAAS Provider Management Overview

Managing the JAAS provider in the J2SE and J2EE environments involves creating and managing realms, users, roles, permissions, and policy.

How you manage the JAAS provider depends on two things:

• Whether your provider is XML-based or LDAP-based Oracle Internet Directory

• Which of the available tools (alone or in combination) you are using:
  • Oracle Enterprise Manager (OEM) (policy and permission management, only with this release)

  • JAZN Admintool, a command line interface tool

  • Java Programs for LDAP Management, based on the JAAS Provider APIs

  • Other Utilities including:

    -PermissionClassManager

    -PrincipalClassManager

    -LoginModuleManager

    Note: Based on the provider type you are using, these tools are used in slightly different contexts and are not necessarily directly parallel in function. For example, the JAZN Admintool enables you to create users if your provider type is the XML-Based Provider Type, but not if your provider type is LDAP-based. Therefore, if you are planning to rely on either the Oracle Enterprise Manager or the JAZN Admintool, also read the appropriate section, "Managing LDAP Provider Data with Java Programs" or "Managing XML-Based Provider Data with the XML Schema", for a fuller understanding of the functions available in each environment.

Table 7-1 describes the general functionality of each tool in both XML-based and LDAP-based provider type environments.

Table 7-1 Tools for Managing XML-Based and LDAP-Based Provider Environments

Using This Tool...	With LDAP-Based provider type	With XML-Based provider type
Oracle Enterprise Manger	You can create principals (known as grantees) and assign permissions to these grantees.	This tool is not available.
JAZN Admintool	A broad range of functions is available, including several not included in the API.	A broad range of functions is available, including several not included in the API.
Java Programs for LDAP Management	You have access to all the JAAS Provider API functionality available in an LDAP environment.	This tool is not available.

LDAP-Based and XML-Based JAAS Providers

XML-based and LDAP-based JAAS providers enable different functionalities as described in Table 7-2.

Table 7-2 JAAS Provider Management

JAAS Provider	Description	See Also...
LDAP-based Available with the Oracle9iAS Infrastructure installation type)	Enables you to: Create realms Manage roles (in an External Realm or Subscriber Realm) Manage or create roles (in an Application Realm) Assign permissions	"Realm Management in LDAP-Based Environments" "Managing Realms"
XML-based (Available with all installation types	Enables you to: Create and manage realms, users, and roles Assign permissions	"Realm Management in XML-Based Environments" "Managing XML-Based Provider Data with the XML Schema"

Using the Oracle Enterprise Manager Interface with the JAAS Provider

You can use Oracle Enterprise Manager to perform two JAAS provider tasks:

• Manage JAAS Policy

• Manage Java Permissions

  See Also: Your Oracle Enterprise Manager documentation for instructions on starting Oracle Enterprise Manager

Oracle Enterprise Manager functionality for the JAAS provider is currently only available for the LDAP provider environment and only for policy management tasks.

Note: Oracle Enterprise Manager windows use Add buttons that operate as follows: You enter or select items to be acted upon or searched for, add them to a list using the Add button, and finally process the items.

Accessing the JAAS Provider

To use the Oracle Enterprise Manager to perform JAAS provider tasks, navigate to the Oracle9i Application Server entry, then to the OC4J system component, and select the application default as follows:

To access the JAAS Provider:

1. Choose the appropriate Oracle9i Application Server entity in the Application Servers Name column.

2. Choose OC4J in the System Components list.

   The System Components panel appears:

   

   Text description of the illustration syscom.gif

3. Choose Oracle9i Application Server from the list of Application Defaults.

The main window for the JAAS provider appears:



Text description of the illustration jpolicy0.gif

Task 1: Managing JAAS Policy

Policies, which store JAAS authorization rules, consist of one or more grants or grant entries. Grant entries are grantees (principals and codesource (optional)) and their assigned permissions.

Managing JAAS Policy enables you to:

• Search for existing grant entries and view grant entry data

• Delete grant entries

• Create new grant entries by assigning JAAS provider permissions to principals

  Note: To manage JAAS policy, the policy cache must be disabled. This is the default setting.

Searching for and Viewing Existing Grant Entries

To search for and view grant entry data:

1. Choose JAAS Policy from the tab on the left of the main window.

   The JAAS Policy Management window appears. This is the same as the main JAAS provider window. See "Accessing the JAAS Provider".

   The window immediately displays a results list that you can modify by entering a search phrase or using arrows that guide you to subsequent sections of the results list.

2. Enter the codesource URL, if any.

3. If the grant name you are searching for does not appear immediately on the results list, enter it.

   Wild cards are implied, that is, if you enter several letters, the results list shows all entries that begin with those letters, assuming the case is the same.

4. Choose Go or press Enter.

5. When the grant name you are searching for appears in the results list, click the name to view the grant entry data.

   For the grant name you have entered, the following data appears:

   • Principal Names and classes

   • Permission Names and classes

   • The codesource, if any, assigned to the grant entry

Deleting Grant Entries

To delete grant entry data:

1. Perform the search functions as described "Searching for and Viewing Existing Grant Entries".

2. Select the grant entry from the results list by choosing the radio button besides the name.

3. Choose Delete.

Creating a New Grant Entry

To create a new grant entry:

1. Choose JAAS Policy from the tab on the left.

   The JAAS Policy Management window appears.

2. Choose New Grant.

   The New Grant: Name/CodeSource window appears, and enables you to enter a name for the new grant entry and define a codesource. The codesource is the code associated with the policy entry.

   

   Text description of the illustration jpolicyc.gif

3. Enter a grant name and codesource.

4. Choose Next.

   See Also: "Policies and Permissions" for information on codesources

   The New Grant: Principal(s) window appears and enables you to select the principal type and enter one or more principals to define the grant entry.

   The available principal types are:

   • Solaris User

   • LDAP User

   • Realm User

Text description of the illustration jpolicyd.gif

5. Select the type and enter the name of a principal.

   If you have selected the LDAP type, the name must be an X.500 distinguished name. Although the system accepts other names, they will be rejected when you finish. For other types, you can enter any name.

6. Choose Add to add this principal to the list of principals being added to this grant.

7. Repeat Steps 5 and 6 until all principals are added to the list of principals.

8. Choose Next to add all principals on the list to the grant.

   The New Grant: Permission window appears and enables you to enter the permission class, target, and action for the grant entry. These are essentially what the user is authorized to do with your application.

   • The class is the Java permission being assigned to the policy (for example, java.io.FilePermission).

   • The target is the resource to which this permission applies (for example, files in a directory named /home/*).

   • The action is the actions associated with this target (for example, read and write privileges on all files in /home/*).

Text description of the illustration jpolicya.gif

9. Select the class, target, and action from the drop-down list boxes on the left or enter the names directly in the fields on the right.

10. Choose Add to add this permission to the list of permissions to be added the grant.

11. Repeat Steps 9 and 10 until all permissions have been added to the list of permissions.

12. Choose Finish.

    The entry is now granted these permissions on the designated target. The grant entry is complete.

Task 2: Managing Java Permissions

The Java Permissions task enables you to search for and view the permissions of a principal on a given codesource and revoke these permissions. You can search by principal class or principal name.

Searching for and Viewing Existing Permissions

To search for permissions on a principal:

1. Choose Java Permissions from the tab on the left.

   The Permission Management window appears:

   

   Text description of the illustration jpolicyb.gif

2. Enter the codesource URL.

3. Select the principal type from the drop-down list.

   The available principal types are:

   • Solaris User

   • LDAP User

   • Realm User

4. Enter the name of a principal from the principal type.

5. Choose Add to add a principal to the search list. You can search for multiple principals at once.

6. Repeat Steps 4 and 5 until all principals have been added to the search list.

7. Choose Search.

The results display on-screen including permission class, permission target, and permission actions, but the codesource does not appear.

Revoking Permissions Assigned to a Principal

To revoke permissions assigned to a principal:

1. Perform the search function as described in "Searching for and Viewing Existing Permissions".

2. Revoke permissions by selecting the radio button of an appropriate permission.

   You can only revoke one permission at a time.

3. Choose Revoke.

Using the JAZN Admintool

The JAZN Admintool can manage both XML-based and LDAP-based JAAS provider data from the command prompt.

The JAZN Admintool is a flexible Java console application, with functions that can be called directly from the command line or through the shell interface of the Admintool. The shell uses UNIX-derived commands to perform specific JAAS provider functions.

This section includes the following topics:

• Usage Examples

• Command Options

• Realm Operations

• JAZN Shell Interface

• JAZN Shell Commands

Usage Examples

The following examples illustrate the different ways that the JAZN Admintool commands can be used.

To list all users in realm foo:

From the UNIX command line:

java -jar jazn.jar -listusers foo

From the shell interface of the Admintool (using command-line options):

JAZN:> listusers foo

From the shell interface of the Admintool (through modified UNIX commands):

JAZN:> cd /realms/foo/users
JAZN:foo> ls

To add the role fooRole to realm foo:

From the UNIX command line:

java -jar jazn.jar -addrole foo fooRole

From the shell interface of the Admintool (using command-line options):

JAZN:> addrole foo fooRole

From the JAAS provider shell (through modified UNIX commands):

JAZN:> cd /realms/foo/users
JAZN:foo> mkdir fooRole

Command Options

The JAZN Admintool provides the following command options, which are described in greater detail in the following sections. The JAZN Admintool command options can be invoked several different ways as described in "Usage Examples". Error messages display if the syntax or parameters specified are incorrect.

Realm Operations

    -addrealm realm admin {adminpwd adminrole|adminrole
          userbase rolebase realmtype}
    -addrole realm role 
    -adduser realm username password 
    -checkpasswd realm user [-pw password] 
    -grantrole role realm {user|-role to_role} 
    -listrealms 
    -listroles [realm [user|-role role]|-perm permission] 
    -listusers [realm [-role role|-perm permission]] 
    -remrealm realm 
    -remrole realm role 
    -remuser realm user 
    -revokerole role realm {user|-role to_role} 
    -setpasswd realm user old_pwd new_pwd 

Policy Operations

    -addperm permission permission_class action target [description] 
    -addprncpl principal_name prncpl_class params [description] 
    -grantperm realm {user|-role role} permission_class 
          permission_actions 
    -listperms realm {user |-role role|-realm realm} 
    -listperm permission
    -listprncpls 
    -listprncpl principal_name 
    -remperm permission 
    -remprncpl principal_name
    -revokeperm realm {user|-role role} permission_class
          permission_actions 

Interactive Shell

    -shell

Configuration Operations

     -getconfig default_realm admin password 

Migration Operations

    -convert filename realm

Miscellaneous

    -help  
    -version

Realm Operations

Adding and Removing Realms

-addrealm realm admin {adminpwd adminrole | adminrole userbase rolebase
           realmtype}
-remrealm realm

The -addrealm option creates a realm of the specified type with the specified name, and -remrealm deletes a realm.

Valid realm types are:

• LDAP Environment: external and application

• XML Environment: XML

The user must provide the following:

• For an XML provider type:
  • realm name

  • administrator username

  • administrator password

  • administrator role

• For LDAP:
  • realm name

  • administrator name

  • administrator role

  • user search base in the directory

  • role search base in the directory

  • realm type

Adding and Removing Roles

-addrole realm role
-remrole realm role

The -addrole option creates a role in the specified realm, and -remrole deletes a role from the realm.

Adding and Removing Users

-adduser realm username password 
-remuser realm user

The -adduser option adds a user to a specified realm, and -remuser deletes a user from the realm.

Checking Password

-checkpasswd [realm] user [-pw password]

The -checkpasswd option indicates whether the given user requires a password for authentication. If -pw is used, it displays a message indicating whether the specified password authenticates the user.

Granting and Revoking Roles

-grantrole role realm {user|-role to_role} 
-revokerole role realm {user|-role to_role} 

The -grantrole option grants the specified role to a user (when called with a user name) or a role (when called with -role). The -revokerole option revokes the specified role from a user or role.

Listing Realms

-listrealms

The -listrealms option displays all realms in the current JAAS provider environments.

Listing Roles

-listroles [realm [user|-role role|-perm permission]] 

The -listroles option displays a list of roles that match the list criteria. This option lists the following:

• All roles in all realms, when called without any parameters

• All roles granted to a user, when called with a realm name and user name

• Roles that are granted the specified role, when called with a realm name and the option -role

• Roles that are granted the specified permission, when called with a realm name and the option -perm

Listing Users

-listusers [realm [-role role|-perm permission]] 

The -listusers option displays a list of users that match the list criteria. This option lists the following:

• All users in all realms, when called without any parameters

• All users in a realm, when called with a realm name

• Users that are granted a certain role or permission, when called with a realm name and the option -role or -perm

Setting a Password

-setpasswd realm user old_pwd new_pwd

The -setpasswd option allows administrators to reset the password of a user given the old password.

Policy Operations

Adding and Removing Permissions

-addperm permission permission_class action target [description]
-remperm permission

The -addperm option registers a permission with the JAAS provider PermissionClassManager. The -remperm option unregisters the specified permission class. permission and description can be multiple words if enclosed by quotation marks ("").

Adding and Removing Principals

-addprncpl principal_name prncpl_class params [description]
-remprncpl principal_name

The -addprncpl option registers a principal with the JAAS Provider PrincipalClassManager. The -remprncpl option unregisters the specified principal class. principal_name and description can be multiple words if enclosed by quotation marks ("").

Granting and Revoking Permissions

-grantperm realm {user|-role role} permission_class  permission_actions 
-revokeperm realm {user|-role role} permission_class  permission_actions 

The -grantperm option grants the specified permission to a user (when called with a username) or a role (when called with -role). The -revokeperm option revokes the specified permission from a user or role. A permission is denoted by its explicit class name (for example, oracle.security.jazn.realm. RealmPermission) and its action and target parameters (for RealmPermission, realmname action). Note that there may be multiple action and target parameters.

Listing Permissions

-listperms realm {user |-role role| realm realm} 

The -listperms option displays all permissions that match the list criteria. This option lists the following:

• All permissions registered with the JAAS Provider PermissionClassManager

• Permissions that are granted a role, when called with a realm name and the option -role

Listing Permission Information

-listperm permission

The -listperm option displays detailed information about the specified permission, including the permission's display name, class, description, actions, and targets.

Listing Principal Classes

-listprncpls

The -listprncpls option lists all principal classes registered with the PrincipalClassManager.

Listing Principal Class Information

-listprncpl principal_name

The -listprncpl option displays detailed information about the specified principal, including the display name, class, description, and actions.

Interactive Shell

Starting the JAZN Admintool Shell

-shell

The -shell option starts an JAAS provider interface shell. The JAAS Provider shell provides interactive administration of JAAS provider principals and policies through a UNIX-derived interface.

Configuration Operations

Getting XML Configuration Information

-getconfig default_realm admin password

The -getconfig option displays the current configuration setting in jazn.xml.

Migration Operations

Migrating Principals from the principals.xml File

-migrates filename realm|

The -migrate option migrates the OC4J principals.xml file into the specified realm of the current JAAS provider. filename specifies the name and location of the OC4J principals file (typically stored in j2ee/home/config/principals.xml).

The migration converts principals.xml users to JAAS Provider RealmUsers and principals.xml groups to JAAS Provider roles. All permissions previously granted to a principals.xml group are mapped to the JAAS Provider role. All users that were deactivated at the time of migration are not migrated. This is to ensure that no users can inadvertently gain access through the migration.

An error is returned if the specified file contains errors.

See Also: "Replacing principals.xml" for additional information on migration and replacement of principals.xml

Miscellaneous

Getting Help

-help

The -help option displays a list of command options available with the JAZN Admintool.

JAZN Shell Interface

The JAZN Admintool includes a shell called the JAZN shell interface. The JAZN shell provides an interactive interface to the JAAS Provider API.

The shell directory structure consists of nodes, where nodes contain subnodes that represent the parent node's properties. Figure 7-1 shows the node structure:

Figure 7-1 JAZN Shell Directory Structure

Text description of the illustration jazdg013.gif

In this structure, the user and role nodes are linked together. Consequently, if you are at /realms/realm/users/user/roles in the tree and type cd role, you are taken to /realms/realm/roles/role.

Another way to look at this, is that role 1 is a symbolic link of role 2.

Figure 7-2 shows nodes of the xmlRealm created by the jazn-data.xml file in "Sample jazn-data.xml Code".

Figure 7-2 Illustrated Shell Directory Structure

Text description of the illustration jazdg014.gif

The JAZN shell can be recognized by the shell prompt JAZN:>. At any point in time, the prompt indicates which realm the administrator is managing. The following is an example:

JAZN:> cd foo
JAZN:foo> ls

To start the shell, invoke the JAZN Admintool with the -shell option, as follows:

java -jar jazn.jar -shell

JAZN Shell Commands

Shell commands consists of the command options in "Realm Operations" and the following series of UNIX derived commands for viewing the principals and policies in the structured way. Relative and absolute paths are supported for all relevant commands.

Using the ls Command to List JAAS Provider Data

ls [path]

The ls command mirrors its UNIX counterpart and lists the contents of the current directory or node. For example, if the current directory is the root, ls lists all realms. If the current directory is /realm/users, then ls lists all users in the realm. The results of the listing depends on the current directory. The ls command can operate with the * wildcard.

Using the cd Command to Navigate JAAS Provider Data

cd path

The cd command, mirroring its UNIX counterpart, allows users to navigate the directory tree. Relative and absolute path names are supported. To exit a directory, type cd ... Entering cd / returns the user to the root node. An error message is displayed if the specified directory does not exist.

Using the mkdir, mk, or add Command to Create JAAS Provider Data

mkdir directory_name [other_parameter]
mk directory_name [other_parameter]
add directory_name [other_parameter]

The mkdir, mk, and add commands are synonyms of a command that creates a new subdirectory or node in the current directory. For example, if the current directory is the root, it creates a realm. If the current directory is /realm/users, it creates a user. The effect of mkdir depends upon the current directory. Some commands require additional parameters in addition to the name.

Using the rm Command to Remove JAAS Provider Data

rm directory_name 

The rm command mirrors its UNIX counterpart and removes the directory or node in the current directory. For example, if the current directory is the root, it removes the specified realm. If the current directory is /realm/users, it removes the specified user. The effect of rm depends on the current directory. An error message is displayed if the specified directory does not exist.

The rm command can operate with the * wildcard.

Using the pwd Command to Display the Current Shell Working Directory

pwd 

The pwd command displays the current location of the user through the UNIX directory format. Undefined values are left blank in this listing.

Using the help Command to List JAAS Provider Commands

help

The help command displays a list of all valid commands.

Using the man Command to Display Detailed JAAS Provider Commands

man command_option
man shell_command

The man command mirrors its UNIX counterpart and displays more detailed usage information for the specified shell command or JAZN Admintool command option. Where information presented by the man page and this document conflict, this document contains the correct usage for the command.

Using the clear Command to Clear the Screen

clear

The clear command clears the terminal screen by displaying 80 blank lines.

Using the exit Command to Exit the JAZN Shell

exit

The exit command exits the JAZN shell.

Managing LDAP Provider Data with Java Programs

You can manage JAAS provider data by creating Java programs using the JAAS Provider APIs.

This section discusses the JAAS provider in LDAP environments. The emphasis is on Java programming, but it also provides useful information for those using Oracle Enterprise Manager or the JAZN Admintool.

This section contains the following topics:

• About the Sample Java Code

• The JAZNContext and JAZNConfig Classes

• Managing Realms

• Managing Users

• Managing Roles

• Managing Permissions

• Managing JAAS Provider Policy

About the Sample Java Code

Some sample Java programs for managing LDAP environments are provided for you. In the sample code, objects to be modified are presented in bold.

For some of the samples in the following chapters, relationships between samples are discussed after the sample code:

• Chapter 7, "Managing the JAAS Provider" (this chapter)

• Chapter 8, "Developing Secure J2SE Applications"

• Chapter 9, "Developing Secure J2EE Applications"

• Appendix B, "JAAS Provider Standards and Samples"

The types of code sample relationships discussed include the following:

• A sample code example demonstrates creating a realm type, such as an Application Realm. A later sample contains the code for dropping that same Application Realm.

• A sample code example demonstrates setting permissions on a specific application. In a later section, the user granted those permissions is shown starting and running that application.

The JAZNContext and JAZNConfig Classes

The JAZNContext and JAZNConfig classes of the package oracle.security. jazn serve as a starting point for the JAAS provider. The JAZNContext and JAZNConfig classes contain methods such as getPolicy, getProperty, and getRealmManager that automatically retrieve information specific to the current JAAS provider instance.

The JAZNConfig class is designed for use with multiple instances of the JAAS provider.

The following code sample illustrates how JAZNContext or JAZNConfig are used in creating a realm in an LDAP-based environment:

RealmManager realmMgr = JAZNContext.getRealmManager();
...
realm = realmMgr.createRealm("abcRealm", realmInfo);

Managing Realms

After you have installed and configured the required components, you must create realms. A realm is a user community instance maintained by the authorization system. Realms consist of a user manager and role manager, and provides access to an LDAP-based provider environment of users and roles (groups).

This section contains the following topics:

• Realm Creation

• Creating an External Realm

• Creating an Application Realm

• Dropping a Realm

Realm Creation

Realms are created using the createRealm() method of the RealmManager class, which requires the following information:

• The realm name

• The role name (adminRole) given to the administrator. This role can then be granted to others, giving them administrative privileges

• Other properties in name/value pairs, including the location that contains the users and roles of the realm's organization in Oracle Internet Directory

• A user's searchbase property for locating the administrator and any user of the realm. This is required for External Realm and Application Realm.

• A role's searchbase property for locating the administrative role and any role for the realm. This is required for External Realm.

• Optional properties:
  • The administrator name (adminUser), a user with administrative privileges

  • A user object class to use as a filter to search for users

  • A role object class to use as a filter to search for roles

    See Also: "Role-Based Access Control (RBAC)" "Realms" "JAAS Provider Realm and Policy Management" "The JAZNContext and JAZNConfig Classes" "Package oracle.security.jazn.realm" "LDAP-Based Realm Types" for definitions of realm types

Creating an External Realm

An External Realm is an LDAP-based realm that integrates existing user communities (user and role information not currently stored under the JAAS Provider context) with the JAAS provider.

User and role management in an External Realm must be handled by an Oracle Internet Directory tool.

The following code sample creates an External Realm with the objects shown in Table 7-3. The objects to be modified are presented in bold.

Table 7-3 Objects in Sample External Realm Creation Code

Objects	Names
sample organization	abc.com
adminUser (optional)	John.Singh
adminRole	administrator
sample realm name	abcRealm

Example 7-1 External Realm Creation Code

import oracle.security.jazn.spi.ldap.*;
import oracle.security.jazn.*;
import oracle.security.jazn.realm.*;

import java.util.*;

/**
 * Creates an external realm.
 */


public class CreateRealm extends Object
{
    public CreateRealm() {};

    public static void main (String[] args) {
      CreateRealm test = new CreateRealm();
      test.createExtRealm();
    }

    void createExtRealm() {
    Realm realm=null;


 try {
     Hashtable prop = new Hashtable();
     prop.put(Realm.LDAPProperty.USERS_SEARCHBASE,"cn=users,o=abc.com");
     prop.put(Realm.LDAPProperty.ROLES_SEARCHBASE,"cn=roles,o=abc.com");

     // specifying the following LDAP directory object class 
	     // is optional.  When specified, it will
     // be used as a filter to search for users
     prop.put(Realm.LDAPProperty.USERS_OBJ_CLASS,"orclUser");

    // adminUser is optional
     String adminUser = "John.Singh";

     String adminRole = "administrator";

     RealmManager realmMgr = JAZNContext.getRealmManager();

     InitRealmInfo realmInfo = new
          InitRealmInfo(InitRealmInfo.RealmType.EXTERNAL_REALM, adminUser,
          adminRole, prop);
     realm = realmMgr.createRealm("abcRealm", realmInfo);
     } 

catch (Exception e) {
     e.printStackTrace();
    }
  }
}

Creating an Application Realm

An Application Realm is an LDAP-based realm that supports external read-only users and internal role management.

The code for creating an Application Realm is similar to the code for creating an External Realm, with the following exceptions:

• The property name for InitRealmInfo.RealmType is APPLICATION_REALM

• An Application Realm does not need to include the setting to search for roles as defined in prop.put(Realm.LDAPProperty.ROLES_SEARCHBASE, "cn=roles,o=defaultOrganization");

  See Also: "Supplementary Code Sample: Creating an Application Realm" for a complete code sample

  Note: If both adminUser and adminRole exist, then adminRole is granted to adminUser, using RBAC.

Dropping a Realm

The RealmManager class of package oracle.security.jazn.realm enables you to drop a realm.

The following code sample shows how to drop a realm:

RealmManager realmMgr = JAZNContext.getRealmManager();
	realmMgr.dropRealm("abcRealm");

The JAAS provider administrator and the realm administrator both have permission to drop a realm.

Managing Users

You cannot create or manage users directly in the JAAS provider if you are using an LDAP-based provider type. For those tasks, use an Oracle Internet Directory tool.

You can add users to a realm using the realm's UserManager interface, as shown in the following code:

UserManager usermgr = realm.getUserManager();
RealmUser user = usermgr.getUser("Chitra.Kumar");

See Also: Oracle Internet Directory Administrator's Guide for information on using Oracle Internet Directory tools

Managing Roles

The RoleManager interface provides methods to manage roles. Table 7-4 describes some of the methods available with the RoleManager interface.

Table 7-4 RoleManager Methods

Method	Description	Available to These Realms
createRole	Creates a role in a realm	Application Realm
grantRole	Grants a role to a RealmPrincipal	Application Realm
dropRole	Drops either named roles or a role given in the instance	Application Realm
getRoles	Gets roles in a realm	All realms
revokeRole	Revokes a role from a RealmPrincipal	Application Realm

Managing roles requires getting the realm from the RealmManager as described in "The JAZNContext and JAZNConfig Classes". After that, you get an instance of the RoleManager interface with the method you are calling.

This section contains these topics:

• Creating Roles

• Granting Roles

• Dropping Roles

  Note: You can internally create, grant, drop, and revoke roles in an Application Realm using the RoleManager interface. However, in an External Realm, you cannot use the RoleManager interface. Roles can be created, granted, dropped, and revoked with an Oracle Internet Directory tool.

Creating Roles

Roles are created either externally in an External Realm with an Oracle Internet Directory tool or internally in an Application Realm with RoleManager.

The following code sample shows how to create a role with RoleManager:

RoleManager rolemgr = realm.getRoleManager();
RealmRole role = rolemgr.createRole("devManager_role");

Granting Roles

You can grant roles in an Application Realm, but not in an External Realm.

Roles are granted by an instance of RoleManager.

These lines show how to grant a role:

RoleManager rolemgr = realm.getRoleManager();
...
rolemgr.grantRole(user, director_role);

These lines are key to the sample code show in Example 7-2.

This sample code demonstrates granting a role, manager_role, to another role, director_role, and granting the director_role to a user, Chitra.Kumar. Consequently, Chitra is granted the director_role directly, and the manager_role indirectly.

The objects to be modified are presented in bold.

Table 7-5 Objects in Sample Granting Roles Code

Objects	Names	Comments
Realm	devRealm	devRealm appears in this code and in the creation of the sample Application Realm which can be viewed in Example 15-3.
RealmUser user	Chitra.Kumar
RealmRole	director_role
RealmRole	manager_role
sample organization	dev.com	dev.com does not appear in this code directly, but was acted upon in the creation of the sample Application Realm which can be viewed in Example 15-3 .

Example 7-2 Granting Roles Code Sample

import oracle.security.jazn.spi.ldap.*;
import oracle.security.jazn.*;
import oracle.security.jazn.realm.*;
import java.util.*;

public class GrantRole extends Object
{
  public GrantRole() {}
  public static void main (String[] args)
  {
      GrantRole test = new GrantRole();
      test.grantRole();
   
  }

    
    void grantRole() {
	try {
	   
	    RealmManager realmMgr = JAZNContext.getRealmManager();
	    Realm realm = realmMgr.getRealm("devRealm");
	    RoleManager rolemgr = realm.getRoleManager();
	    RealmRole manager_role = rolemgr.getRole("manager_role");
	    RealmRole director_role = rolemgr.getRole("director_role");
	    UserManager usermgr = realm.getUserManager();
		    RealmUser user = usermgr.getUser("Chitra.Kumar");
	    
	    /* grants manager_role to director_role */
	    rolemgr.grantRole( director_role, manager_role);
	    
	    /* grants director_role to Chitra */
	    rolemgr.grantRole( user, director_role); 
	    }

	catch (JAZNException e) {
	    System.out.println("Exception "+e.getMessage());

    	}
	  }
}

Dropping Roles

The following code sample shows how to drop a role with RoleManager:

RoleManager rolemgr = realm.getRoleManager();
rolemgr.dropRole("devManager_role");

Managing Permissions

Permissions are extended from the java.security.Permission class. The JAAS provider provides four classes of permissions representing types of actions that can be performed. See Table 4-2 for the list of permissions.

Permissions are all created with constructors such as the following RealmPermission:

RealmPermission Perm1 = new RealmPermission("devRealm", "createRole");

See Also: The following for further information on permissions: "What is the Java2 Security Model?" "What is the Java2 Security Model?" Java Security documentation by visiting the following URL: http://java.sun.com/j2se/1.3/docs/guide/security/

Managing JAAS Provider Policy

JAAS provider policy grants permissions to principals, such as users and roles. The policy can be modified after initialization to grant and revoke permissions to grantees.

Managing Policy with JAAS Provider Packages

These lines of code are key to the sample class shown in "Modifying User Permissions Code".

final JAZNPolicy policy = JAZNContext.getPolicy(); 
...  
policy.grant(new Grantee(propset, cs), new

         FilePermission("report.data", "read"));

Managing XML-Based Provider Data with the XML Schema

You can manage JAAS provider data by modifying XML files used by the JAAS Provider APIs.

This section discusses the JAAS provider in XML-based provider environments. The emphasis is on data files that you create yourself based on the XML schema, but it also provides useful information for those using the JAZN Admintool.

The XML-based environment provides fast, simple, lightweight JAAS provider management. You can use an XML file (named jazn-data.xml in this example) to manage the JAAS provider realm and policy information. Table 7-6 describes the sections of the jazn-data.xml file.

Table 7-6 Description of jazn-data.xml File

Section	This section enables you to:
Realm data	Create realms, users, and roles Grant roles to users and to other roles
Policy data	Assign permissions to users and roles defined in the realm data section of the file

The jazn-data.xml file is specified as follows:

• For J2SE: in the jazn.xml configuration file

• For J2EE: in the orion-application.xml configuration file

  See Also: Oracle9i Application Server Security Guide for configuration information on these two XML files

Managing Realms, Users, Roles, and Permissions

XML realm and provider information is stored in an XML file typically named jazn-data.xml. To work correctly, the XML file must conform to specific policy schema and DTD standards.

See Also: "Sample jazn-data.xml Code" to view an XML Schema and a sample jazn-data.xml file

DTD Standard for XML Datafiles

The XML data file must conform to the following DTD:

<!ELEMENT jazn-data (jazn-realm?, jazn-policy?, jazn-permission-classes?, 
jazn-principal-classes?, jazn-loginconfig?)>

<!-- Realm Data -->

<!ELEMENT jazn-realm (realm*)>
<!ELEMENT realm (name, users?, roles?, jazn-policy?)>
<!ELEMENT users (user*)>
<!ELEMENT user (name, display-name?, description?, credentials?)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT display-name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT credentials (#PCDATA)>
<!ELEMENT roles (role*)>
<!ELEMENT role (name, display-name?, description?, members)>
<!ELEMENT members (member*)>
<!ELEMENT member (type, name)>
<!ELEMENT type (#PCDATA)>

<!-- Policy Data -->

<!ELEMENT jazn-policy (grant*)>
<!ELEMENT grant (grantee, permissions?)>
<!ELEMENT grantee (display-name?, principals?, codesource?)>
<!ELEMENT principals (principal*)>
<!ELEMENT principal (realm-name?, type?, class, name)>
<!ELEMENT realm-name (#PCDATA)>
<!ELEMENT codesource (url)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT permissions (permission+)>
<!ELEMENT permission (class, name, actions?)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT actions (#PCDATA)>

<!-- Principal Class Data -->

<!ELEMENT jazn-principal-classes (principal-class*)>
<!ELEMENT principal-class (name, description?, type, class, 
name-description-map?)>
<!ELEMENT name-description-map (name-description-pair*)>
<!ELEMENT name-description-pair (name, description?)>

<!-- Permission Class Data -->

<!ELEMENT jazn-permission-classes (permission-class*)>
<!ELEMENT permission-class (name, description?, type, class, target-descriptors, 
action-descriptors?)>
<!ELEMENT target-descriptors (target-descriptor*)>
<!ELEMENT target-descriptor (name, description?)>
<!ELEMENT action-descriptors (action-descriptor*)>
<!ELEMENT action-descriptor (name, description?)>

<!-- Login Module Data -->

<!ELEMENT jazn-loginconfig (application*)>
<!ELEMENT application (name, login-modules)>
<!ELEMENT login-modules (login-module+)>
<!ELEMENT login-module (class, control-flag, options?)>
<!ELEMENT control-flag (#PCDATA)>
<!ELEMENT options (option+)>
<!ELEMENT option (name, value)>
<!ELEMENT value (#PCDATA)> 

Other Utilities

There are three additional utilities for managing the JAAS provider. These classes work with both LDAP-based and XML-based provider types. The classes can be used and managed programmatically. Additionally, two can be managed through the JAZN Admintool.

• PermissionClassManager - Integrates with the JAZN Admintool

• PrincipalClassManager - Integrates with the JAZN Admintool

• LoginModuleManager - Works only with J2EE applications and is not activated with the JAZN Admintool

PermissionClassManager Interface

The PermissionClassManager is a repository of all registered Permission classes and a utility to help manage them. Registering a permission class allows access to stored metadata that provides specific information about a given permission's target, action, and/or description. Failure to register a given permission class does not affect the JAAS provider's ability to use the permission class. That is, the JAAS provider does not limit permission grants or revocations to those classes registered with the PermissionClassManager.

Works with the JAZN Admintool to perform these functions:

• "Adding and Removing Permissions"

• "Listing Permissions"

  See Also: "PermissionClassManager" to view the API

PrincipalClassManager Interface

PrincipalClassManager represents the repository of all registered Principal classes and a utility to help manage them. Registering a principal class allows access to stored metadata that provides specific information about a given principal's name and description. Failure to register a given principal class will not affect the JAAS provider's ability to use the principal class. That is, the JAAS provider recognizes all principal classes whether or not they've been registered with the PrincipalClassManager.

The PrincipalClassManager works with the JAZN Admintool to perform these functions:

• "Adding and Removing Principals"

• "Listing Principal Classes"

  See Also: "PrincipalClassManager" to view the API

LoginModuleManager

LoginModuleManager is the JAAS Provider implementation of the JAAS Configuration class and provides login configuration support to applications. The Configuration class is a registry of applications and corresponding login modules used by a given application and the order they are to be used. There are both LDAPLoginModuleManager and XMLLoginModuleManager implementations of the LoginModuleManager.