Skip Headers

Oracle® Containers for J2EE Security Guide 10g Release 3 (10.1.3) B14429-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 5 Tasks and Guidelines in Setting Security

This chapter discusses key tasks and related guidelines to consider when setting up security for your applications:

- Guidelines for Password Management

- Tasks and Guidelines for Using Security Realms in OC4J

- Tasks for JAAS Mode and Authorization

- Using the Java Authorization Contract for Containers

- Packaging Considerations for OC4J Configuration Files

- Deployment Tasks and Guidelines for Security

- Post-Deployment Considerations

- Tasks for DataSourceUserManager

- See Also: The following Web site for OC4J "how-to" examples:
      http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html

## Guidelines for Password Management

Many OC4J components require passwords for authentication. Embedding these passwords into deployment and configuration files poses a security risk, especially if the permissions on the files allow them to be read by any user. To avoid this problem, OC4J provides two solutions:

- Password indirection, which replaces cleartext passwords with information necessary to look up the password in another location (`system-jazn-data.xml` in OC4J).

- Password obfuscation, which replaces passwords stored in cleartext files with an encrypted version of the password.

The rest of this discussion covers these topics:

- Creating an Indirect Password

- Specifying a Password Manager in system-application.xml

- Password Obfuscation in OC4J Configuration Files

### Creating an Indirect Password

The following configuration files support password indirection in one or more elements:

- `data-sources.xml`: `password` attribute of `<data-source>` element

- `ra.xml`: `<res-password>` element

- `rmi.xml`: `keystore-password` attribute of `<ssl-config>` element

- `application.xml`: `password` attributes of `<resource-provider>` and `<commit-coordinator>` elements

- `jms.xml`: `<password>` element

- `*-web-site.xml`: `keystore-password` attribute of `<ssl-config>` element

To make any of these passwords indirect, replace the literal password string with a string containing "`->`" followed by either the user name or by the realm and user name separated by a slash ("`/`").

Here are some examples of indirect versus direct passwords.

- `<data-source password="->Scott">`

  Look up `Scott` in the default realm, and use the password stored in the password manager.

- `<res-password="->customers/Scott">`

  Look up `Scott` in the `customers` realm, and use the password stored there.

- `<cluster password="martha">`

  The literal string "`martha`" is the password; the password is not indirect.

### Specifying a Password Manager in system-application.xml

The `<password-manager>` element in the OC4J-specific `system-application.xml` file (associated with the OC4J `system` application) specifies the security provider that is used to look up indirect passwords (discussed in the preceding section, "Creating an Indirect Password"). If this element is omitted, the security provider of the global application is used for authentication and authorization of indirect passwords. The `<jazn>` element within a `<password-manager>` element in `system-application.xml` can be different from the <`jazn>` element at the top level.

Note that for security reasons, credentials stored in Oracle Internet Directory cannot usually be retrieved in decrypted (cleartext) format, which means that Oracle Internet Directory cannot be used as a password manager for your application. To resolve this, you can specify the file-based provider as your application password manager, even when your application uses Oracle Identity Management as the security provider.

To do this, add an entry such as the following to the OC4J-specific `system-application.xml` file:

    <password-manager>
      <jazn provider="XML"
        location=ORACLE_HOME/j2ee/instance_name/config/system-jazn-data.xml>
      </jazn>
    </password-manager>

Note: By default, `system-jazn-data.xml` is used as the password manager.

### Password Obfuscation in OC4J Configuration Files

The JAAS configuration files `jazn.xml` and `system-jazn-data.xml` (or optionally an application-specific `jazn-data.xml` file) contain user names and passwords for JAAS authorization. To protect these files, OC4J uses password obfuscation.

Generally, whenever you update `jazn.xml` or `system-jazn-data.xml`, OC4J reads the file, then rewrites it with obfuscated (encrypted) versions of all passwords.

In addition (relevant for Oracle Identity Management), a setting for the `ldap.password` property within a `<jazn>` element, such as in `orion-application.xml`, is obfuscated. For example:

    <jazn ... >
       <property name="ldap.password" value="welcome123"/>
       ...
    </jazn>

In other OC4J configuration, you can avoid exposing password cleartext by using password indirection, as explained in "Creating an Indirect Password".

No te: In `system-jazn-data.xml` or an application-specific `jazn-data.xml` file, you can use clear (human-readable) passwords by setting the `clear` attribute of the `<credentials>` element to "`true`", though this is discouraged:
    <credentials clear="true">welcome</credentials>
To explicitly specify password obfuscation, precede the password with "!" (in which case "!" is not considered part of the password):
    <credentials>!welcome</credentials>

## Tasks and Guidelines for Using Security Realms in OC4J

In OC4J, both the file-based provider and LDAP-based Oracle Identity Management use the concept of security realms, introduced in "Security Realms". You can configure a single realm or multiple realms, and the default realm is specified through your OC4J configuration. Note that the concept of realms is not supported when you use external LDAP providers such as Active Directory or Sun Java System Directory Server.

This section discusses key details for using security realms to control authentication and authorization in OC4J, covering the following topics:

- Default Realm with the File-Based Provider or Oracle Identity Management

- Using the Default Realm

- Using a Nondefault Realm

- Using Multiple Realms

- Omitting the Realm Name When Retrieving an Authenticated Principal

### Default Re alm with the File-Based Provider or Oracle Identity Management

A default realm is specified in the `default-realm` attribute of the `<jazn>` element. For the file-based provider, this is either at application level in your `orion-application.xml` file, or at the OC4J level in the instance-level `jazn.xml` file. For Oracle Identity Management, this is in the bootstrap `jazn.xml` file.

For the file-based provider, `jazn.com` is configured as the default realm by default, at the instance level:

    <jazn provider="XML" location="./system-jazn-data.xml" default-realm="jazn.com" />

For Oracle Identity Management, the default realm is according to the Oracle Internet Directory, where it is determined during Oracle Internet Directory installation. After you associate OC4J with an Oracle Internet Directory instance, the default realm is reflected at the OC4J instance level, such as in the following example:

    <jazn provider="LDAP" location="ldap://www.example.com:636" default-realm="us"/>

"Using the Default Realm", discusses guidelines to be aware of when you use the default realm.

Important: A default realm should always be specified, even if you use only one realm. For the file-based provider, this means you should specify a default realm when you configure your security provider during application deployment. Do not remove configuration of the `jazn.com` realm from `system-jazn-data.xml`; it is there by default and must remain there for use by the OC4J `system` application.

### Evaluation of the Default Realm for File-Based Provider or Oracle Identity Management

As noted in the preceding section, a default realm should always be configured. However, for reference purposes only, this section discusses the progression that is followed to determine the default realm if one is not specified, when using the file-based provider or Oracle Identity Management.

If your application uses the file-based provider:

1. OracleAS JAAS Provider looks for default realm configuration at the application level, in the `orion-appliation.xml` file. If a default realm is found there, it is used as the default realm for your application.

2. If there is no default realm setting at the application level, OracleAS JAAS Provider looks for default realm configuration at the OC4J instance level, in the `jazn.xml` file:

   - If `jazn.xml` sets `provider="XML"`, OracleAS JAAS Provider uses the default realm specified in `jazn.xml`, if one is specified, as the default realm for your application. If none is specified, an error is thrown to indicate that you are missing the default realm attribute.

   - If `jazn.xml` sets `provider="LDAP"`, OracleAS JAAS Provider uses `jazn.com` as the default realm for your application.

If your application uses Oracle Identity Management:

1. If configuration specifies the LDAP-based provider both for your application and at the OC4J instance level (in `jazn.xml`), then OracleAS JAAS Provider looks for default realm configuration in `jazn.xml`. If a default realm is found there, it is used as the default realm for your application.

2. If configuration does not specify the LDAP-based provider at the OC4J instance level, or if there is no default realm setting at the instance level, the Oracle Internet Directory default subscriber is used as the default realm. (This is configured in the Oracle Internet Directory server.)

### Using the Default Realm

For authentication, when you use the default realm, there is no need to prefix the realm name with a user name. For example, if a user `scott` is in the default realm `jazn.com`, for authentication the user name need only be specified as "`scott`".

This is also true for applicable OC4J components and services such as JNDI, JMS, and J2CA.

Similarly, for password indirection, the OC4J deployment descriptor need not prefix the realm name in the user name specified for indirection: "`scott`".

### Using a Nondefault Realm

If you are using a nondefault realm—such as `acme.com`, for this discussion—you must always prefix user names with the realm name. To authenticate the user `scott` in `acme.com`, for example, you would have to specify "`acme.com/scott`", not just "`scott`".

This is also the case for applicable OC4J components and services such as JNDI, JMS, and J2CA.

Similarly, for password indirection, the OC4J deployment descriptor must prefix the realm name in the user name specified for indirection, if the user is in a nondefault realm: "`acme.com/scott`".

### Using Multiple Realms

When multiple realms are configured, you must prefix user names with the realm name for any nondefault realm that you use. For this discussion, assume the realms `jazn.com`, `acme.com`, and `example.org` are configured, with `jazn.com` being the default realm. Further assume user `scott` is in `jazn.com`, while user `ralph` is in `example.org`.

To specify `scott` for authentication, you need only specify the user as "`scott`", because he is in the default realm `jazn.com`.

To specify `ralph` for authentication, you must specify "`example.org/ralph`".

This is also the case for applicable OC4J components and services such as JNDI, JMS, and J2CA. The realm name must be specified for a user in any nondefault realm.

Similarly, for password indirection, the OC4J deployment descriptor must prefix the realm name in the user name specified for indirection if the user is in any nondefault realm: "`example.org/ralph`". But you need not specify the realm name for any user in the default realm, such as "`scott`".

Important: Always set `jaas.username.simple` to "`false`" when multiple realms are configured. (See the next section, "Omitting the Realm Name When Retrieving an Authenticated Principal".)

### Omit ting the Realm Name When Retrieving an Authenticated Principal

Unless you configure custom realms, it is typically desirable to omit the realm name from the authenticated principal that is returned by key methods for servlets, EJBs, and Web services. In OC4J, use the `jaas.username.simple` property to control this behavior. This property affects the following methods:

- `getUserPrincipal()` method of any `HTTPServletRequest` instance (servlets)

- `getRemoteUser()` method of any `HTTPServletRequest` instance (servlets)

- `getCallerPrincipal()` method of any `EJBContext` instance (EJBs)

- `getUserPrincipal()` method of any `ServletEndpointContext` instance (Web services)

With a "`true`" property setting, which is the default, principal names returned by these methods do not include the realm name: for example, "`scott`".

If you set the property to "`false`", then principal names returned by these methods are prefixed with the realm name: for example, "`jazn.com/scott`".

To specify a "`false`" setting, use a `<property>` subelement of the `<jazn>` element (in `orion-application.xml` for application level, or in the instance-level `jazn.xml` file for OC4J instance level) as follows:

    <jazn ... >
       ...
       <property name="jaas.username.simple" value="false" />
       ...
    </jazn>

Important: Always set `jaas.username.simple` to "`false`" when multiple realms are configured.

## Tasks for JAAS Mode and Authorization

This section provides sample code for the following steps, to use J2EE and JAAS authorization in an application:

1. Use J2EE Authorization

2. Use OracleAS JAAS Provider Policy Management

3. Use OracleAS JAAS Provider JAAS Mode

The samples here use a servlet method, but the basic functionality is similar for EJBs.

See Also: "JAAS Authorization and JAAS Mode" for an overview of features shown here Appendix B, "OracleAS JAAS Provider Samples" for the complete example

### Use J2EE Authorization

This sample servlet `doGet()` method uses standard J2EE authorization methods to retrieve a user and principal, and determine whether a user is in the specified role.

    public void doGet(HttpServletRequest request, HttpServletResponse response)
                throws ServletException, IOException {
        ServletOutputStream out = response.getOutputStream();

        response.setContentType("text/html");
        out.println("<HTML><BODY bgcolor=\"#FFFFFF\">");
        out.println("Time stamp: " + new Date().toString());
        out.println("request.getRemoteUser = " + request.getRemoteUser() + "<br>");
        out.println("request.isUserInRole('ar_developer') = " +
                     request.isUserInRole("ar_developer") + "<br>");
        out.println("request.getUserPrincipal = " +
                     request.getUserPrincipal() + "<br>");
        out.println("</BODY>");
        out.println("</HTML>");
    }

### Use OracleAS JAAS Provider Policy Management

In this example, the `doGet()` method shown in the preceding section, "Use J2EE Authorization", is expanded to use the OracleAS JAAS Provider policy management API to grant file permissions to a user.

    public void doGet(HttpServletRequest request, HttpServletResponse response)
           throws ServletException, IOException {
       ServletOutputStream out = response.getOutputStream();

       response.setContentType("text/html");
       out.println("<HTML><BODY bgcolor=\"#FFFFFF\">");
       out.println("Time stamp: " + new Date().toString());
       out.println("request.getRemoteUser = " + request.getRemoteUser() + "<br>");
       out.println("request.isUserInRole('ar_developer') = " +
                    request.isUserInRole("ar_developer") + "<br>");
       out.println("request.getUserPrincipal = " +
                    request.getUserPrincipal() + "<br>");

    //Grant Permissions to a user developer

    //get JAZNConfiguration related info
       JAZNConfig jc = JAZNConfig.getJAZNConfig();

       //create a Grantee for "developer"
       RealmManager realmmgr = jc.getRealmManager();
       Realm realm = realmMgr.getRealm("jazn.com");
       UserManager userMgr = realm.getUserManager();
       final RealmUser user = userMgr.getUser("developer");

       //grant scott file permission
       JAZNPolicy policy = jc.getPolicy();
       if ( policy != null) {
          Grantee gtee = new Grantee( (Principal) user);
          java.io.FilePermission fileperm =
                                 new java.io.FilePermission("foo.txt", "read");
          policy.grant( gtee, fileperm);
       }

       out.println("</BODY>");
       out.println("</HTML>");
    }

See Also: Oracle Identity Management Application Developer's Guide for details about JAAS policy management APIs.

### Use OracleAS JAAS Provider JAAS Mode

In this example, the `doGet()` method shown in "Use J2EE Authorization" is expanded to create and check permissions. Furthermore, assume the JAAS mode `doAsPrivileged`, which is set with configuration such as the following in the application `orion-application.xml` file (which specifies the file-based provider in this example):

    <orion-application ... >
       ...
       <jazn provider="XML" jaas-mode="doAsPrivileged" />
       ...
    </orion-application>

The code follows. Because of the JAAS mode setting, the action method, in this case `doGet()`, will be executed by OC4J within a `Subject.doAsPrivileged()` block for the authenticated subject.

        public void doGet(HttpServletRequest request, HttpServletResponse response)
                throws ServletException, IOException {
           ServletOutputStream out = response.getOutputStream();

           response.setContentType("text/html");
           out.println("<HTML><BODY bgcolor=\"#FFFFFF\">");
           out.println("Time stamp: " + new Date().toString());
           out.println
               ("request.getRemoteUser = " + request.getRemoteUser() + "<br>");
           out.println("request.isUserInRole('ar_developer') = " +
                        request.isUserInRole("ar_developer") + "<br>");
           out.println
               ("request.getUserPrincipal = " + request.getUserPrincipal() + "<br>");

          //create Permission
          FilePermission perm = new FilePermission("/home/developer/foo.txt","read");
          {
             //get current AccessControlContext
             AccessControlContext acc = AccessController.getContext();

             javax.security.auth.Policy currPolicy =
                                        javax.security.auth.Policy.getPolicy();

             // Query policy now
             out.println("Policy permissions for this subject are " +
                          currPolicy.getPermissions(Subject.getSubject(acc),null));

             //Check Permissions
             out.println("Policy.impiles permission: "+ perm +" ? " +
             currPolicy.getPermissions(Subject.getSubject(acc),null).implies(perm));
          }
          out.println("</BODY>");
          out.println("</HTML>");
       }

## Using the Java Authorization Contract for Containers

This section describes what you must do to use the Oracle Java ACC provider in OC4J, covering the following topics:

- System Properties to Enable Java ACC Features

- System Properties to Specify the Java ACC Provider

Note: Java ACC is supported only for the file-based provider. Generated policies are stored in `system-jazn-data.xml`.

See Also: "Implementation of Java Authorization Contract for Containers" for an overview

### System Properties to Enable Java ACC Features

By default, Java ACC is disabled in OC4J. It can be enabled with the following system property setting at OC4J startup:

    -Doracle.oc4j.security.jacc=true

Java ACC trace logging can be enabled with the following system property setting at OC4J startup:

    -Doracle.oc4j.security.jacc.debug=true

### System Properties to Specify the Java ACC Provider

To employ a Java ACC provider, the system properties described in Table 5-1 must be set appropriately at application server startup. For the Oracle Java ACC provider, this happens automatically when you enable Java ACC, with the properties being set as shown in parentheses.

Table 5-1 System Properties for the Java ACC Provider

Property | Description
--- | ---
javax.security.jacc.policy.provider | Class name of the policy provider (oracle.security.jacc.provider.J2SEPolicy)
javax.security.jacc.policy. PolicyConfigurationFactory.provider | Class name of the policy mapping configuration factory (oracle.security.jacc.provider. JACCPolicyConfigurationFactory)
oracle.security.jacc.provider. RoleMappingConfigurationFactory.provider | Class name of the role mapping configuration factory (oracle.security.jacc.provider. JACCRoleMappingConfigurationFactoryImpl)

## Packaging Considerations for OC4J Configuration Files

This section discusses packaging considerations for OC4J-specific configuration files:

- Configuration Tasks and Considerations in the Deployment Descriptors

- Supplying an Application-Specific jazn-data.xml File

### Configuration Tasks and Considerations in the Deployment Descriptors

When you package your application, you will include standard deployment descriptors such as `application.xml`, `web.xml`, and `ejb-jar.xml`. You can also optionally provide OC4J descriptors such as `orion-application.xml`, `orion-web.xml`, and `orion-ejb-jar.xml`, or they may be provided for you, such as according to your settings in Application Server Control Console when you deploy.

This section summarizes some considerations for your deployment descriptors before you package your application.

#### Configuration to Use the Instance-Level File-Based Provider

If there is no `<jazn>` element in the `orion-application.xml` file when you deploy your application (neither placed there automatically by Application Server Control or other deployment processing, nor placed there manually), the default is as follows:

    <jazn provider="XML" />

This results in use of the instance-level file-based provider with `system-jazn-data.xml` as the repository.

Alternatively, you can explicitly place this configuration in `orion-application.xml` in order to use the instance-level file-based provider.

#### Configuration to Automatically Create jazn-data.xml

If `orion-application.xml` is configured exactly as follows:

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

But the `jazn-data.xml` file is not packaged with the application, then one will be created during deployment.

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

1. In `orion-application.xml`, specify the following:

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

2. Package the `jazn-data.xml` file in the `/META-INF` directory of the EAR file.

## Deployment Tasks and Guidelines for Security

This section discusses security issues to consider when deploying your application, covering the following topics:

- Overview of Deployment Considerations

- Deploying an Application

- Specifying a Security Provider

- Mapping J2EE Security Roles to JAAS Roles

See Also: Oracle Containers for J2EE Deployment Guide for a full discussion of deployment and related considerations

### Overview of Deployment Considerations

The security provider is designed to work with the J2EE declarative security model. This declarative model requires little or no programming to use JAAS security in your application. Instead, most security decisions are made as part of the deployment process, making it easy to make changes without requiring re-coding. If the declarative model is not sufficient, the security provider also supports programmatic security in the same manner that JAAS is used in any J2SE environment.

Using the declarative security model, the deployer must make the following security-related decisions:

- Decide which security provider you want to use. The Oracle Application Server includes Oracle Identity Management, which uses the LDAP-based Oracle Internet Directory as the repository, and the file-based provider, which uses an XML file as the repository. OC4J also supports external (third-party) LDAP providers, custom security providers (custom login modules), and, beginning in the OC4J 10.1.3 implementation, the COREid Access provider.

- Determine the J2EE logical roles that are assumed in the application, then define these roles in the deployment descriptors. For example, an HR application may assume that the J2EE logical role `hr_manager` is running the application; the deployer must define that role.

- Determine the authorization constraints that apply to these roles and define them in the deployment descriptors. For web modules, these constraints typically apply to URL patterns as defined in the J2EE specification. EJB modules typically have constraints at the EJB-method level.

- Map the security roles (including the application-specific roles, if they exist) to users and roles defined by the OracleAS JAAS Provider. For example, the J2EE logical role called `hr_manager` may be mapped to a given set of users defined by the OracleAS JAAS Provider.

- Consider whether you have any code that you will want to load as shared libraries (login modules, for example).

### Deploying an Application

This section discusses how to deploy an application, focusing on the functionality of the Application Server Control Console.

#### Deploying an Application through Application Server Control

Details about deploying an application to OC4J, including information about deployment plans, are provided in the Oracle Containers for J2EE Deployment Guide. This section reviews the basic steps:

1. In the OC4J Home page, select the Applications tab.

2. In the resulting Applications page, choose Deploy.

3. In the resulting Deploy: Select Archive page (page 1 of 3), specify the archive file to deploy and your desired choice for a deployment plan.

4. In the Deploy: Application Attributes page (page 2 of 3), specify the desired application name, parent application, Web site, and context root.

5. In the Deploy: Deployment Settings page (page 3 of 3), you can choose any of the following tasks:

   - Map Environment References (if applicable)

   - Select Security Provider

   - Map Security Roles (if applicable)

   - Configure EJBs (if applicable)

   - Configure Clustering

   - Configure Class Loading

   For security, selecting a security provider and mapping security roles are of particular interest. You may also want to configure class loading in order to import shared libraries, such as if you have login modules that you want to load as shared libraries.

6. In the Deploy: Deployment Settings page, when you are done with any applicable tasks mentioned in the previous step, select Deploy.

See Also: "Specifying the Security Provider through Application Server Control" "Specifying Security Role Mapping through Application Server Control" "Using Login Modules as OC4J Shared Libraries"

### Specifying a Security Provider

This section discusses how to specify the security provider using Application Server Control Console, as well as considerations for using the file-based provider versus the LDAP-based provider.

#### Considering the File-Based Provider Versus Oracle Identity Management

Generally, use the file-based provider in development environments and in deployed applications with a small user population. Use Oracle Identity Management in larger production environments.

Compared to the file-based provider, Oracle Identity Management offers better security and performance. The centralized Oracle Internet Directory server scales well as the number of applications and users grows, and enables you to configure cache parameters to improve overall performance of authentication and authorization.

In addition, Oracle Internet Directory offers features such as centralized account creation and management, single passwords, and credential management.

Note: To use Oracle Identity Management, the OC4J instance must have been previously associated with Oracle Internet Directory through Application Server Control.

#### Specifying the Security Provider through Application Server Control

In Application Server Control Console, specify the security provider during deployment, from the Deploy: Deployment Settings page (see "Deploying an Application through Application Server Control" for how to get to this page), as follows:

1. Choose the Select Security Provider task.

2. In the resulting Deployment Settings: Select Security Provider page, choose the desired security provider from the dropdown list. The choices are:

   - File-Based

   - Oracle Identity Management

   - Third Party LDAP Server (for an external LDAP provider)

   - Custom (for a custom login module)

3. Each type of security provider involves its own set of configuration tasks, documented in the following locations:

   - "Specifying Oracle Identity Management during Deployment"

   - "Configuring the File-Based Provider during Application Deployment"

   - "Specifying and Configuring an External LDAP Provider during Deployment"

   - "Specifying and Configuring a Custom Security Provider during Deployment"

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

### Mapping J2EE Security Roles to JAAS Roles

This section discusses various aspects of the following:

- Defining security roles in an application and referencing them to logical J2EE security roles in the standard deployment descriptor

- Mapping J2EE security roles to JAAS security roles in the OC4J configuration, and how to accomplish this mapping in Application Server Control

The information is organized as follows:

- Application Role Definitions and References

- Specifying Security Role Mapping through Application Server Control

- Mapping J2EE Roles to JAAS Roles in OC4J Configuration Files

- Using the OC4J PUBLIC Role to Allow General Access by Authenticated Users

Note: Security role mappings are not inherited from a parent application.

See Also: "Overview of Security Role Mapping" "Web Application Security Role Configuration" "Mapping Logical Roles to Users and Roles" (for EJBs)

#### Application Role Definitions and References

The process of role definitions and references includes the following steps:

1. During development, define roles as classes that implement the `java.security.Principal` interface.

2. In your standard deployment descriptor (`web.xml` or `ejb-jar.xml`), use `<security-role>` elements to define logical security roles, such as in the following example:

       <security-role>
          <role-name>sr_developer</role-name>
       </security-role>

3. Use `<security-role-ref>` elements in the standard deployment descriptor to map from the roles you have developed in your application to the logical roles you have defined in the descriptors, such as in the following example (where `ar_developer` is defined in the application):

       <security-role-ref>
          <role-name>ar_developer</role-name>
          <role-link>sr_developer</role-link>
       </security-role-ref>

After these steps, mappings from the logical roles to roles defined in the OC4J container are defined in the OC4J descriptors (`orion-web.xml`, `orion-ejb-jar.xml`, or `orion-application.xml`). These files are updated, as appropriate, through the mappings you define when you deploy an application through Application Server Control, for example, and are reflected in `<security-role-mapping>` elements. These mappings are discussed in the next two sections, "Specifying Security Role Mapping through Application Server Control" and "Mapping J2EE Roles to JAAS Roles in OC4J Configuration Files".

See Also: The preceding discussion leaves out some details, which differ between Web applications and EJBs. Refer to the following for additional information: "Web Application Security Role Configuration" "Authenticating and Authorizing EJB Applications"

#### Specifying Security Role Mapping through Application Server Control

In Application Server Control Console, map security roles during deployment, from the Deploy: Deployment Settings page (see "Deploying an Application through Application Server Control" for how to get to this page), as follows:

1. Select the Map Security Roles task.

2. In the resulting Deployment Settings: Map Security Roles page, choose the Map Role task for each role you want to map. (You can also choose Clear All Mappings.)

3. In the resulting page for the role, you can do any of the following:

   - Map all users and groups to the role.

   - Map selected users to the role. Choose Add Existing User, then specify the desired users in the Select and Search: Users page, then choose Select. If Add Existing User does not list the desired user, then use the Add User feature.

   - Map selected groups to the role. Choose Add Existing Group, then specify the desired groups in the Select and Search: Groups page, then choose Select. If Add Existing Group does not list the desired group, then use the Add Group feature.

   - Choose Continue when you are finished mapping users and groups.

4. Back in the Deployment Settings: Map Security Roles page, choose OK.

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

These actions create `<security-role-mapping>` elements in the applicable OC4J configuration file, such as `orion-application.xml`, `orion-web.xml`, `orion-ejb-jar.xml`, as shown in the next section, "Mapping J2EE Roles to JAAS Roles in OC4J Configuration Files".

Note: There is no way to alter security mappings through Application Server Control after deployment. You would have to update the configuration manually (as shown in "OC4J Mapping of J2EE Roles to JAAS Roles" and "Mapping Logical Roles to Users and Roles") and then restart or redeploy the application.

#### Mapping J2EE Roles to JAAS Roles in OC4J Configuration Files

Portable J2EE security roles defined in a standard J2EE deployment descriptor are mapped to JAAS roles in OC4J through `<security-role-mapping>` settings in the `orion-application.xml` file (to apply throughout a J2EE application), `orion-web.xml` file (to apply to a particular Web application), or `orion-ejb-jar.xml` file (to apply to a particular EJB application).

In this example, the JAAS `sr_developer` security role is mapped to the OC4J `developer` role. Note that a `<group>` subelement under a `<security-role-mapping>` element corresponds to a role in the OracleAS JAAS Provider. You can also have `<user>` subelements to map to individual users.

    <security-role-mapping name="sr_developer">
       <group name="developer" />
    </security-role-mapping>

This association permits the `developer` role to access resources that are accessible for the `sr_developer` role.

Consider a user `john`, for example, who is a member of the `developer` role. Because this role is mapped to the J2EE role `sr_developer`, `john` has access to the application resources available to the `sr_developer` role.

#### Us ing the OC4J PUBLIC Role to Allow General Access by Authenticated Users

For situations where you care only about authentication, not authorization, OC4J supports a mode where any authenticated user is allowed access to a given application or resource. This is supported through the `PUBLIC` role, and can be configured down to a per-URL or per-method basis as desired. This involves the following steps:

1. If you do not already have a logical role intended for public access, you can define such a role in `web.xml` (for a Web application) or in `ejb-jar.xml` (for an EJB).

   For example, in `web.xml`:

       <web-app>
          ...
          <security-role>
             <role-name>public_role</role-name>
          </security-role>
          ...
          <auth-constraint>
             <role-name>public_role</role-name>
          </auth-constraint>
          ...
       </web-app>

   Or, in `ejb-jar.xml`:

       <assembly-descriptor>
          ...
          <security-role>
             <role-name>public_role</role-name>
          </security-role>
          ...
          <method-permission>
             <role-name>public_role</role-name>
             <method>method</method>
          </method-permission>
          ...
       </assembly-descriptor>

2. Map your public role to the `PUBLIC` role in `orion-application.xml` (for a Web application) or `orion-ejb-jar.xml` (for an EJB).

   To map the role defined in `web.xml` above, include the following in `orion-application.xml`:

       <orion-application>
          ...
          <security-role-mapping name="public_role">
             <group name="{{PUBLIC}}"/>
          </security-role-mapping>
          ...
       </orion-application>

   Or, for an EJB, use the `<security-role-mapping>` element in `orion-ejb-jar.xml` instead (where it is a subelement of the `<assembly-descriptor>` element).

Note: This example assumes the default setting of "`{{PUBLIC}}`" for the OC4J public group. This may be overridden through the OracleAS JAAS Provider `public.group` property.

## Post-Deployment Considerations

This section discusses the following consideration for after you have deployed your application:

- Navigating to the Security Provider Page for Your Application

### Navigating to the Security Provider Page for Your Application

After you have deployed your application, you can go to the Security Provider page for your application in the Application Server Control Console to examine or update the application-level security settings. Starting from the OC4J Home page for your OC4J instance:

1. Choose the Administration tab.

2. In the Administration page, go to the Security Providers task (under "Security").

3. In the Security Providers page, under "Application Level Security", go to the Edit task for your application.

This brings you to the Security Provider page, displaying information on the provider for your application and allowing you to update settings or change to a different security provider.

## Tasks for DataSourceUserManager

As an alternative to using security providers documented elsewhere in this manual, the OC4J 10.1.3 implementation continues to support the `DataSourceUserManager` class, in package `com.evermind.sql`, for retrieving user data from a database. This section discusses features of this class, and how to configure your application to use it. The following topics are covered:

- DataSourceUserManager Properties

- Configuring an Application to Use DataSourceUserManager

Important: The `DataSourceUserManager` class is deprecated in the OC4J 10.1.3 implementation, but is still supported for backward compatibility. In future releases, it will be replaced with equivalent functionality using a custom login module. In the 10.1.3 implementation, `DataSourceUserManager` obtains group information only from the database, which differs from the behavior in previous implementations. Therefore, you must now map groups to users in the database, as applicable.

### DataSourceUserManager Properties

When you configure `DataSourceUserManager` (as described later, in "Configuring an Application to Use DataSourceUserManager"), you can specify values for the properties described in Table 5-2, as appropriate. The `DataSourceUserManager` instance uses these properties to access the user-defined database table that lists the current users and their associated credentials.

Table 5-2 DataSourceUserManager Properties

Property | Description
--- | ---
dataSource | A JNDI location for the installed data source (database) to use
table | Name of the database table containing user data
usernameField | Name of the column for user names in the database table
passwordField | Name of the column for passwords in the database table
certificateIssuerField | An identifier for the certificate issuer, if applicable
certificateSerialField | The serial ID of the certificate issuer, if applicable
localeField | The locale, if applicable
defaultGroups | Comma-delimited list of groups that the users are members of
groupMembershipTableName | Name of an optional database table that maps users to groups, if the use of `defaultGroups` is not sufficient
groupMembershipUserNameFieldName | Name of the column for user names in the group membership database table, if applicable
groupMembershipGroupFieldName | Name of the column for group names in the group membership database table, if applicable
staleness | Number of milliseconds for which a fetched set of user data will be valid. The default setting is -1 (forever)
casing | Flag that controls how `DataSourceUserManager` handles character case for user names (but not group names) when trying to match a name against the list of known users in the database The default "`sensitive`" setting results in case-sensitive matching. For the "`toupper`" and "`tolower`" settings, the name is converted to all uppercase or all lowercase, respectively, for purposes of matching.
debug | Flag to enable output of debug information

### Configuring an Application to Use DataSourceUserManager

To use `DataSourceUserManager`, configure it in a `<user-manager>` element in your `orion-application.xml` file. This is a subelement of `<orion-application>`, and must be configured manually. There is no `UserManager` support in the Application Server Control 10.1.3 implementation.

Specify the `DataSourceUserManager` fully qualified name in the `class` attribute of `<user-manager>`. Use a `<property>` subelement to specify the name and value of each property you want to set.

See Also: The preceding section, "DataSourceUserManager Properties"

Here is an example:

    <orion-application ... >
       ...
       <user-manager class="com.evermind.sql.DataSourceUserManager">
          <property name="dataSource" value="jdbc/OracleCoreDS" />
          <property name="table" value="j2ee_users" />
          <property name="usernameField" value="username" />
          <property name="passwordField" value="password" />
          <property name="groupMembershipTableName" value="second_table" />
          <property name="groupMembershipGroupFieldName" value="group" />
          <property name="groupMembershipUserNameFieldName" value="userId" />
       </user-manager>
       ...
    </orion-application>