Skip Headers

Oracle® Application Server Containers for J2EE Security Guide 10g Release 2 (10.1.2) B14013-02 |
| Library | Product | Contents | Index

Previous | Next |

# 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:

1. Go to the Application Server Control Console.

2. Navigate to the Security page for the appropriate OC4J instance.

3. 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:

1. Go to the Application Server Control Console.

2. Navigate to the Security page for the appropriate OC4J instance.

3. 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:

1. Go to the Application Server Control Console.

2. Navigate to the Security page for the appropriate OC4J instance.

3. Select a user with the radio button.

4. 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:

1. Go to the Application Server Control Console.

2. Navigate to the Security page for the appropriate OC4J instance.

3. Select a group with the radio button.

4. 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:

1. Go to the Application Server Control Console.

2. Navigate to the Security page of the chosen OC4J instance.

3. Select a user with the radio button.

4. Select the checkboxes that correspond to the roles you wish to grant.

5. Click the Apply button.

## Revoking Roles (Groups)

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

1. Go to the Application Server Control Console.

2. Navigate to the Security page of the chosen OC4J instance.

3. Select a user with the radio button.

4. Select the checkboxes that correspond to the roles you wish to revoke.

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

See Also: "Locating jazn.xml, jazn-data.xml, and the <jazn> Element" for details on locating `jazn.xml`

1. Open `jazn.xml` in your text editor and go to the `<jazn>` element.

2. Edit the `persistence` attribute of the `<jazn>` element. For example, to write changes after every modification, you should edit the `<jazn>` element to look like:

       <jazn persistence="ALL" ... other attributes >
          ...
       </jazn>

Note: Do not change the other attributes of the `<jazn>` element.

## 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:

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

2. Edit the `default-realm` attribute of the `<jazn>` element. The syntax is:

       <jazn provider="XML" default-realm="myrealm" ... >

3. 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:

1. Activate the administrative user in `principals.xml`, which is deactivated by default. Be sure to create a password for the administrator.

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

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

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

4. Change the `<default-realm>` to `principals.com`.

   See Also: "Setting Persistence Mode"

5. Stop and restart OC4J.