B Using the JAZN Admintool

The JAZN Admintool can manage both XML-based and LDAP-based JAAS configurations and 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 an interactive shell. The JAZN Admintool is located in OC4J_HOME/j2ee/home/jazn.jar.

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

This chapter discusses how to perform common administration tasks using the JAZN Admintool. It is divided into the following sections:

• Authentication and the JAZN Admintool (XML-based Provider Only)

• JAZN Admintool Command-Line Options

• Adding and Removing Policy Permissions (XML-based Provider Only)

• Adding Clustering Support

• Adding and Removing Login Modules (XML-based Provider Only)

• Adding and Removing Principals (XML-based Provider Only)

• Adding and Removing Realms

• Adding and Removing Roles (XML-based Provider Only)

• Adding and Removing Users (XML-based Provider Only)

• Checking Passwords (XML-based Provider Only)

• Configuration Operations

• Granting and Revoking Permissions

• Granting and Revoking Roles

• Listing Login Modules

• Listing Permissions

• Listing Permission Information

• Listing Principal Classes

• Listing Principal Class Information

• Listing Realms

• Listing Roles

• Listing Users

• Migrating Principals from the principals.xml File

• Setting Passwords (XML-based Provider only)

• Using the JAZN Admintool Shell

Authentication and the JAZN Admintool (XML-based Provider Only)

If you are using the XML-based provider, you must authenticate yourself to the JAZN Admintool before making administrative changes. You authenticate yourself in one of two ways:

• Supplying the -user and -password switches, as in:

  java -jar jazn.jar -user myusername -password mypassword -listrealms
  

  
  

  Note: If you specify the -user, -password, or -clustersupport options, you must specify them before all other options on the command line.

  
  

• Supplying a username and password when prompted by the Admintool, as in:

java -jar jazn.jar -listrealms 
>RealmLoginModule username: martha
>RealmLoginModule password: mypass

Cautions: Because of Java limitations, the password you type to the Admintool may be visible in the command window. Be sure to close the command window after using the Admintool. The Admintool does not require authentication when used with the LDAP-based provider; anyone who runs the toolcan perform Admintool operations against the Oracle Internet Directory server. This means that it is vital to secure access to the production machine(s) on which OC4J uses the LDAP-based provider. If you specify the -user and -password options when using the LDAP-based provider, they are ignored.

JAZN Admintool Command-Line Options

The JAZN Admintool provides the following command options, described in greater detail in the following sections. The tool prints error messages if the syntax or parameters are incorrect. You can list all the options and their syntax with the -help option, as in:

java -jar jazn.jar -help

Syntax

The overall syntax for the Admintool is

java -jar jazn.jar [-user username -password mypassword
  -clustersupport ORACLE_HOME] [otheroptions] 

Note: If you are using the -user, -password, or -clustersupport options, you must specify them before all other options on the command line.

This section lists all the Admintool command options.

Admintool Authentication (XML-based Provider Only)

-user username -password mypassword

See "Authentication and the JAZN Admintool (XML-based Provider Only)".

Clustering Operations

-clustersupport oracle_home

See "Adding Clustering Support".

Configuration Operations

-getconfig 

See "Configuration Operations".

Interactive Shell

-shell

See "Using the JAZN Admintool Shell".

Login Modules

-addloginmodule application_name login_module_name    control_flag [options] 
-listloginmodules [application_name] [login_module_class]
-remloginmodule application_name login_module_name 

See "Adding and Removing Login Modules (XML-based Provider Only)" and "Listing Login Modules".

Migration Operations

-convert filename realm

See "Migrating Principals from the principals.xml File".

Miscellaneous

-help  [command name]

To display help for a specific command.

Password Management (XML-based Provider only)

-checkpasswd realm user [-pw password] 
-setpasswd realm user old_pwd new_pwd 

See "Checking Passwords (XML-based Provider Only)" and "Setting Passwords (XML-based Provider only)".

Policy Operations

-addperm permission permission_class action target [description] 
-addprncpl principlename principle_class parameters [description]
-grantperm {realm {-user user|-role role} | principal_class  
         principal_params} permission_class [permission_params] 
-listperms [{realm {-user user |-role role} | 
         principal_class principal_params | permission_name] 
-listperm permission
-listprncpls [principal_name ]
-listprncpl principal_name 
-remperm permission 
-remprncpl principal_name
-revokeperm {realm {-user user|-role role} | principal_class 
         principal_params} permission_class [permission_params] 

See "Adding and Removing Policy Permissions (XML-based Provider Only)", "Adding and Removing Principals (XML-based Provider Only)", "Granting and Revoking Permissions", "Listing Permissions", "Listing Permission Information", "Listing Principal Classes", and"Listing Principal Class Information".

Realm Operations

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

See "Adding and Removing Realms", "Adding and Removing Roles (XML-based Provider Only)", "Adding and Removing Users (XML-based Provider Only)", "Granting and Revoking Roles", "Listing Realms", "Listing Roles", and "Listing Users".

Adding and Removing Policy Permissions (XML-based Provider Only)

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

The -addperm option registers a permission with the JAAS Provider PermissionClassManager. The -remperm option removes registration for the specified permission class. To supply multiple words in the permission or description arguments, enclose them in quotation marks ("three word permission").

If you add a permission that already exists, the Admintool updates the permission's action and target lists.

For instance, to create permission to drop a realm, type:

java -jar jazn.jar -addperm perm1 oracle.security.jazn.realm.RealmPermission droprealm "permission to drop a realm"

To delete the droprealm permission, type:

java -jar jazn.jar -remperm perm1

Admintool shell:

JAZN:> addperm perm1 oracle.security.jazn.realm.RealmPermission droprealm -null "permission to drop a realm" 
JAZN: remperm perm1

Adding Clustering Support

-clustersupport oracle_home

Specifying this option instructs the Admintool to propagate all JAAS configuration changes throughout a cluster. The oracle_home argument specifies the absolute path name of $ORACLE_HOME, the Oracle home directory. You can combine -clustersupport with the -shell option.

Notes: If you are using the -clustersupport option, you must specify it before all other options on the command line. The -clustersupport option is meaningful only when using the XML-based provider.

For example:

java -jar jazn.jar -clustersupport /oracle_home -shell

Adding and Removing Login Modules (XML-based Provider Only)

You use the JAZN Admintool to add and remove login modules. For basic information on running the JAZN Admintool, see "Admintool Overview" .

java -jar jazn.jar -addloginmodule application_name login_module_name    control_flag [optionname=value ...] 
 java -jar jazn.jar -remloginmodule application_name login_module_name 

The -addloginmodule option configures a new LoginModule for the named application.

The control_flag must be one of required, requisite, sufficient or optional, as specified in javax.security.auth.login.Configuration. See Table B-1.

Table B-1 LoginModule Control Flags

Flag	Meaning
Required	The LoginModule must succeed. Whether or not it succeeds, authentication proceeds down the LoginModule list.
Requisite	The LoginModule must succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not continue down the LoginModule list).
Sufficient	The LoginModule is not required to succeed. If it succeeds, control immediately returns to the application and authentication does not proceed down the LoginModule list. If it fails, authentication continues down the LoginModule list.
Optional	The LoginModule is not required to succeed. Whether or not it succeeds, authentication proceeds down the LoginModule list.

If the LoginModule accepts its own options, you specify each option and its value as an optionname=value pair. Each LoginModule has its own individual set of options.

For instance, to add MyLoginModule to the application myapp as a required module with debug set to true, type:

java -jar jazn.jar -addloginmodule myapp MyLoginModule required debug=true

To delete MyLoginModule from myapp, type:

java -jar jazn.jar -remloginmodule myapp MyLoginModule

Admintool shell:

JAZN:> addloginmodule myapp MyLoginModule required debug=true 
JAZN: remloginmodule myapp MyLoginModule

Adding and Removing Principals (XML-based Provider Only)

-addprncpl principlename principle_class parameters [description] 
-remprncpl principal_name

The -addprncpl option registers a principal with the JAAS Provider PrincipalClassManager. The -remprncpl option removes registration for the specified principal class. To supply multiple words in the principal_name and description arguments, enclose them in quotation marks ("three word description").

If you add a principal that already exists, the Admintool updates the principal's parameter list.

For example, to add the principal staff, type:

java -jar jazn.jar -addprincpl staff oracle.security.jazn.spi.xml.XMLRealmUser
  "a staff user"

Admintool shell:

JAZN:> addprincpl staff oracle.security.jazn.spi.xml.XMLRealmUser -null "a staff user"

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.

For example, using the XML-based Provider, the administrator martha with password mypass using role hr would add the realm employees as follows:

java -jar jazn.jar -addrealm employees martha mypass hr

Using the LDAP-based Provider, the administrator martha using role hr would add the realm employees to userbase ub and rolebase rb in an external realm as follows:

java -jar jazn.jar -addrealm employees martha hr ub rb external

Note: The realmtype argument is required only when using the LDAP-based Provider. The possible values for realmtype are: external application

In either environment, the administrator would delete employees as follows:

java -jar jazn.jar -remrealm employees

Adding and Removing Roles (XML-based Provider Only)

-addrole realm role
-remrole realm role

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

Note: If you are using the LDAP-based provider, -addrole and -remrole are supported only for application realms; they are not supported for external or identity management realms.

For example, to add the role roleFoo to the realm foo, type:

java -jar jazn.jar -addrole foo fooRole

To delete the role from the realm, type:

java -jar jazn.jar -remrole foo fooRole

Admintool shell:

JAZN:> remrole foo fooRole

Adding and Removing Users (XML-based Provider Only)

-adduser realm username password 
-remuser realm user

The -adduser option adds a user to a specified realm; the -remuser option deletes a user from the realm. For example, to add the user martha to the realm foo with the password mypass, type:

java -jar jazn.jar -adduser foo martha mypass 

Notes: To insert a user with no password, end the command line with the -null option, as in: jazn -jar jazn.jar -adduser foo martha -null If you are using the LDAP-based provider, these commands will not work.

To delete martha from the realm, type:

java -jar jazn.jar -remuser foo martha

Admintool shell:

JAZN:> adduser foo martha mypass

Checking Passwords (XML-based Provider Only)

-checkpasswd realm user [-pw password]

The -checkpasswd option indicates whether the given user requires a password for authentication.

When you specify -checkpasswd alone, the Admintool responds "A password exists for this principal" if the user has a password, or "No password exists for this principal" if the user has no password.

When you specify -checkpasswd together with the -pw option, the Admintool responds "Successful verification of user/password pair" if the username and password pair are correct, or "Unsuccessful verification of user/password pair" if username and/or password is incorrect.

For example, to check whether the user martha in realm foo uses the password Hello, type:

java -jar jazn.jar -checkpasswd foo martha -pw Hello

Admintool shell:

JAZN:> checkpasswd foo martha -pw Hello

Configuration Operations

-getconfig

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

For example, to check the configuration settings for the realm foo, type:

java -jar jazn.jar -getconfig

Admintool shell:

JAZN:> getconfig foo

Granting and Revoking Permissions

-grantperm realm {-user user|-role role } | principal_params} permission_class [permission_params] 
-revokeperm realm {-user user|-role role} | principal_class principal_parameters} permission_class [permission_parameters]
-listperms realm {-user user|-role role} | principal_class principal_parameters} permission_class [permission_parameters]

where principal_class is the fully qualified name of a class that implements the principal interface (such as com.sun.security.auth.NTDomainPrincipal) and principal_paramters is a single String parameter.

The -grantperm option grants the specified permission to a user (when called with -user) or a role (when called with -role) or a principal. The -revokeperm option revokes the specified permission from a user or role or principal

A permission_descriptor consists of a permission's explicit class name (for example, oracle.security.jazn.realm.RealmPermission), its action, and its action and target parameters (for RealmPermission, realmname action). Note that there may be multiple action and target parameters.

For example, to grant FilePermission with target a.txt and actions "read, write" to user martha in realm foo, type:

java -jar jazn.jar -grantperm foo -user martha java.io.FilePermission 
 a.txt read, write

Admintool shell:

JAZN:> grantperm foo -user martha java.io.FilePermission a.txt read, write

Granting and Revoking Roles

-grantrole role realm {user|-role to_role} 
-revokerole role realm {user|-role from_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.

Note: If you are using the LDAP-based provider, -grantrole and -revokerole are supported only for application realms; they are not supported for external or identity management realms.

For example, to grant the role editor to the user martha in realm foo, type:

java -jar jazn.jar -grantrole editor foo martha

Admintool shell:

JAZN:> grantrole editor foo martha

Listing Login Modules

-listloginmodules [application_name] [login_module_class]

You use the JAZN Admintool to list login modules. For basic information on running the JAZN Admintool, see "Admintool Overview" .

java -jar jazn.jar -listloginmodules [application_name [login_module_class]]

The -listloginmodules option displays all LoginModules either in the specified application_name , or, if no application_name is specified, in all applications. Specifying login_module_class, after application_name displays information on only the specified class within the application.

For example, to display all LoginModules for the application myapp, type:

java -jar jazn.jar -listloginmodules myapp

Admintool shell:

JAZN:> listloginmodules myapp

Listing Permissions

-listperms realm {-user user|-role role} | principal_class principal_parameters} permission_class [permission_parameters]

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 to a role when the -role option is used.

• Permissions that are grated to a prinicpal.

For example, to display all permissions for the user martha in realm foo, type:

java -jar jazn.jar -listperms foo -user martha

Admintool shell:

JAZN:> listperms foo -user martha

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.

For example, to list all information about the permission perm1, type:

java -jar jazn.jar -listperm perm1

Typical output might look like

Name:
perm1

Class:
oracle.security.jazn.realm.RealmPermission

Description:
permission to drop realm

Targets:

Actions:
droprealm  <no description available>

Admintool shell:

JAZN:> listperm perm1

Listing Principal Classes

-listprncpls principal_name

The -listprncpls option lists all principal classes registered with the PrincipalClassManager. If the principal_name argument is present, only the named principal class is listed.

For example:

java -jar jazn.jar -listprncpls

Admintool shell:

JAZN:> listprncpls

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.

For example, to list all information about the principal martha, type:

java -jar jazn.jar -listprncpl martha

In our example, the output would be:

Name:
martha
Class:
oracle.security.jazn.spi.xml.XMLRealmUser
Description:
a staff user
Parameters:

Admintool shell:

JAZN:> listprncpl martha

Listing Realms

-listrealms [realm]

The -listrealms option displays all realms in the current JAAS environment; if an argument is specified, it lists only the specified realm.

For example, to list all realms, type:

java -jar jazn.jar -listrealms

Admintool shell:

JAZN:> listrealms

Listing Roles

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

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

• 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

For example, to list all roles in realm foo, type:

java -jar jazn.jar -listroles foo 

Admintool shell:

JAZN:> listroles foo 

Listing Users

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

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

• 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

For example, to list all users in realm foo, type:

java -jar jazn.jar -listusers foo

Admintool shell:

JAZN:> listusers foo

For example, to list all users in realm foo using permission bar, type:

java -jar jazn.jar -listusers foo -perm bar

The Admintool lists users one to a line, as in:

scott
admin
anonymous

Migrating Principals from the principals.xml File

You use the JAZN Admintool to migrate your data out of the principals.xml file. For basic information on running the JAZN Admintool, see "Admintool Overview" .

-convert filename realm

The -convert option migrates the principals.xml file into the specified realm of the current OracleAS JAAS Provider. The filename argument specifies the path name of the input file (typically $ORACLE_HOME/j2ee/home/config/principals.xml).

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

An error (either javax.naming.AuthenticationException:Invalid username/password or javax.naming.NamingException:Lookup Error) is returned if the input file contains errors.

Before you convert principals.xml, you must make sure that you have an administrator user that is authorized to manage realms. To do this:

1. Activate the administrative user in principals.xml, which is deactivated by default. Be sure to create a password for the administrator.

   Make sure that the administrator name you used to create the realm is different from the name of the administrator in principals.xml. This is necessary because the convert command does not migrate duplicate users, and migrates duplicate roles by overwriting the old one.

2. Create the realm principals.com with a dummy user and a dummy role. For example, in the Admintool shell you would type:

   JAZN> addrealm principals.com u1 welcome r1
   
   

3. Migrate principals.xml to the principals.com realm, as in

   java -jar jazn.jar -convert config/principals.xml principals.com
   

4. Change the <default-realm> to principals.com; see "Setting Persistence Mode".

5. Stop OC4J and restart it.

Setting Passwords (XML-based Provider only)

-setpasswd realm user old_pwd new_pwd 

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

For example, to change the user martha in realm foo from password mypass to password a2d3vn, type:

java -jar jazn.jar -setpasswd foo martha mypass a2d3vn

Admintool shell:

JAZN:> setpasswd foo martha mypass a2d3vn

Using the JAZN Admintool Shell

-shell  

The -shell option starts a JAZN Admintool shell. The JAZN Admintool shell provides interactive administration of JAAS principals and policies through a UNIX-derived interface.

java -jar jazn.jar -user martha -password mypass -shell
JAZN:> 

The shell responds with the JAZN:> prompt. To leave the interface shell, type exit.

Note: Multi-word arguments must be enclosed in quotes. For example, java -jar jazn.jar -user 'Oracle DBA' ...

If you are using the XML-based provider you must supply a username and password to the Admintool; for details see "Authentication and the JAZN Admintool (XML-based Provider Only)" . If you are using the LDAP-based Provider, you do not need to specify the -user and -password arguments.

Navigating the JAZN Admintool Shell

The Admintool shell supports UNIX-like commands for navigating within a JAZN structure. For a complete discussion of the Admintool directory structure, see "Admintool Shell Directory Structure" . All the Admintool commands support relative and absolute paths.

The Admintool navigation commands are:

add: Creating Provider Data

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

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

cd: Navigating Provider Data

cd path

The cd command enables users to navigate the directory tree. Relative and absolute path names are supported. To exit a directory, type:

cd ..

Typing cd / returns the user to the root node. An error message is displayed if the specified directory does not exist.

clear: Clearing the Screen

clear

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

exit: Exiting the JAZN Shell

exit

The exit command exits the JAZN shell.

help: Listing JAZN Admintool Shell Commands

help

The help command displays a list of all valid commands.

ls: Listing Data

ls [path]

The ls command lists the contents of the current directory or node. For example, if the current directory is the root, then 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.

man: Viewing JAZN Admintool Man Pages

man command_option
man shell_command

The man command displays 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.

pwd: Displaying The Working Directory

pwd 

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

rm: Removing Provider Data

rm directory_name 

The rm command removes the directory or node in the current directory. For example, if the current directory is the root, then rm 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 accepts the * wildcard.

set: Updating Values

set name=value

The set command updates the value of the specified name. For example, use this command to update the login module class, or a login module control flag, or a login module class option, depending on the working directory.

Admintool Shell Directory Structure

The JAZN Admintool includes a shell called the JAZN shell interface. The JAZN shell is 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 B-1 illustrates the node structure.

Figure B-1 JAZN Shell Directory Structure

Description of the illustration jaz013.gif

In this structure, the user and role nodes are linked together. This means that the roles link under user is the same link as the roles link under realm. In Unix terms, the role at numeral 1 in the diagram is a symbolic link to role at numeral 2 in the diagram.

Note: In this release, the policy directory is always empty.

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

Figure B-2 Illustrated Shell Directory Structure

Description of the illustration jaz014.gif