Oracle® Containers for J2EE Security Guide 10g (10.1.3.1.0) Part Number B28957-01 |
|
|
View PDF |
This chapter contains reference information for the OracleAS JAAS Provider Admintool. It is divided into the following sections:
Notes:
|
This section will help you get started with the OracleAS JAAS Provider Admintool and covers the following topics:
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 ofjazn.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 ...
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>
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".
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 thejre/lib/ext directory. This will still work, but is not recommended. |
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:
|
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
Authentication options
-user username -password password
Login module options
-addloginmodule application_name login_module_name control_flag [options] -listloginmodules [application_name] [login_module_class] -remloginmodule application_name login_module_name
Migration option
-convert filename realm
Password management options (file-based provider only)
-checkpasswd realm user [-pw password] -setpasswd realm user old_pwd new_pwd
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]
Realm manipulation options for file-based provider
-addrealm realm admin {adminpwd adminrole | adminrole userbase rolebase realmtype } -addrole realm role -adduser realm username password -remrealm realm -remrole realm role -remuser realm user
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. |
Realm options for general use
-grantrole role realm {user | -role to_role} -revokerole role realm {user|-role from_role} -listrealms realm -listroles [realm [user | -role role]] -listusers [realm [-role role | -perm permission]]
Shell option
-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:
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
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
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
This section summarizes the following Admintool shell commands:
All the Admintool commands support relative and absolute paths.
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 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
The clear
command clears the terminal screen by displaying 80 blank lines.
help
The help
command displays a list of all valid shell commands.
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 command_option man shell_command
The man
command displays detailed usage information for the specified shell command or Admintool command option.
pwd
The pwd
command displays the current location of the user in the directory tree. Undefined values are left blank in this listing.
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.
This section documents administrative features of the Admintool. The following topics are covered:
-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
-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
-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
-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
-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
-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
-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. |
-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
-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
-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
-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
-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
-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
-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
-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