8 Configuring the XML-Based Provider

This chapter discusses performing basic user, group, and role management tasks using Oracle Enterprise Manager 10g Application Server Control Console and the JAZN Admintool. It is divided into the following sections:

Creating Users
Creating Roles (Groups)
Deleting Users
Deleting Roles (Groups)
Creating Realms
Deleting Realms
Granting Permissions
Revoking Permissions
Granting Roles (Groups)
Revoking Roles (Groups)
Setting Persistence Mode
Configuring XML Default Realm
Migrating Principals from the principals.xml File

Note:

This chapter uses the term "role" because that term is used by the JAZN Admintool. A "role" is the same as a "group", which is the more commonly used term.

Creating Users

To create users in the XML-based provider, use Enterprise Manager as follows:

Go to the Application Server Control Console.
Navigate to the Security page for the appropriate OC4J instance.
Click the Add User button and follow the instructions on the pages.

Note:
Do not create user names that contain slash (/) characters, as in a/b/c.

Creating Roles (Groups)

To create roles (also known as groups) in the XML-based provider, use Enterprise Manager as follows:

Go to the Application Server Control Console.
Navigate to the Security page for the appropriate OC4J instance.
Click the Add Group button and follow the instructions on the pages.

Deleting Users

To delete users in the XML-based provider, use Enterprise Manager as follows:

Go to the Application Server Control Console.
Navigate to the Security page for the appropriate OC4J instance.
Select a user with the radio button.
Click the Remove button and follow the instructions on the pages.

Note:

The instance-level jazn-data.xml file must contain accounts for "admin" and "anonymous". Do not remove these accounts; if you do, the OracleAS JAAS Provider will stop working.

Deleting Roles (Groups)

To delete roles (also known as groups) in the XML-based provider, use Enterprise Manager as follows:

Go to the Application Server Control Console.
Navigate to the Security page for the appropriate OC4J instance.
Select a group with the radio button.
Click the Remove button and follow the instructions on the pages.

Creating Realms

To add a realm, use the JAZN Admintool. See "Admintool Overview" for details on using the Admintool.

The Admintool -addrealm option adds a realm. It takes as arguments the realm name, the administrator name, and the administrator password. The syntax is:

-addrealm realm admin adminpwd adminrole

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

Deleting Realms

To delete realms, use the JAZN Admintool. See "Admintool Overview" for details on using the Admintool.

The Admintool -remrrealm option deletes a role from the realm. It takes one arguments, realm, the realm name. The syntax is:

-remrealm realm

To delete a realm foo, type:

java -jar jazn.jar -remrealm foo

Granting Permissions

See "Granting Permissions".

Revoking Permissions

To revoke permissions, use the JAZN Admintool. See"Admintool Overview" for details on using the Admintool. The -revokeperm option revokes the specified permission from a user or role or principal. To supply multiple words in the permission argument, enclose it in quotation marks ("three word permission"). The syntax is:

-revokeperm {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_paramters is a single String parameter.

To revoke the perm1 permission:

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

Granting Roles (Groups)

To grant roles in the XML-based provider, use Enterprise Manager as follows:

Go to the Application Server Control Console.
Navigate to the Security page of the chosen OC4J instance.
Select a user with the radio button.
Select the checkboxes that correspond to the roles you wish to grant.
Click the Apply button.

Revoking Roles (Groups)

To grant roles in the XML-based provider, use Enterprise Manager as follows:

Go to the Application Server Control Console.
Navigate to the Security page of the chosen OC4J instance.
Select a user with the radio button.
Select the checkboxes that correspond to the roles you wish to revoke.
Click the Apply button.

Setting Persistence Mode

Persistence mode governs when changes to data are written to jazn-data.xml. There are three possible values for persistence:

NONE

Do not write changes to jazn-data.xml.
ALL

Write changes after every modification.
VM_EXIT (the default)

Write changes when the Java Virtual Machine exits.

To configure the persistence mode in the XML-based provider, you must edit the <jazn> element in the jazn.xml file by hand.

Configuring XML Default Realm

The default realm is the realm used whenever an authentication or authorization request does not specify a realm explicitly. This attribute is not needed if you have configured only one realm in the repository. To configure the XML default realm, use the following steps:

Locate the file containing the <jazn> element (as discussed in "Locating jazn.xml, jazn-data.xml, and the <jazn> Element"), open the file in a text editor, and go to the <jazn> element within the file.
Edit the default-realm attribute of the <jazn> element. The syntax is:
```
<jazn provider="XML" default-realm="myrealm" ... >
```

For example, a <jazn> element that set the default-realm to Sales would look like:

<jazn provider="XML" default-realm="Sales" ... more attributes ... >
   ...
</jazn>

Note:

Do not edit any <jazn> properties except as specified in this chapter.

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, you must make sure that you have an administrator user that is authorized to manage realms. To do this:

Activate the administrative user in principals.xml, which is deactivated by default. Be sure to create a password for the administrator.
Create the realm 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
```
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.

Migrate principals.xml to the principals.com realm, as in:

java -jar jazn.jar -convert config/principals.xml principals.com

Change the <default-realm> to principals.com.
See Also:

"Setting Persistence Mode"
Stop and restart OC4J.