Oracle9iAS Containers for J2EE Services Guide Release 2 (9.0.2) Part Number A95879-01 |
|
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:
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:
-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.
XML-based and LDAP-based JAAS providers enable different functionalities as described in Table 7-2.
JAAS Provider | Description | See Also... |
---|---|---|
Available with the Oracle9iAS Infrastructure installation type) |
Enables you to: |
|
(Available with all installation types |
Enables you to: |
You can use Oracle Enterprise Manager to perform two JAAS provider tasks:
Oracle Enterprise Manager functionality for the JAAS provider is currently only available for the LDAP provider environment and only for policy management tasks.
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:
The System Components panel appears:
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:
To search for and view grant entry data:
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.
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.
For the grant name you have entered, the following data appears:
To delete grant entry data:
To create a new grant entry:
The JAAS Policy Management window appears.
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.
"Policies and Permissions" for information on codesources
See Also:
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:
Text description of the illustration jpolicyd.gif
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.
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.
java.io.FilePermission
).
/home/*
).
/home/*
).
Text description of the illustration jpolicya.gif
The entry is now granted these permissions on the designated target. The grant entry is complete.
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.
To search for permissions on a principal:
The Permission Management window appears:
The available principal types are:
The results display on-screen including permission class, permission target, and permission actions, but the codesource does not appear.
To revoke permissions assigned to a principal:
You can only revoke one permission at a time.
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:
The following examples illustrate the different ways that the JAZN Admintool commands can be used.
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
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
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.
-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
-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
-shell
-getconfig default_realm admin password
-convert filename realm
-help -version
-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:
The user must provide the following:
-addrole realm role -remrole realm role
The -addrole
option creates a role in the specified realm, and -remrole
deletes a role from the realm.
-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.
-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.
-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.
-listrealms
The -listrealms
option displays all realms in the current JAAS provider environments.
-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:
role
, when called with a realm name and the option -role
permission
, when called with a realm name and the option -perm
-listusers [realm [-role role|-perm permission]]
The -listusers
option displays a list of users that match the list criteria. This option lists the following:
-role
or -perm
-setpasswd realm user old_pwd new_pwd
The -setpasswd
option allows administrators to reset the password of a user given the old password.
-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 ("").
-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 ("").
-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.
-listperms realm {user |-role role| realm realm}
The -listperms
option displays all permissions that match the list criteria. This option lists the following:
PermissionClassManager
-role
-listperm permission
The -listperm
option displays detailed information about the specified permission, including the permission's display name, class, description, actions, and targets.
-listprncpls
The -listprncpls
option lists all principal classes registered with the PrincipalClassManager
.
-listprncpl principal_name
The -listprncpl
option displays detailed information about the specified principal, including the display name, class, description, and actions.
-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.
-getconfig default_realm admin password
The -getconfig
option displays the current configuration setting in jazn.xml
.
-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 |
-help
The -help
option displays a list of command options available with the JAZN Admintool.
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:
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".
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
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.
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.
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.
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.
pwd
The pwd
command displays the current location of the user through the UNIX directory format. Undefined values are left blank in this listing.
help
The help
command displays a list of all valid 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.
clear
The clear
command clears the terminal screen by displaying 80 blank lines.
exit
The exit
command exits the JAZN shell.
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:
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:
The types of code sample relationships discussed include the following:
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);
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:
Realms are created using the createRealm()
method of the RealmManager
class, which requires the following information:
adminRole)
given to the administrator. This role can then be granted to others, giving them administrative privileges
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.
Objects | Names |
---|---|
sample organization |
|
|
|
|
|
sample realm name |
|
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(); } } }
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:
InitRealmInfo.RealmType
is APPLICATION_REALM
prop.put(Realm.LDAPProperty.ROLES_SEARCHBASE, "cn=roles,o=
defaultOrganization
");
"Supplementary Code Sample: Creating an Application Realm" for a complete code sample
See Also:
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.
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");
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
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:
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");
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.
Objects | Names | Comments |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
sample organization |
|
|
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()); } } }
The following code sample shows how to drop a role with RoleManager
:
RoleManager rolemgr = realm.getRoleManager(); rolemgr.dropRole("devManager_role");
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:
|
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.
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"));
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.
Section | This section enables you to: |
---|---|
Realm data |
|
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:
jazn.xml
configuration file
orion-application.xml
configuration file
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:
|
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)>
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
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:
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:
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
.
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|