Skip Headers
Oracle® Application Server Containers for J2EE Security Guide
10g Release 2 (10.1.2)
B14013-02
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

B JAZN Admintool Reference

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 ORACLE_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 appendix is a central reference for how to perform common administration tasks using the JAZN Admintool (in some cases repeating information from earlier in this manual). It is divided into the following sections:

Introduction to JAZN Admintool Command-Line Options and Syntax

This section introduces JAZN Admintool options, grouped according to function, and their syntax. The options are described in greater detail later in the appendix.

The overall syntax for the Admintool is as follows:

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

Note:

If you use one or more of the -user, -password, and -clustersupport options, you must specify them before all other options on the command line.

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 the following example:

java -jar jazn.jar -help

Admintool Authentication (XML-Based Provider Only)

-user username password password

Clustering Operations

-clustersupport oracle_home

Configuration Operations

-getconfig 

Interactive Shell

-shell

Login Modules

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

Migration Operations

-convert filename realm

Password Management

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

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_class [permission_params] 
-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] 

Realm Options

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

Help

-help  [command_name]

To display help for a specific command.

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

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

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

Cautions:

  • Although it is possible to supply the user name and password on the command line with -user and -password, we recommend that you avoid this; specifying passwords on command lines creates security vulnerabilities.

  • 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 tool can perform Admintool operations against the Oracle Internet Directory server. This means that it is vital to secure access to any production machine 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.


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 action and target lists of the permission.

For instance, to create permission to drop a realm:

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

To delete the droprealm permission:

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 (XML-Based Provider Only)

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


Note:

If you use the -clustersupport option, it must appear before all other options on the command line.

For example:

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

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

Use the JAZN Admintool to add and remove login modules.

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.


See Also:


Table B-1 Login Module 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 example, to add MyLoginModule to the application myapp as a required module with debug set to true:

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

To delete MyLoginModule from myapp:

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 principal_name principal_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 parameter list of the principal.

For example, to add the principal staff:

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 or 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 use 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:

java -jar jazn.jar -addrole foo fooRole

To delete the role from the realm:

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:

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

    jazn -jar jazn.jar -adduser foo martha -null
    
    
  • If you use 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 user name and password pair are correct, or "Unsuccessful verification of user/password pair" if the user name 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:

java -jar jazn.jar -getconfig

Admintool shell:

JAZN:> getconfig foo

Granting and Revoking Permissions

-grantperm {realm {-user user|-role role} | principal_class principal_parameters}
            permission_class [permission_parameters]
-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]

In this syntax, principal_class is the fully qualified name of a class that implements the principal interface (such as com.sun.security.auth.NTDomainPrincipal) and principal_parameters 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 the explicit class name of a permission (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:

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:

java -jar jazn.jar -grantrole editor foo martha

Admintool shell:

JAZN:> grantrole editor foo martha

Listing Login Modules

-listloginmodules [application_name] [login_module_class]

Use the JAZN Admintool to list login modules.


See Also:


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

The -listloginmodules option displays all login modules, 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 login modules or the application myapp:

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:

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

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 display name, class, description, actions, and targets.

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

java -jar jazn.jar -listperm perm1

Typical output might look like the following:

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:

java -jar jazn.jar -listprncpl martha

In this 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:

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:

For example, to list all roles in realm foo:

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:

For example, to list all users in realm foo:

java -jar jazn.jar -listusers foo

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

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

The Admintool lists users one to a line:

scott
admin
anonymous

Admintool shell:

To list all users in the realm foo:

JAZN:> listusers foo

Migrating Principals from the principals.xml File

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

    JAZN> addrealm principals.com u1 welcome r1
    
    
  3. Migrate principals.xml to the principals.com realm, as in the following example:

    java -jar jazn.jar -convert config/principals.xml principals.com
    
    
  4. Change the <default-realm> to principals.com, as discussed in "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:

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:

Multiple-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 user name and password to the Admintool, as discussed in "Authentication and the JAZN Admintool (XML-Based Provider Only)" . If you use the LDAP-based provider, you do not need to specify the -user and -password arguments.

JAZN Admintool Shell Commands

The Admintool shell supports UNIX-like commands for navigating within a JAZN structure. All the Admintool commands support relative and absolute paths. This section documents command syntax.


See Also:


The Admintool navigation commands are: add, cd, clear, exit, help, ls, man, pwd, rm, and set.

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 navigate to a directory mydir:

cd mydir

The command "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 properties of the parent node. Figure B-1 illustrates the node structure.

Figure B-1 JAZN Shell Directory Structure

Description of Figure B-1  follows
Description of "Figure B-1 JAZN Shell Directory Structure"

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 Configuration".

Figure B-2 Illustrated Shell Directory Structure

Description of Figure B-2  follows
Description of "Figure B-2 Illustrated Shell Directory Structure"