B JAZN Admintool Reference

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]

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:

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

  java -jar jazn.jar -user username -password password -listrealms
  

  
  

  Note: If you use the -user and -password options, they must appear before all other options on the command line.

  
  

• Supply a user name and password when prompted by the Admintool, as in:

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

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.

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.

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

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.

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 

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.

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.

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:

• All permissions registered with the JAAS provider PermissionClassManager

• Permissions that are granted to a role when the -role option is used

• Permissions that are granted to a principal

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:

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

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:

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.

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.

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

cd path

cd mydir

clear

exit

help

ls [path]

man command_option
man shell_command

pwd 

rm directory_name 

set name=value

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 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 Illustrated Shell Directory Structure"