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. Use of this file-based provider is typical during development and in small production environments (such as when using standalone OC4J), and 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
Using the File-Based Provider Across an OC4J Group

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.

See Also:

"Creating a New Administrator Account" if you want to use an administrator account other than oc4jadmin

Tools for File-Ba sed 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 application 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 Roles through Application Server Control
Administering Instance-Level Security through Application Server Control

Notes:

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.

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:
- Choose whether to use the default file-based provider of the OC4J instance, or an application-specific file-based provider.
- Specify the location of your repository, optionally an application-specific jazn-data.xml file, for user and role configuration. By default, the system-jazn-data.xml file will be used.
- 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"):
- Choose whether to use the default file-based provider of the OC4J instance, or an application-specific file-based 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.
- 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. You are prompted to restart your application for the change to take effect.

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 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 administrative user of the realm.
- Specify and confirm the desired password for the administrative user.
- Specify the desired administrator role of the realm. The administrative 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 by navigating 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 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 from 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

You can specifically configure realms, users, and roles for the OC4J instance-level file-based security provider. Changes made in this way will always affect the system-jazn-data.xml file, rather than any application-level jazn-data.xml file (if any have been specified).

(The instance-level file-based provider is specified to be system-jazn-data.xml according to settings in the <jazn> element of the OC4J system-application.xml file.)

You can administer the instance-level file-based provider 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 Roles through Application Server Control".

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 (discussed earlier in this chapter) for configuration and administration, instead of manipulating the files directly. Using this tool results in the appropriate entries automatically being made in the configuration files.

The rest of this discussion covers the following:

Settings in the <jazn> Element for the File-Based Provider
Realm Configuration in the Repository File
Policy Configuration in the Repository File
Predefined OC4J Accounts in system-jazn-data.xml

Settings in the <jazn> Element for the File-Based Provider

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.

This section discusses the following related topics:

Scenarios for <jazn> Settings in orion-application.xml
Configuration to Automatically Create an Application-Specific jazn-data.xml File
Supplying an Application-Specific jazn-data.xml File

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

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.

Configuration to Automatically Create an Application-Specific jazn-data.xml File

If orion-application.xml is configured exactly as follows, but the jazn-data.xml file is not packaged with the application, then one will be created during deployment:

<jazn provider="XML" location="./jazn-data.xml" />

Supplying an Application-Specific jazn-data.xml File

If you supply a jazn-data.xml file with your application, then you must specify its location through the <jazn> element location attribute in the orion-application.xml file for your application. For example:

In orion-application.xml, specify the following:
```
<jazn provider="XML" location="./jazn-data.xml" default-realm="myrealm" />
```
If you specify a relative location, the location is relative to that of the orion-application.xml file within which the <jazn> element is contained, typically the /META-INF directory of the application EAR file.
Package the jazn-data.xml file in the /META-INF directory of the EAR file.

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 shows the result of granting RMI permission "login" to the admin principal. (This example assumes admin is a user in the jazn.com realm.)

<jazn-policy>
  <grant>
   <grantee>
     <principals>
      <principal>
        <realm-name>jazn.com</realm-name>
        <type>user</type>
        <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 (with member oc4jadmin)
oc4j-app-administrators role
ascontrol_admin role (with member oc4jadmin)
ascontrol_appadmin role
ascontrol_monitor role
anonymous user, initially deactivated
users role
jtaadmin user

See Also:

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

OracleAS JAAS Provider Mi gration 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.

This section covers the following topics:

Overview of the Migration Tool
Migration Tool Command Syntax
Migration Tool APIs

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:

Be aware of the following when you use the migration tool:

To migrate to Oracle Internet Directory, the directory server must be running and available when you run the tool.
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).
When in policy mode or all mode: 1) When migrating permissions for a non-realm custom principal, the JAR file containing the class files for the custom principal must be available in the classpath. 2) 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 deployment users and converts principals.xml groups to deployment roles. All permissions that were previously granted to a principals.xml group are mapped to the deployment 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. (It will not be supported in the 11g 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 "Settings in the <jazn> Element for the File-Based Provider".
Stop and restart OC4J.

Using the File-Based Provider Across an OC4J Group

The OC4J 10.1.3.1 implementation adds features to include OC4J instances in a "group" (where previously, instances could only be in a group if they had the same instance name).

Through use of these features, and use of OC4J J2EEServerGroup MBean, you can coordinate changes to the system-jazn-data.xml file in each OC4J instance in a group.

OC4J Basic Group Features

In an OC4J cluster, you can create a new group through Application Server Control as follows:

In the Cluster Topology page, under Groups, choose Create.

In the Create Group page:

Specify the desired name of the group.

Select the OC4J instances to move to the group. Be aware that an OC4J instance you move into the new group is removed from the group it was in previously (if applicable), and that an instance must be stopped before it can be moved.

Important:

When you stop an OC4J instance, at least one other OC4J instance must be running on the application server that hosts the instances. If the check box to stop an OC4J instance is disabled, then no other OC4J instances in that application server are running.

Choose Create.

Note:

You can also move an OC4J instance into a group after the group is created:

In the Cluster Topology page, under Groups, select the group.
In the Group: groupname page, in the OC4J Instances tab, choose Add.
In the Add OC4J Instances to Group page, select and add OC4J instances to the group as desired.

You can administer a group through Application Server Control as follows:

In the Cluster Topology page, under Groups, choose the desired group.
Choose the Administration tab.
The Administration page provides administration features for the group as a whole. Note, however, that this does not include Security Provider administration.

See Also:

For additional information about OC4J group features, the topic "Group OC4J Instances Page" in the Application Server Control online help

Cluster M Bean Browser Features and the J2EEServerGroup MBean

Once you have created a group and populated it with OC4J instances, you can use the Cluster MBean Browser to coordinate settings to each system-jazn-data.xml file across the group, by invoking operations on the J2EEServerGroup MBean for the group. This also involves the J2EEApplication MBean for the system application.

You can accomplish this as follows:

In the Cluster Topology page, under Groups, chose the group.
In the Group: groupname page, choose the Administration tab.
In the Administration page, under JMX, go the Cluster MBean Browser task.
In the Cluster MBean Browser page:
1. Under the J2EEServerGroup MBean, select the OC4J group.
2. Choose the Operations tab.
3. Choose the invoke operation.
In the Operation: invoke page (shown in Figure 7-1 at the end of this procedure), use the flashlight icon to search for MBeans by name.
In the Search and Select: MBean page (shown in Figure 7-2 at the end of this procedure):
1. Search by MBean name "SecurityProvider".
2. In the search results, select the result with J2EEApplication=system (the last result shown in the figure).
Back in the Operation: invoke page:
1. For the parameter name operationName, choose the desired operation from the dropdown menu. Available operations for the J2EEApplication MBean include (among many others): addUser, addRole, remUser, remRole, revokeUserRole, revokeUserPerm, grantUserPerm, and grantRolePerm, for example.
2. Use the pencil icon to specify parameter settings for the operation. For example, for addUser, the parameters are username, passwd, and realm.
3. In the Edit Params page, specify the desired settings.
Back in the Operation: invoke page, choose Invoke Operation.

Results of the operation will apply to system-jazn-data.xml files across all instances of the group.

Figure 7-1 Operation: Invoke

Description of "Figure 7-1 Operation: Invoke"

Figure 7-2 Search and Select: MBean

Description of "Figure 7-2 Search and Select: MBean"

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

Settings in the <jazn> Element for the File-Based Provider

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

Configuration to Automatically Create an Application-Specific jazn-data.xml File

Supplying an Application-Specific jazn-data.xml File

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

Using the File-Based Provider Across an OC4J Group

OC4J Basic Group Features

Cluster MBean Browser Features and the J2EEServerGroup MBean

Tools for File-Ba sed Provider Policy and Realm Management

Administering Insta nce-Level Security through Application Server Control

Re alm Configuration in the Repository File

OracleAS JAAS Provider Mi gration Tool

Migrating Principals from the prin cipals.xml File

Cluster M Bean Browser Features and the J2EEServerGroup MBean