7 File-Based Security Provider

OC4J supplies a file-based security provider, where an XML-based file is used as the repository for users, roles, and policies. This is the default security provider. Specifically, OracleAS JAAS Provider supports the following tasks for the file-based (XML-based) provider:

Create realms, users, and roles.
Grant roles to users and to other roles.
Assign permissions to specific users and roles (principals).

This information is stored in an XML repository, typically, system-jazn-data.xml, although you have the option of using an application-specific jazn-data.xml file instead.

This chapter discusses basic user, role, and realm management tasks for the file-based provider, focusing on features of the Application Server Control Console.

The chapter is divided into the following sections:

Tools for File-Based Provider Policy and Realm Management
Configuring the File-Based Provider in Application Server Control
File-Based Provider Settings in OC4J Configuration Files
OracleAS JAAS Provider Migration Tool
Migrating Principals from the principals.xml File

Notes:

B e aware that with the file-based provider, role comparisons for authorization are case-sensitive.
By default, the file-based provider is the security provider, the system-jazn-data.xml file is the repository, and jazn.com is the default realm. The system-jazn-data.xml file is located in the ORACLE_HOME/j2ee/instance_name/config directory. Changes made to this repository are visible to all applications that use it.

Tools for File-Based Provider Policy and Realm Management

To manage users and roles for the file-based provider, use Application Server Control Console, as described in "Managing Application Realms through Application Server Control". This updates the user repository, either system-jazn-data.xml or an application-specific jazn-data.xml file that you provide.

To manage policies for the file-based provider, use the OracleAS JAAS Provider Admintool. Refer to the policy options listed in "Summary of Admintool Command-Line Syntax and Options".

Generally avoid direct manipulation of the system-jazn-data.xml or jazn-data.xml file.

Note:

There is one exception regarding the tool for policy management: Granting RMI permission or Administration permission to a role in the file-based provider is something you can do as part of editing or adding the role through Application Server Control, as described later in this chapter.

Note that to enable fat client access to EJBs using RMI, you must grant RMI permission "login" to your user or role. If you do not enable this through Application Server Control, you can use the OracleAS JAAS Provider Admintool. For example:

% java -jar jazn.jar -grantperm myrealm -role myrole \
     com.evermind.server.rmi.RMIPermission login

See Also:

Appendix C, "OracleAS JAAS Provider Admintool Reference"

Configuring the File-Based Provider in Application Server Control

This section covers the following administration tasks, using the Application Server Control Console, for an application using the file-based provider. There is also a section at the end for instance-level administration.

Configuring the File-Based Provider during Application Deployment
Changing to the File-Based Provider after Deployment
Managing Application Realms through Application Server Control
Managing Application Users through Application Server Control
Managing Application Roles through Application Server Control
Administering Instance-Level Security through Application Server Control

Note:

Procedures discussed throughout this section assume you are logged in to Application Server Control as a user with required administrative permissions (as oc4jadmin, for example).
Security provider settings, optionally including specification of the repository file, affect settings in the <jazn> element of the orion-application.xml file. Realm, user, and role settings affect settings under the <jazn-realm> element in the repository file. Examples of the XML settings are in "File-Based Provider Settings in OC4J Configuration Files".

See Also:

"File-Based Provider Settings in OC4J Configuration Files", for examples of the XML configuration that results from the steps described in this section

Configuring the File-Based Provider during Application Deployment

You can specify the file-based provider when you deploy an application through Application Server Control. Optionally, you can also specify a jazn-data.xml file location and a default realm.

From the Deploy: Deployment Settings page (see "Deploying an Application through Application Server Control" for how to get to this page):

Go to the Select Security Provider task.
In the resulting Deployment Settings: Select Security Provider page, choose File-Based from the Security Provider dropdown list.
Under "Configuration of File-Based Security Provider" (which appears after you choose the file-based provider in the dropdown), you can accomplish the following:
- Specify the location of your repository, optionally an application-specific jazn-data.xml file for user and role configuration. Otherwise, the system-jazn-data.xml file will be used, unless jazn.xml also specifies the file-based provider and has a location setting for a jazn-data.xml file.
- Specify a default realm. Otherwise, the default realm is jazn.com, unless there is a different setting in the instance-level jazn.xml file.
Choose OK to finish the security provider selection.
Back in the Deploy: Deployment Settings page, choose Deploy to complete the deployment, or choose another task, as desired. The list of tasks is noted in "Deploying an Application through Application Server Control".

Changing to the File-Based Provider after Deployment

You can select a security provider for your application at deployment time, as described above. You can also change to a different security provider after deployment. You can change to the file-based provider as follows:

Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".
In the Security Provider page, choose "Change Security Provider".
In the Change Security Provider page, select File-Based Security Provider from the Security Provider Type dropdown.
Under "Security Provider Attributes: File-Based Security Provider" (which appears after you select "File-Based Security Provider"):
- Optionally specify the location of your repository file, such as an application-specific jazn-data.xml file. Otherwise, the system-jazn-data.xml file will be used, unless jazn.xml also specifies the file-based provider and has a location setting for a jazn-data.xml file.
- Optionally specify a default realm. Otherwise, the default realm is jazn.com, unless there is a different setting in the instance-level jazn.xml file.
Choose OK to finish the change.

This takes you back to the Security Provider page, where you can examine your settings.

Managing Application Realms through Application Server Control

This section describes how to configure realms for the file-based provider.

The first step for any of these instructions is to go to the Application Server Control Console Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

The tasks here create or modify subelements under the <jazn-realm> element in your repository file. There is a <realm> subelement under <jazn-realm> for each realm.

Note:

There is no "Edit" task for realms. Editing a realm includes updating users, roles, or both, as described in "Managing Application Users through Application Server Control" and "Managing Application Roles through Application Server Control".

Search for a Realm

From the Security Provider page for your application, execute the following steps to search for a realm:

Choose the Realms tab.
In the Realms page, under "Search", specify a search string then choose Go.
Realms matching the search string appear under "Results". (An empty search string displays all existing realms.)

Create a Realm

From the Security Provider page for your application, execute the following steps to create a realm:

Choose the Realms tab.
Above the list of existing realms, choose Create.
In the resulting Add Realm page:
- Specify the desired name of the realm.
- Specify the desired name for the administrator user of the realm.
- Specify and confirm the desired password for the administrator user.
- Specify the desired administrator role of the realm. The administrator user you specified will belong to this realm.
Choose OK to create the realm.

This takes you back to the Security Provider page, where you can see the new realm in the list of realms.

Delete a Realm

From the Security Provider page for your application, execute the following steps to delete a realm:

In the list of existing realms, choose the Delete task for the realm you want to delete.
In the resulting Confirmation page, choose Yes to delete the realm.

This takes you back to the Security Provider page.

Managing Application Users through Application Server Control

This section describes how to configure users for the file-based provider.

The tasks here create or modify subelements under a <users> element in your repository file. Each <realm> element has a <users> subelement for the users in that realm.

Search for a User

From the Security Provider page for your application, execute the following steps to search for a user:

Choose the Realms tab.
In the Realms page, under "Users" in the list of realms, and in the row for the realm of interest, select the number that shows how many users are in the realm. This is a link to the Users page for the realm.
In the Users page, under "Search", specify a search string then choose Go.
Users matching the search string appear under "Results". (An empty search string displays all users in the realm.)

Create a User

From the Security Provider page for your application, execute the following steps to create a user:

Choose the Realms tab.
In the Realms page, under "Users" in the list of realms, and in the row for the realm of interest, select the number that shows how many users are in the realm. This is a link to the Users page for the realm.
In the Users page, above the list of existing users in the realm, choose Create.
In the resulting Add User page:
- Specify the desired user name.
- Specify and confirm the desired password for the user.
- Under "Assign Roles", for any available role you want the user to belong to, move the role name into the "Selected Roles" column.
- Choose OK to add the user.

This takes you back to the Users page, where you can see the new user in the list of users.

Note:

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

Delete a User

From the Security Provider page for your application, execute the following steps to delete a user:

Choose the Realms tab.
In the Realms page, under "Users" in the list of realms, and in the row for the realm of interest, select the number that shows how many users are in the realm. This is a link to the Users page for the realm.
In the Users page, choose the Delete task for the user you want to delete.
In the resulting Confirmation page, choose Yes to delete the user.

This takes you back to the Users page.

Edit a User

From the Security Provider page for your application, execute the following steps to edit the properties of a user:

Choose the Realms tab.
In the Realms page, under "Users" in the list of realms, and in the row for the realm of interest, select the number that shows how many users are in the realm. This is a link to the Users page for the realm.
In the Users page, select the user you want to edit.
In the resulting User page:
- If you want to change the user password, enter the old password, then specify and confirm the desired new password.
- If you want to add the user to any roles or remove the user from any roles, under "Assign Roles", move role names into or out of the "Selected Roles" column as desired.
- Choose Apply to edit the user.

This takes you back to the Users page.

Note:

You can also reach the User page for a given user from the Role page (see "Edit a Role") for any role that the user belongs to. In the Role page, under "Users", select the user of interest.

Managing Application Roles through Application Server Control

This section describes how to configure roles for the file-based provider.

The tasks here create or modify subelements under a <roles> element in your repository file. Each <realm> element has a <roles> subelement for the roles in that realm.

Search for a Role

From the Security Provider page for your application, execute the following steps to search for a role:

Choose the Realms tab.
In the Realms page, under "Roles" in the list of realms, and in the row for the realm of interest, select the number that shows how many roles are in the realm. This is a link to the Roles page for the realm.
In the Roles page, under "Search", specify a search string then choose Go.
Roles matching the search string appear under "Results". (An empty search string displays all roles in the realm.)

Create a Role

From the Security Provider page for your application, execute the following steps to create a role:

Choose the Realms tab.
In the Realms page, under "Roles" in the list of realms, and in the row for the realm of interest, select the number that shows how many roles are in the realm. This is a link to the Roles page for the realm.
In the Roles page, above the list of existing users in the realm, choose Create.
In the resulting Add Role page:
- Specify the desired role name.
- Choose the permissions you want to grant to the role (essentially, to users or other entities belonging to the role)—RMI permission, administration permission, neither, or both.
  
  A user needs RMI (remote method invocation) permission to be able to access objects on OC4J through RMI, such as when using a remote EJB client.
  
  A user needs administration permission to perform administrative functions such as startup, shutdown, and configuration changes.
- Under "Assign Roles", for any available role you want the new role to inherit from, move the role name into the "Selected Roles" column.
- Choose OK to add the role.

This takes you back to the Roles page, where you can see the new role in the list of roles.

Delete a Role

From the Security Provider page for your application, execute the following steps to delete a role:

Choose the Realms tab.
In the Realms page, under "Roles" in the list of realms, and in the row for the realm of interest, select the number that shows how many roles are in the realm. This is a link to the Roles page for the realm.
In the Roles page, choose the Delete task for the role you want to delete.
In the resulting Confirmation page, choose Yes to delete the role.

This takes you back to the Roles page.

Edit a Role

From the Security Provider page for your application, execute the following steps to edit the properties of a role:

Choose the Realms tab.
In the Realms page, under "Roles" in the list of realms, and in the row for the realm of interest, select the number that shows how many roles are in the realm. This is a link to the Roles page for the realm.
In the Roles page, select the role you want to edit.
In the resulting Role page:
- Update permissions for the role as desired, by selecting or unselecting RMI permission and administration permission.
- Under "Assign Roles", move role names into or out of the "Selected Roles" column, depending on which roles you want this role (the role you are editing) to inherit from.
- Choose Apply to edit the role.

This takes you back to the Roles page.

See Also:

"Edit a User" for how to add a user to a role

Administering Insta nce-Level Security through Application Server Control

In the OC4J 10.1.3 implementation, instance-level security uses the file-based provider for realm settings (users and roles). This is according to settings in the <jazn> element of the OC4J system-application.xml file, which points to the system-jazn-data.xml file for the user and role repository. You can administer the file-based provider for instance-level security in much the same was as you would administer the file-based provider for an application. You can navigate to the Application Server Control Console Instance Level Security page as follows:

From the OC4J Home page for the OC4J instance, choose the Administration tab.
In the Administration page, choose the Security Providers task (under "Security").
In the Security Providers page, choose Instance Level Security.
From the resulting Instance Level Security page, you can manage instance-level realms, users, and roles using essentially the same steps as documented earlier in this chapter, in "Managing Application Realms through Application Server Control", "Managing Application Users through Application Server Control", and "Managing Application Roles through Application Server Control".

Instance-level security settings here will always affect the system-jazn-data.xml file (as opposed to application-level security settings, which would affect an application-level jazn-data.xml file if the user has specified one).

Note:

Be aware that OC4J has some dependencies on the instance-level security provider settings in system-application.xml and system-jazn-data.xml. For example, admin_client.jar uses accounts in system-jazn-data.xml. Do not delete or alter default settings in these files regarding the instance-level security provider and related accounts.

File-Based Provider Settings in OC4J Configuration Files

This section provides reference information for important security configuration for the file-based provider in key OC4J configuration files. In general, you should use the Application Server Control Console or OracleAS JAAS Provider Admintool (both discussed earlier in this chapter) for configuration and administration, instead of manipulating the files directly. Using these tools results in the appropriate entries automatically being made in the configuration files.

The rest of this discussion covers the following:

Scenarios for <jazn> Settings in orion-application.xml
Realm Configuration in the Repository File
Policy Configuration in the Repository File
Predefined OC4J Accounts in system-jazn-data.xml

Scenarios for <jazn> Settings in orion-application.xml

The <jazn> element, which appears in both the jazn.xml file and the orion-application.xml file, includes configuration for the security provider, repository, and default realm. By default, the system-jazn-data.xml file is the repository for user, role, and policy configuration for the file-based provider, but OC4J can be configured to use an application-specific jazn-data.xml file instead.

There are three typical deployment scenarios for an application, as determined by <jazn> element settings in the orion-application.xml file and instance-level jazn.xml file, in using the file-based provider:

Delegate to the instance-level jazn.xml file for the repository and default realm. If the <jazn> element in jazn.xml has the setting provider="XML", then its settings for the repository (location attribute) and default realm (default-realm attribute) are used if the orion-application.xml file has the following <jazn> element:
```
<jazn provider="XML" />
```
Or, if the jazn.xml file has no location and default-realm settings, this would use the default repository system-jazn-data.xml and the default realm jazn.com.

Note:
This becomes the default <jazn> setting if there is no <jazn> element in orion-application.xml when the application is deployed.
Delegate to the instance-level jazn.xml file for the repository. If the <jazn> element in jazn.xml has the setting provider="XML", then its setting for the repository (location attribute) is used, but the orion-application.xml file setting for the default-realm (default-realm attribute) is used, if orion-application.xml has a <jazn> element such as the following:
```
<jazn provider="XML" default-realm="abc.com" />
```
Or, if the jazn.xml file has no location setting, this would use the default repository system-jazn-data.xml.

Note:
This example assumes the abc.com realm is defined in the system-jazn-data.xml repository.
Do not delegate; specify both the repository and the default realm in orion-application.xml. In this example, orion-application.xml specifies the repository jazn-data.xml and the default realm myrealm:
```
<jazn provider="XML" location="./jazn-data.xml" default-realm="myrealm" />
```

Notes:

Note the following for situations where the application uses the file-based provider (provider="XML" in orion-application.xml) but the jazn.xml file has the setting provider="LDAP":

If orion-application.xml specifies no repository file, then system-jazn-data.xml will be the repository.
If orion-application.xml specifies no default realm, then jazn.com file will be the default realm.

Re alm Configuration in the Repository File

This section shows configuration for users and roles in the system-jazn-data.xml file for the jazn.com realm. The general structure would be the same for configuration of any realm in system-jazn-data.xml or a jazn-data.xml file. This configuration is created automatically when you manage realms through Application Server Control.

  <jazn-realm>
    <realm>
      <name>jazn.com</name>
      <users>
        <user deactivated="true">
          <name>anonymous</name>
          <description>The default guest/anonymous user</description>
        </user>
        <user deactivated="true">
          <name>oc4jadmin</name>
          <display-name>OC4J Administrator</display-name>
          <description>OC4J Administrator</description>
          <credentials>!welcome</credentials>
        </user>
        <user>
          <name>JtaAdmin</name>
          <display-name>JTA Recovery User</display-name>
          <description>Used to recover propagated OC4J transactions</description>
          <credentials>!defaultJtaPassword</credentials>
        </user>
      </users>
      <roles>
        <role>
          <name>oc4j-administrators</name>
          <display-name>OC4J Admin Role</display-name>
          <description>Administrative role for OC4J</description>
          <members>
            <member>
              <type>user</type>
              <name>oc4jadmin</name>
            </member>
            <member>
              <type>user</type>
              <name>JtaAdmin</name>
            </member>
          </members>
        </role>
        <role>
          <name>oc4j-app-administrators</name>
          <display-name>OC4J Application Administrators</display-name>
          <description>OC4J application-level administrators</description>
          <members>
          </members>
        </role>
        <role>
          <name>users</name>
          <display-name>users</display-name>
          <description>users role for rmi/ejb access</description>
          <members>
          </members>
        </role>
      </roles>
    </realm>
  </jazn-realm>

Policy Configuration in the Repository File

You can use the OracleAS JAAS Provider Admintool to grant JAAS permissions to custom principals, using the -grantperm option, as described in "Granting and Revoking Permissions".

Policy data is stored in the file system-jazn-data.xml. In the following example, a segment of this file grants the admin principal permission to log in.

<jazn-policy>
  <grant>
   <grantee>
     <principals>
      <principal>
        <class>oracle.security.jazn.samples.SampleUser</class>
        <name>admin</name>
      </principal>
    </principals>
   </grantee>
   <permissions>
     <permission>
       <class>com.evermind.server.rmi.RMIPermission</class>
       <name>login</name>
     </permission>
   </permissions>
  </grant>
</jazn-policy>

Predefined OC4J Accounts in system-jazn-data.xml

The following accounts are predefined in system-jazn-data.xml for the file-based provider:

oc4jadmin user (initially deactivated in standalone OC4J)
oc4j-administrators role
oc4j-app-administrators role
anonymous user, initially deactivated
users role
jtaadmin user

See Also:

"Predefined OC4J Accounts" for additional information about these accounts
"Activation of the oc4jadmin Account"

OracleAS JAAS Provider Migration Tool

OC4J includes a tool for migrating from a file-based repository to either an Oracle Internet Directory repository or an alternative file-based repository. (Do not confuse this with the tool for migrating from principals.xml; that is separate, and is documented later in this chapter.)

When migrating to an Oracle Internet Directory repository, the output is an LDIF file, which can be imported into Oracle Internet Directory using commands such as ldapmodify or bulkload.

Overview of the Migration Tool

The migration tool supports the migration of users, roles, role memberships, and policies (permissions granted to roles, users, custom principals, or codebases).

There are three modes for migration:

Realm mode migrates only users and roles. All users and roles in the source realm, other than deactivated users, are migrated. Migrated roles include membership information.
Policy mode migrates grantees and the permissions that have been granted to them. Grantees can be realm grantees, such as users and roles, or non-realm grantees, such as custom principals and codebases. When migrating to Oracle Internet Directory, realm grantees and their permissions are migrated to the policy that is specific to the destination realm, while non-realm grantees and their permissions are migrated to the global policy.
All mode combines realm mode and policy mode.

Notes:

When output to an LDIF file is generated, passwords are in clear text. It is your responsibility to take proper care in protecting this information.
When migrating to Oracle Internet Directory, passwords may have to be modified to conform to Oracle Internet Directory requirements (such as having at least one numeric character).
If you are migrating custom permissions, the JAR file containing the class files for the custom permissions must be available in the classpath.
The migration tool is not intended for migration of indirect password accounts to Oracle Internet Directory.
Be aware of the possibility of conflict—migrated users and roles may already exist in the destination realm. When migrating to Oracle Internet Directory, for example, commands such as ldapmodify and bulkload can be used in conjunction with standard JDK logging to obtain information that will help you to recover from conflicts.

Migration Tool Command Syntax

Command-line options and syntax of the migration tool are as follows:

% java JAZNMigrationTool [-st xml] [-dt ldap|xml]
                         [-D binddn] [-w passwd] [-h ldaphost] [-p ldapport]
                         [-sf sourcefilename] [-df destfilename]
                         [-sr source_realm] [-dr dest_realm]
                         [-m policy|realm|all]
                         [-help]

Table 7-1 describes these options.

Table 7-1 OracleAS JAAS Provider Migration Tool Options

Option	Description	Default (where applicable)
`-help`	To display option information
`-st`	Type of provider at the source Currently only the setting `xml` is supported, for migrating from a file-based provider.	`xml`
`-dt`	Type of provider at the destination—either `xml` (to migrate to a file-based repository) or `ldap` (to migrate to Oracle Internet Directory)	`ldap`
`-D`	Oracle Internet Directory user name (for migration to Oracle Internet Directory only)
`-w`	Oracle Internet Directory user password (for migration to Oracle Internet Directory only)
`-h`	Oracle Internet Directory host system (for migration to Oracle Internet Directory only)	According to `<jazn>` element `location` setting in `jazn.xml`
`-p`	Oracle Internet Directory port (for migration to Oracle Internet Directory only)	According to `<jazn>` element `location` setting in `jazn.xml`
`-sf`	Source file—path to the file-based repository you are migrating from	`ORACLE_HOME/j2ee/home/config/system-jazn-data.xml`
`-df`	Destination file—path to the LDIF output file (if migrating to Oracle Internet Directory) or to the destination file-based repository (if migrating to file-based)	If migrating to a file-based repository, `ORACLE_HOME/j2ee/home/config/system-jazn-data.xml` (otherwise no default)
`-sr`	Source realm—the realm you are migrating from	Name of the realm in the source repository, if there is only one realm
`-dr`	Destination realm—the realm you are migrating to	If migrating to a file-based repository, name of the realm in the destination repository, if there is only one realm; if migrating to Oracle Internet Directory, the default subscriber realm
`-m`	The desired migration mode—realm mode (`realm`), policy mode (`policy`), or both (`all`)	`all`

The following example migrates in all mode to the default subscriber realm in Oracle Internet Directory on the specified host:

% java oracle.security.jazn.tools.JAZNMigrationTool -D cn=orcladmin -w welcome1 \
       -h myhost.example.com -p 389 -sf /tmp/jazn-data.xml -df /tmp/dest.ldif \
       -sr jazndemo.com

Migration Tool APIs

You can also invoke the migration tool (class JAZNMigrationTool in package oracle.security.jazn.tools) from an application. Oracle provides the following APIs:

/**
 * Create an instance with the provided parameters. These parameters are
 * equivalent to the options supported by the executable utility version.
 */
public JAZNMigrationTool(Map params)
 
/**
 * Perform the migration operation
 */
public  void migrateData() throws JAZNException

The params parameter in the constructor supports the same options as described in Table 7-1 in the preceding section, with the same defaults. Parameter keys are defined as constants in the JAZNMigrationTool class. Table 7-2 shows the correlation between constants defined in JAZNMigrationTool and command-line options.

Table 7-2 JAZNMigrationTool Constants

Key Constant	Corresponds to Option
`SRC_TYPE`	`-st`
`DEST_TYPE`	`-dt`
`OID_USER`	`-D`
`OID_PASSWORD`	`-w`
`OID_HOST`	`-h`
`OID_PORT`	`-p`
`SRC_FILE`	`-sf`
`DEST_FILE`	`-df`
`SRC_REALM`	`-sr`
`DEST_REALM`	`-dr`
`MIGRATE_OPT`	`-m`

Migrating Principals from the prin cipals.xml File

Use the OracleAS JAAS Provider Admintool convert option to migrate your data out of the principals.xml file, which is deprecated.

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

Note:

The principals.xml file is deprecated in the OC4J 10.1.3 implementation and will be desupported in a future release.

Before you convert principals.xml, you must make sure that you have an administrative 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 option 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 "Scenarios for <jazn> Settings in orion-application.xml".
Stop OC4J and restart it.

7 File-Based Security Provider

Tools for File-Based Provider Policy and Realm Management

Configuring the File-Based Provider in Application Server Control

Configuring the File-Based Provider during Application Deployment

Changing to the File-Based Provider after Deployment

Managing Application Realms through Application Server Control

Search for a Realm

Create a Realm

Delete a Realm

Managing Application Users through Application Server Control

Search for a User

Create a User

Delete a User

Edit a User

Managing Application Roles through Application Server Control

Search for a Role

Create a Role

Delete a Role

Edit a Role

Administering Instance-Level Security through Application Server Control

File-Based Provider Settings in OC4J Configuration Files

Scenarios for <jazn> Settings in orion-application.xml

Realm Configuration in the Repository File

Policy Configuration in the Repository File

Predefined OC4J Accounts in system-jazn-data.xml

OracleAS JAAS Provider Migration Tool

Overview of the Migration Tool

Migration Tool Command Syntax

Migration Tool APIs

Migrating Principals from the principals.xml File

Administering Insta nce-Level Security through Application Server Control

Re alm Configuration in the Repository File

Migrating Principals from the prin cipals.xml File