Skip Headers
Oracle® Containers for J2EE Security Guide
10g (10.1.3.5.0)
Part Number E13977-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

C OracleAS JAAS Provider Admintool Reference

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

Notes:

See Also:

Getting Started with the Admintool

This section will help you get started with the OracleAS JAAS Provider Admintool and covers the following topics:

Running the Admintool

Run the Admintool by executing the OracleAS JAAS Provider jazn.jar file using the java -jar option. Either make your current directory the directory where jazn.jar is located, or specify the path to jazn.jar on the Java command line, as in the following example:

% java -jar /myroot/mydir/jazn.jar ...

Note:

The location of jazn.jar is typically: 
ORACLE_HOME/j2ee/home/jazn.jar

By default, the Admintool looks for the jazn.xml configuration file in the config directory under your current directory. You can alter this by directly specifying a location through the oracle.security.jazn.config system property, or by specifying an Oracle home or J2EE home location through the oracle.home property or oracle.j2ee.home property, respectively. The precedence of search locations is described in "The jazn.xml File".

The following example specifies the location of the jazn.xml file:

% java -jar -Doracle.security.jazn.config=/tmp/jazn.xml jazn.jar ...

The next example specifies the J2EE home location, where ORACLE_HOME is the path to the Oracle home directory, and instancename is the name of the OC4J instance (such as home, for example). Based on this, the Admintool will look for jazn.xml in the ORACLE_HOME/j2ee/instancename/config directory:

% java -jar -Doracle.j2ee.home=ORACLE_HOME/j2ee/instancename jazn.jar ...

User Repository Location for the Admintool

When you use the file-based security provider, the jazn.xml file specifies the location of the user repository (system-jazn-data.xml or jazn-data.xml) that the Admintool will use, through the location attribute of the <jazn> element. By default, this is the system-jazn-data.xml file, but you can update the location setting to use an application-specific jazn-data.xml file:

<jazn provider="XML" location="path/jazn-data.xml">
   ...
</jazn>

When you use Oracle Identity Management, the <jazn> location attribute specifies the Oracle Internet Directory location, such as in the example that follows. However, do not manually update the location value when you use Oracle Identity Management; this value is set automatically when you associate the Oracle Internet Directory instance with OC4J through Application Server Control (as described in "Associating Oracle Internet Directory with OC4J"). Here is an example:

<jazn provider="LDAP" location="ldap://myoid.oracle.com:389" default-realm="us" >
   ...
</jazn>

Authentication for the Admintool

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, as in this example:

    % 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

    Important:

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

Using Custom Principals and Permissions with the Admintool

For the Admintool to work with custom principals and permissions, configure the property classpath to specify the location of the JAR file containing the custom classes. Do this with a <property> subelement under the <jazn> element in the jazn.xml file, as in the following example:

<jazn ... >
   ...
   <property name="classpath" value="/tmp/customPrincipal.jar" />
   ...
</jazn>

Note:

In previous versions, the workaround was to put the JAR file into the jre/lib/ext directory. This will still work, but is not recommended.

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:

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 the 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 admintoolcommand

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

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 follows
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 following shows nodes of a realm abcRealm.

Figure C-2 Sample Shell Directory Structure

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

Summary of Admintool Special Shell Commands

This section summarizes the following Admintool shell commands:

All the Admintool commands support relative and absolute paths.

add, mkdir, and mk: Creating Provider Data

add name [other_parameter]
mkdir name [other_parameter]
mk name [other_parameter]

The add, mkdir, and mk commands are equivalent; they each create a subdirectory or node under the current directory. The effect of the command depends on the current directory location. For example, if the current directory is the root, then the command creates a realm. If the current directory is /realm/users, then the command creates a user. Depending on the situation, these commands would be equivalent to Admintool commands such as -addrealm and -adduser.

These shell commands may require additional parameters—essentially, the same as what would be required for the equivalent Admintool commands. For example, consider the following shell command:

JAZN:> add myrealm myuser mypassword myrole

When executed under the directory /realms, this shell command is equivalent to the following:

% java -jar jazn.jar -addrealm myrealm myuser mypassword myrole

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.

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 name

The rm command removes the directory or node in the current directory. The effect of the command depends on 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. An error message is displayed if the specified name 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

-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 Table 9-5, "Login Module Control Flags".

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, and where the login module supports a debug option:

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

-addrealm realm admin adminpwd adminrole
-remrealm realm

The -addrealm option creates a realm with the specified name and specified administrator.

For the file-based provider, specify the name of the realm, the realm administrator, the administrator password, and the administrator role:

-addrealm realm admin adminpwd adminrole

The -remrealm option deletes a realm.

Important:

Do not use the OracleAS JAAS Provider Admintool to create realms for Oracle Internet Directory. Realms created with this tool are suitable for the file-based provider only, and would not include sufficient information for use with Oracle Internet Directory. Instead, use Oracle Delegated Administration Services (DAS).

See Also:

For example, to create a realm employees with administrator martha, who has password mypass and is a member of role hr:

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

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

Adding and Removing Users (File-Based Provider Only)

-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

Setting Passwords (File-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

Checking Passwords (File-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 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.

See Also:

Granting and Revoking Permissions

-grantperm {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 java.security.Principal interface, and principal_params is a string to be interpreted by the principal class.

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

Always specify a realm when you grant or revoke permissions for a user or role, but not when you grant or revoke permissions for a principal.

Permission specifications include the explicit class name of a permission, and its action and target parameters. Note that there may be multiple action and target parameters, as shown in the examples below.

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. See "Using Custom Principals and Permissions with the Admintool".

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

% 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

Always specify a realm when you list permissions for a user or role, but not when you list permissions for a principal.

Important:

PermissionClassManager and related classes and operations, including -listperms, are deprecated in OC4J 10.1.3.x implementations 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

  • All roles granted to 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:

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us