OracleŽ Application Server Containers for J2EE Security Guide 10g (9.0.4) Part Number Part No. B10325-02 |
|
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 shell uses UNIX-derived commands to perform specific JAAS functions. The JAZN Admintool is located in OC4J_HOME
/j2ee/home/jazn.jar.
This chapter discusses how to perform common administration tasks using the JAZN Admintool. It is divided into the following sections:
When you use the Admintool to manage XML provider data, by default it edits the file jazn-data.xml
under the config
directory of the OC4J home instance. The pathname of jazn-data.xml
is specified in the <jazn provider="xml" location="
pathname
">
element in jazn.xml
. The password for the admin user is set during installation time to the same value as the Oracle Application Server administrator (ias_admin
) password.
For using the Admintool with the LDAP-based provider, be sure to:
If you are using the XML-based Provider, you must authenticate yourself to the JAZN Admintool before making administrative changes. You authenticate yourself in one of two ways:
-user
and -password
switches, as in:
java -jar jazn.jar -usermyusername
-passwordmypassword
-listrealms
java -jar jazn.jar -listrealms >RealmLoginModule username: martha >RealmLoginModule password: mypass
In either case you may specify a LoginModule
for the Admintool in jazn-data.xml
. If it is not provided, the RealmLoginModule
is used by default.
Your jazn-data.xml
file can specify which LoginModule
the Admintool uses to authenticate its users. For example:
<application> <name>oracle.security.jazn.tools.Admintool</name> <login-modules> <login-module> <class>oracle.security.jazn.realm.RealmLoginModule</class> <control-flag>required</control-flag> <options> <option> <name>debug</name> <value>false</value> </option> <option> <name>addAllRoles</name> <value>true</value> </option> </options> </login-module> </login-modules> </application>
If you try to run the Admintool without specifying a LoginModule
, the RealmLoginModule with the default options is used.
The JAZN Admintool provides the following command options, described in greater detail in the following sections. 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:
java -jar jazn.jar -help
The overall syntax for the Admintool is
java -jar jazn.jar [-userusername
-passwordmypassword
-clustersupportORACLE_HOME
] [otheroptions
]
This section lists all the Admintool command options.
-userusername
-passwordmypassword
See "Authentication and the JAZN Admintool (XML-based Provider Only)".
-clustersupport oracle_home
See "Adding Clustering Support (XML-based Provider Only)".
-getconfig
See "Configuration Operations".
-shell
See "Using the JAZN Admintool Shell".
-addloginmoduleapplication_name
login_module_name
[
control_flagoptions
] -listloginmodules [application_name]
-remloginmoduleapplication_name
login_module_name
See "Adding and Removing Login Modules" and "Listing Login Modules".
-convert filename realm
See "Migrating Principals from the principals.xml File (XML-based Provider Only)".
-help [<command name>
]
To display help for a specific command.
-checkpasswdrealm user [-pw password]
-setpasswdrealm user old_pwd new_pwd
See "Checking Passwords (XML-based Provider Only)" and "Setting Passwords (XML-based Provider only)".
-addpermpermission permission_class action target [description]
-addprncplprinciplename
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_name>] | -listpermpermission
-listprncpls -listprncplprincipal_name
-rempermpermission
-remprncplprincipal_name
-revokeperm {<realm> {-user user|-role <role>} | <principal_class> <principal_params>} <permission_class> [<permission_params>] |
See "Adding and Removing Policy Permissions (XML-based Provider Only)", "Adding and Removing Principals (XML-based Provider Only)", "Granting and Revoking Permissions", "Listing Permissions", "Listing Permission Information", "Listing Principal Classes", and"Listing Principal Class Information".
-addrealm realm admin {adminpwd adminrole | adminrole
userbase rolebase realmtype}
-addrolerealm role
-adduserrealm username password
-grantrolerole realm {user|-role to_role}
-listrealms -listroles [realm
[user
|-rolerole
]] -listusers [realm
[-rolerole
|-perm permission]] -remrealmrealm
-remrolerealm
role
-remuserrealm
user
-revokerolerole
realm
{user|-role from_role}
See "Adding and Removing Realms", "Adding and Removing Roles", "Adding and Removing Users (XML-based Provider Only)", "Granting and Revoking Roles", "Listing Realms", "Listing Roles", and "Listing Users".
-
clustersupportoracle_home
This option instructs the Admintool to propagate all JAAS configuration changes throughout a cluster. The oracle_home
argument specifies the absolute pathname of the Oracle home directory. You can combine -clustersupport
with the -shell
option.
For example:
java -jar jazn.jar -clustersupport /oracle_home
-shell
-addloginmodule
application_name
login_module_name
[
control_flagoptionname=value ...
] -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 5-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 instance, to add MyLoginModule
to the application myapp
as a required module with debug
set to true
, type:
java -jar jazn.jar -addloginmodule myapp MyLoginModule required debug=true
To delete MyLoginModule
from myapp
, type:
java -jar jazn.jar -remloginmodule myapp MyLoginModule
JAZN:> addloginmodule myapp MyLoginModule required debug=true JAZN: remloginmodule myapp MyLoginModule
-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 permission's action and target lists.
For instance, to create permission to drop a realm, type:
java -jar jazn.jar -addperm perm1 oracle.security.jazn.realm.RealmPermission droprealm "permission to drop a realm"
To delete the droprealm
permission, type:
java -jar jazn.jar -remperm perm1
JAZN:> addperm perm1 oracle.security.jazn.realm.RealmPermission droprealm -null "permission to drop a realm" JAZN: remperm perm1
-addprncpl
principlename
principle_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 principal's parameter list.
For example, to add the principal staff
, type:
java -jar jazn.jar -addprincpl staff oracle.security.jazn.spi.xml.XMLRealmUser "a staff user"
JAZN:> addprincpl staff oracle.security.jazn.spi.xml.XMLRealmUser -null "a staff user"
-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
-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
, type:
java -jar jazn.jar -addrole foo fooRole
To delete the role from the realm, type:
java -jar jazn.jar -remrole foo fooRole
JAZN:> remrole foo fooRole
-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
, type:
java -jar jazn.jar -adduser foo martha mypass
To delete martha
from the realm, type:
java -jar jazn.jar -remuser foo martha
JAZN:> adduser foo martha mypass
-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 username and password pair are correct, or "Unsuccessful verification of user/password pair
" if username and/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
JAZN:> checkpasswd foo martha -pw Hello
-getconfig
The -getconfig
option displays the current configuration setting in jazn.xml
.
For example, to check the configuration settings for the realm foo
, type:
java -jar jazn.jar -getconfig
JAZN:> getconfig foo
-grantperm
realm
{-user user
|-rolerole
}|
principal_class principal_parameters} permission_class
[permission_parameters]
-revokeperm
realm
{-user user|-rolerole
}|
principal_class principal_parameters} permission_class
[permission_parameters]
-listperms
realm
{-user user|-rolerole
}|
principal_class principal_parameters} permission_class
[permission_parameters]
where principal_class
is the fully qualified name of a class that implements the principal interface (e.g., com.sun.security.auth.NTDomainPrincipal
) and principal_paramters
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 a permission's explicit class name (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
, type:
java -jar jazn.jar -grantperm foo martha java.io.FilePermission a.txt read, write
JAZN:> grantperm foo martha java.io.FilePermission a.txt read, write
-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
, type:
java -jar jazn.jar -grantrole editor foo martha
JAZN:> grantrole editor foo martha
-listloginmodules
[application_name
]
The -listloginmodules
option displays all LoginModule
s either in the specified application_name
or, if no application_name
is specified, in all applications.
For example, to display all LoginModule
s for the application myapp
, type:
java -jar jazn.jar -listloginmodules myapp
JAZN:> listloginmodules myapp
-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:
PermissionClassManager
-role
option is used.
prinicpal
.
For example, to display all permissions for the user martha
in realm foo
, type:
java -jar jazn.jar -listperms foo martha
JAZN:> listperms foo martha
-listperm
permission
The-listperm
option displays detailed information about the specified permission, including the permission's display name, class, description, actions, and targets.
For example, to list all information about the permission perm1
, type:
java -jar jazn.jar -listperm perm1
Typical output might look like
Name: perm1 Class: oracle.security.jazn.realm.RealmPermission Description: permission to drop realm Targets: Actions: droprealm <no description available>
JAZN:> listperm perm1
-listprncpls
The -listprncpls
option lists all principal classes registered with the PrincipalClassManager
.
For example:
java -jar jazn.jar -listprncpls
JAZN:> listprncpls
-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
, type:
java -jar jazn.jar -listprncpl martha
In our example, the output would be:
Name: martha Class: oracle.security.jazn.spi.xml.XMLRealmUser Description: a staff user Parameters:
JAZN:> listprncpl martha
-listrealms
The -listrealms
option displays all realms in the current JAAS environment.
For example, to list all realms, type:
java -jar jazn.jar -listrealms
JAZN:> listrealms
-listroles
[realm
[user
|-rolerole
]]
The -listroles
option displays a list of roles that match the list criteria. This option lists:
role
, when called with a realm name and the option -role
For example, to list all roles in realm foo
, type:
java -jar jazn.jar -listroles foo
JAZN:> listroles foo
-listusers
[realm
[-rolerole
|-perm permission]]
The -listusers
option displays a list of users that match the list criteria. This option lists:
-role
or -perm
For example, to list all users in realm foo
, type:
java -jar jazn.jar -listusers foo
For example, to list all users in realm foo
using permission bar
, type:
java -jar jazn.jar -listusers foo -perm bar
The Admintool lists users one per line, as in:
scott admin anonymous
JAZN:> listusers foo
-convert
filename realm
The -convert
option migrates the principals.xml
file into the specified realm of the current JAAS Provider. The filename
argument specifies the pathname 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
, you must make sure that you have an administrator user that is authorized to manage realms. To do this:
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.
principals.com
with a dummy user and a dummy role. For example, in the Admintool shell you would type:
JAZN> addrealm principals.com u1 welcome r1
java -jar jazn.jar -convert config/principals.xml principals.com
jazn.xml
and change the <default-realm>
entry to principals.com
.
-setpasswd
realm user old_pwd new_pwd
The -setpasswd
option allows 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
, type:
java -jar jazn.jar -setpasswd foo martha mypass a2d3vn
JAZN:> setpasswd foo martha mypass a2d3vn
-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
.
If you are using the XML-based provider you must supply a username and password to the Admintool; for details see "Authentication and the JAZN Admintool (XML-based Provider Only)" . If you are using the LDAP-based Provider, you do not need to specify the -user
and -password
arguments.
The Admintool shell supports UNIX-like commands for navigating within a JAZN structure. For a complete discussion of the Admintool directory structure, see "Admintool Shell Directory Structure" . All the Admintool commands support relative and absolute paths.
The Admintool navigation commands are:
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 path
The cd
command allows users to navigate the directory tree. Relative and absolute path names are supported. To exit a directory, type:
cd ..
Typing cd
/
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.
exit
The exit
command exits the JAZN shell.
help
The help
command displays a list of all valid 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 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
The pwd
command displays the current location of the user in the directory tree. Undefined values are left blank in this listing.
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 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.
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 parent node's properties. Figure 5-1 illustrates the node 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.
Figure 5-2 shows nodes of the xmlRealm
created by the jazn-data.xml
file in "Sample jazn-data.xml Code".
|
Copyright © 1996, 2003 Oracle Corporation. All Rights Reserved. |
|