C OracleAS JAAS Provider Admintool Reference

This chapter provides reference information for the OracleAS JAAS Provider Admintool. It is divided into the following sections:

• Authentication to Run the Admintool

• Summary of Admintool Command-Line Syntax and Options

• Admintool Shell

• Admintool Administrative Functions

See Also: "Overview of the OracleAS JAAS Provider Admintool"

Authentication to Run the Admintool

Run the Admintool by executing the OracleAS JAAS Provider jazn.jar file using the java -jar option.

When you run the Admintool, you must authenticate yourself, optionally using the -user and -password command-line options. You can authenticate yourself in one of two ways:

• The recommended way is to not supply -user and -password settings on the command line; Admintool will then prompt you for a user name and password:

  % java -jar jazn.jar ... 
  AbstractLoginModule username: username
  AbstractLoginModule password: password
  ...
  
  

  In this mode, any options you specify are executed only after you have been prompted for and have supplied the user name and password. For example:

  % java -jar jazn.jar -listrealms
  
  

  When an example such as this is presented in this appendix, what is left unsaid is that you will be prompted for the user name and password before the command is executed (in this example, before the realms are listed).

• Alternatively, you can use the -user and -password options on the command line:

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

  This is generally undesirable, because specifying passwords on command lines creates security vulnerabilities.

  In this mode, a command such as the following would immediately list the realms:

  % java -jar jazn.jar -user myname -password mypassword -listrealms
  

  
  

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

  
  

In either of these modes, once the options you specify on the command line have been executed, you are returned to your system prompt. To execute any further Admintool commands, you will have to rerun the tool and be authenticated again.

To run multiple commands without reauthenticating, you can use the Admintool shell mode, where you can repeatedly run commands from the Admintool prompt until you exit the shell, as described in "Admintool Shell".

Summary of Admintool Command-Line Syntax and Options

The Admintool provides a number of command options for administrative functions. The general syntax is as follows:

% java -jar jazn.jar [-user username -password password] [option1 option2 ... ]

Important: If you use the -user and -password options (which is not recommended, as discussed in the preceding section), you must specify them before all other options on the command line. Restart OC4J for Admintool changes to take effect.

This section lists all the Admintool command options, with cross-references for further information. You can also list all the options and their syntax with the -help option:

% java -jar jazn.jar -help

Command line options are summarized below:

• Administrative option

  -activateadmin
  

  
  

  See Also: "Administrative Operations"

  
  

• Authentication options

  -user username -password password
  

  
  

  See Also: "Authentication to Run the Admintool"

  
  

• Login module options

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

  
  

  See Also: "Adding and Removing Login Modules" "Listing Login Modules"

  
  

• Migration option

  -convert filename realm
  

  
  

  See Also: "Converting from the principals.xml File to JAAS"

  
  

• Password management options (file-based provider only)

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

  
  

  See Also: "Checking Passwords (File-Based Provider)" "Setting Passwords (File-Based Provider)"

  
  

• Policy options

  -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]
  -revokeperm {realm {-user user|-role role} | principal_class principal_params}
               permission_class [permission_params] 
  

  
  

  See Also: "Granting and Revoking Permissions" "Listing Permissions"

  
  

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

  
  

  See Also: "Adding and Removing Realms" "Adding and Removing Roles (File-Based Provider)" "Adding and Removing Users (File-Based Provider)" "Granting and Revoking Roles" "Listing Realms" "Listing Roles" "Listing Users"

  
  

• Shell option

  -shell
  

  
  

  See Also: The next section, "Admintool Shell"

  
  

Admintool Shell

The Admintool shell provides interactive administration of JAAS principals and policies through a UNIX-like interface. The -shell option starts the shell. For example (entering oc4jadmin user and password when prompted):

% java -jar jazn.jar -shell
AbstractLoginModule username: oc4jadmin
AbstractLoginModule password: password
JAZN> 

The shell responds with the JAZN> prompt. To leave the interface shell, use the exit shell command. To see a list of shell commands, use the help command. For information about a particular shell command, the shell supports the man command:

JAZN> man command

Note: Multiple-word arguments must be enclosed in quotation marks. For example: % java -jar jazn.jar -user "Oracle DBA" ...

The rest of this discussion covers the following topics:

• Shell Support for Admintool Command-Line Options

• Summary of Admintool Special Shell Commands

• Admintool Shell Directory Structure

Shell Support for Admintool Command-Line Options

The Admintool shell supports the same options as the Admintool command line, but you do not have to include the hyphen ("-") in front of the option name. (If you do, it will be ignored.) Once you have launched the Admintool shell, a shell command line such as the following:

JAZN> option1 option2 ... optionN

Is equivalent to an Admintool command line (from your system prompt) such as the following:

% java -jar jazn.jar -option1 -option2 ... -optionN

Admintool Shell Directory Structure

The Admintool shell is an interactive interface to the OracleAS JAAS Provider API.

The shell directory structure consists of nodes, where nodes contain subnodes that represent properties of the parent node. Figure C-1 illustrates the node structure.

Figure C-1 Admintool Shell Directory Structure

Description of "Figure C-1 Admintool 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 C-2 shows nodes of a realm abcRealm.

Figure C-2 Sample Shell Directory Structure

Description of "Figure C-2 Sample Shell Directory Structure"

Summary of Admintool Special Shell Commands

This section summarizes the following Admintool shell commands:

• add, mkdir, and mk: Creating Provider Data

• cd: Navigating Provider Data

• clear: Clearing the Screen

• exit: Exiting the Admintool Shell

• help: Listing Admintool Shell Commands

• ls: Listing Data

• man: Viewing Admintool man Pages

• pwd: Displaying the Working Directory

• rm: Removing Provider Data

• set: Updating Values

All the Admintool commands support relative and absolute paths.

add, mkdir, and mk: 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 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.

The path "/" 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 Admintool Shell

exit

The exit command exits the Admintool shell.

help: Listing Admintool Shell Commands

help

The help command displays a list of all valid shell 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 Admintool man Pages

man command_option
man shell_command

The man command displays detailed usage information for the specified shell command or 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 Administrative Functions

This section documents administrative features of the Admintool. The following topics are covered:

• Adding and Removing Login Modules

• Adding and Removing Realms

• Adding and Removing Roles (File-Based Provider)

• Adding and Removing Users (File-Based Provider)

• Checking Passwords (File-Based Provider)

• Administrative Operations

• Granting and Revoking Permissions

• Granting and Revoking Roles

• Listing Login Modules

• Listing Permissions

• Listing Realms

• Listing Roles

• Listing Users

• Converting from the principals.xml File to JAAS

• Setting Passwords (File-Based Provider)

Adding and Removing Login Modules

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

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

The control_flag must be one of required, requisite, sufficient or optional, as specified in the standard javax.security.auth.login.Configuration class. The meanings of these flag values are summarized in "Editing a Custom Login Module Configuration during Deployment".

If the login module accepts its own options, specify each option and its value as an optionname=value pair. Each login module 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 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 file-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

The administrator would delete employees as follows:

% java -jar jazn.jar -remrealm employees

Admintool shell:

JAZN> addrealm employees martha mypass hr
JAZN> remrealm employees

Adding and Removing Roles (File-Based Provider)

-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> addrole foo fooRole
JAZN> remrole foo fooRole

Adding and Removing Users (File-Based Provider)

-adduser realm username password
-remuser realm username

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

It is recommended that you add users through the Admintool shell instead of on the command line, as in the following example:

% java -jar jazn.jar -shell
AbstractLoginModule username : oc4jadmin
AbstractLoginModule password : adminpassword
JAZN> adduser jazn.com my_user my_password

Entering a user on the Admintool command line is less secure. For example, on a UNIX system, any other user on the system could see the password by using the "ps -ef" command to list all processes. By contrast, commands entered in the Admintool shell are read only by the Admintool.

However, adding a user on the command line is supported as well. For example, to add the user martha to the realm foo with the password mypass:

% java -jar jazn.jar -adduser foo martha mypass 

To insert a user with no password, end the command line with the -null option:

jazn -jar jazn.jar -adduser foo martha -null

To delete martha from the realm:

% java -jar jazn.jar -remuser foo martha

Admintool shell:

JAZN> adduser foo martha mypass
JAZN> remuser foo martha

Checking Passwords (File-Based Provider)

-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 tis principal" if the user has no password.

When you specify -checkpasswd together with a -pw parameter for a password, 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 user name or password is incorrect.

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

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

Admintool shell:

JAZN> checkpasswd foo martha -pw Hello

Administrative Operations

-activateadmin

Use the -activateadmin option to activate the oc4jadmin account (formerly admin) in the default realm, and to set its password. (This account is initially deactivated for the file-based provider in standalone OC4J.)

% java -jar jazn.jar -activateadmin password

Admintool shell:

JAZN> activateadmin password

Note: The -activateadmin command is a one-time command. If the administrative account is already active, an error will be thrown to indicate that.

Granting and Revoking Permissions

-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]
-revokeperm {realm {-user user|-role role} | principal_class principal_params}
             permission_class [permission_params] 

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

Note: If the Admintool gives the error message "Permission class not found," it means that the permission you wish to grant is not in the classpath. You must place the JAR containing the permission class in the jdk/jre/lib/ext directory so the Admintool can locate it.

For example, to grant RuntimePermission to the principal LDAPPrincipal (with principal parameter hobbes and permission parameter getProtectionDomain, values that are understood by LDAPPrincipal):

% java -jar jazn.jar -grantperm oracle.security.jazn.realm.LDAPPrincipal hobbes
     java.lang.RuntimePermission getProtectionDomain

As another 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

To revoke the permission:

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

Admintool shell:

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

Granting and Revoking Roles

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

Or, to grant the role financial to the role finreporter:

% java -jar jazn.jar -grantrole financial foo -role finreporter

Admintool shell:

JAZN> grantrole editor foo martha
JAZN> revokerole editor foo martha

Listing Login Modules

-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 for 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_params
            permission_class [permission_params] 

The -listperms option displays all permissions that match the list criteria, as follows:

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

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

• Permissions that are granted to a principal

Important: PermissionClassManager and related classes and operations, including -listperms, are deprecated in the OC4J 10.1.3 implementation and will be desupported in a future release.

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 Realms

-listrealms [realm]

The -listrealms option displays all realms in the current JAAS environment; or, if a realm argument is specified, the option lists only that 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

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

scott
admin
anonymous

Admintool shell:

JAZN> listusers foo

Converting from the principals.xml File to JAAS

-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). For example:

% java -jar jazn.jar \
       -convert $ORACLE_HOME/j2ee/home/config/principals.xml jazn.com

Admintool shell:

JAZN> convert ORACLE_HOME/j2ee/home/config/principals.xml jazn.com

See Also: "Migrating Principals from the principals.xml File" for important additional information

Setting Passwords (File-Based Provider)

-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