Skip Headers

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

Previous | Next |

# 3 Understanding OC4J Security

This chapter describes security issues affecting J2EE applications in OC4J.

This chapter contains these topics:

- Introduction

- Security Considerations During Development and Deployment

- OC4J and the OracleAS JAAS Provider

- Authentication in the J2EE Environment

- Authorization in the J2EE Environment

- Lightweight J2EE Single Sign-On

## Introduction

The following are components of the OC4J security architecture:

- The OracleAS JAAS Provider, which provides support for storage, retrieval, and administration of realm information (users and roles) and policy information (permissions). The OracleAS JAAS Provider supports two possible repositories or provider types:

  - XML-based provider type

  - LDAP-based Oracle Internet Directory (available only with Oracle Application Server Infrastructure installation)

- JAAS login modules, such as the `RealmLoginModule`, third-party login modules, and custom login modules

  See Also: "Provider Types" for further information about provider types Oracle Application Server Installation Guide for information on installing Oracle Internet Directory

## Security Considerations During Development and Deployment

The OracleAS JAAS 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 OracleAS JAAS Provider also supports programmatic security in the same manner that JAAS is used in any J2SE environment.

### Development

If your application relies on the declarative security model (where J2EE security roles are defined in deployment descriptors, such as `web.xml`), the developer must determine if the application uses application-specific roles. If so, the developer must define these roles so that they can be mapped to the J2EE logical roles during the deployment phase.

### Deployment

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

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

- Decide whether to use an XML flat file or Oracle Internet Directory (LDAP) as the repository for the OracleAS JAAS Provider. This also determines which provider, XML-based or LDAP-based, and user manager the application uses.

- Map the security roles (including the application-specific roles, if they exist) to users and groups defined by the OC4J user manager (for instance, `JAZNUserManager`). For example, the J2EE logical role called `hr_manager` may be mapped to a given set of users defined by the OC4J user manager.

See Also: Chapter 6, "Security Considerations During Application Deployment" for information on making and implementing these decisions Oracle Application Server Containers for J2EE User's Guide for a full discussion of deployment

## OC4J and the OracleAS JAAS Provider

OC4J is a J2EE container that accepts HTTP and RMI client connections. These connections permit access to servlets, JavaServer Pages, and Enterprise JavaBeans (EJBs).

J2EE containers separate business logic from resource and lifecycle management. This enables developers to focus on writing business logic, rather than writing enterprise infrastructure. For example, Java servlets simplify Web development by providing an infrastructure for component, communication, and session management in a Web container integrated with a Web server.

### OC4J Integration

The OracleAS JAAS Provider is integrated with OC4J and with OracleAS Single Sign-On to enhance application security. This integration provides the following benefits:

- `run-as` identity support, delegation support (from servlet to Enterprise JavaBeans)

- Full support for OracleAS Single Sign-On

- Support for custom login modules

### JAZNUserManager

The OracleAS JAAS Provider is supported through `JAZNUserManager`. `JAZNUserManager`, an implementation of the OC4J `UserManager` interface, supports the following features:

- Secure storage of obfuscated passwords

- Full role-based access control (RBAC), including hierarchical roles

- Full support for the Java 2 permission model and JAAS

- Secure implementation based on the Java 2 permission model, allowing non-trusted (or partially trusted) code to run in the same JVM as the OracleAS JAAS Provider

- OracleAS Single Sign-On integration with OC4J

- `RealmLoginModule` integration in non-OracleAS Single Sign-On environments

- Support for custom JAAS login modules

- Identity propagation

### Authentication Environments

The OracleAS JAAS Provider integrates with several different login authentication environments in a J2EE application.

- OracleAS Single Sign-On

  Uses OracleAS Single Sign-On to authenticate logins.

- SSL

  - Uses Secure Socket Layers for client certificate-based authentication.

  - Uses a login module (for example, `RealmLoginModule`) to authenticate logins.

- Basic Authentication

  - Prompts user directly for user name and password, without going through OracleAS Single Sign-On.

  - Uses a login module (for example, `RealmLoginModule`) to authenticate logins.

- Form-based Authentication

  When the user attempts to access a protected resource, OC4J checks whether the user has already been authenticated. If not, OC4J displays an application-specific login prompt for user name and password.

- Digest Authentication

  With the digest mechanism (a standard but optional feature of J2EE), the credentials that a client presents to authenticate itself consist of an MD5 digest. This is transmitted in the request message.

The following sections discuss how the OracleAS JAAS Provider integrates with each of these authentication types.

### Enabling OracleAS Single Sign-On in J2 EE Applications

OracleAS Single Sign-On lets a user access multiple applications with a single set of login credentials. Figure 3-1 shows JAAS integration in an application running in an OracleAS Single Sign-On-enabled J2EE environment.

Note: Alternatively, there is a single sign-on implementation specifically for the OC4J environment. See "Lightweight J2EE Single Sign-On".

Figure 3-1 OracleAS Single Sign-On and J2EE Environments

Description of "Figure 3-1 OracleAS Single Sign-On and J2EE Environments"

#### OracleAS Single Sign-On-Enabled J2EE Environments: Typical Scenario

This section describes the responsibilities of Oracle components when an HTTP client request is initiated in an OracleAS Single Sign-On-enabled J2EE environment.

1. An HTTP client attempts to access a Web application, WebApp A1, hosted by OC4J (the Web container for executing servlets). Oracle HTTP Server (using an Apache listener) handles the request.

2. `mod_osso`/Oracle HTTP Server receives the request then:

   1. Determines that WebApp A1 application requires Web-based OracleAS Single Sign-On for authenticating HTTP clients.

   2. Redirects the HTTP client request to the Web-based OracleAS Single Sign-On (because it has not yet been authenticated).

3. The HTTP client is authenticated by OracleAS Single Sign-On through a user name and password or through a user certificate. OracleAS Single Sign-On then:

   1. Validates the user's stored login credentials.

   2. Sets the OracleAS Single Sign-On cookie (including the user's distinguished name and realm).

   3. Redirects back to the WebApp A1 application (in OC4J).

4. The OracleAS JAAS Provider retrieves the OracleAS Single Sign-On user.

See Also: Oracle Application Server Single Sign-On Administrator's Guide, for full details on OracleAS Single Sign-On

### Integrating the OracleAS JAAS Provider with SSL-Enabled Applications

SSL is an industry standard protocol for managing the security of message transmission on the Internet. Figure 3-2 shows JAAS integration in an application running in an SSL-enabled J2EE environment.

Figure 3-2 Oracle Component Integration in SSL-Enabled J2EE Environments

Description of "Figure 3-2 Oracle Component Integration in SSL-Enabled J2EE Environments"

### Integrating the OracleAS JAAS Provider with Basic Authentication

Basic authentication bypasses OracleAS Single Sign-On. Figure 3-3 shows specific JAAS integration in an application configured for Basic authentication in a J2EE environment.

Figure 3-3 Oracle Component Integration in J2EE Environment

Description of "Figure 3-3 Oracle Component Integration in J2EE Environment"

#### Basic Authentication J2EE Environments: Typical Scenario

This section describes the responsibilities of Oracle components when an HTTP client request is initiated in a J2EE environment configured for Basic authentication. In this environment, OracleAS Single Sign-On is not used. A login module (for example, `RealmLoginModule`) is used.

1. An HTTP client attempts to access a Web application (named WebApp A1) hosted by OC4J (the Web container for executing servlets).

2. OC4J invokes the `RealmLoginModule` whenever user credentials are required. For example, when a request hits a protected page, OC4J will ask the OracleAS JAAS Provider to authenticate the user, then the `RealmLoginModule` will be invoked to authenticate the user, using the credentials sent by the user via the browser over HTTP.

3. The OracleAS JAAS Provider retrieves the user.

See Also: Sun Java documentation for more information on J2EE: `http://java.sun.com/j2ee/`

## Authentication in the J2EE Environment

Authentication is the process of verifying the identity of a user in a computing system, often as a prerequisite to granting access to resources in a system. In Oracle Application Server, authentication in the J2EE environment is performed by the following:

- OracleAS Single Sign-On (for OracleAS Single Sign-On environments) or the OracleAS JAAS Provider `RealmLoginModule` or other login module (for non-OracleAS Single Sign-On environments)

  Before HTTP requests can be dispatched to the target servlet, the `JAZNUserManager` gets the authenticated user information (set by `mod_osso`) from the HTTP request object and sets the JAAS subject in OC4J.

  Note: There is a separate single sign-on implementation for standalone OC4J. See "Lightweight J2EE Single Sign-On".

- One of the following:

  - `JAZNUserManager`

  - `XMLUserManager`

  - A developer-supplied `UserManager`

    Note: Developer-supplied `UserManager` is deprecated and will be desupported in a future release.

### Running with an Authenticated Identity

You can choose to configure the `JAZNUserManager` so that a filter enables the target servlet to run with the permissions and roles associated with an authenticated identity or run-as identity. To do this, configure the `<jazn-web-app>` element.

See Also: "JAZNUserManager" for further information on options and configuration of the `JAZNUserManager` filter, including the `<jazn-web-app>` element

### Retrieving Authentication Information

The following `javax.servlet.HttpServletRequest` APIs retrieve authentication information within the servlet:

- `getRemoteUser()` for the authenticated user name

- `getAuthType()` for the authentication scheme

- `getUserPrincipal()` for the authenticated principal object

  Note: The returned principal is an instance of the interface `oracle.j2ee.security.User`, which extends the `java.security.Principal` interface.

- `getAttribute("javax.servlet.request.X509certificate")` for the SSL client certificate

## Authorization in the J2EE Environment

Authorization is the process of granting permissions and privileges to an authenticated user. This section discusses authorization within servlets.

If the servlet is configured to permit`doAs()`, the `JAZNUserManager` invokes an authenticated target servlet within a `Subject.doAs()` block to enable JAAS-based authorization in the target servlets.

Authorization is achieved through the following:

- `JAZNUserManager`

- Methods based on JAAS authorization:

  - `Servlet.service()` in the servlet

  - `Subject.doAs()` and `Subject.doAsPrivileged()` in the client

  - `SecurityManager.checkPermission()` in the server

    See Also: Configuring J2EE Authorization

### Security Role Mapping

Two distinct role types are available to application developers creating secure applications in J2EE environments: J2EE roles and JAAS roles. When these role types are mapped together using OC4J group mappings, users can access an application with a defined set of role permissions for as long as the user is mapped to this role.

This section describes these role types and how they are mapped together.

- J2EE Security Roles

- Deployment Roles and Users

- OC4J Group Mapping to J2EE Security Roles

#### J2EE Security Roles

The J2EE development environment includes a portable security roles feature defined in the `web.xml` file for servlets and JavaServer Pages (JSP). Security roles define a set of resource access permissions for an application. Associating a principal (in this case, a JAAS user) with a security role assigns the defined access permissions to that principal for as long as they are mapped to the role. For example, an application defines a security role called `sr_developer`:

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

You also define the access permissions for the `sr_developer` role.

     <security-constraint>
        <web-resource-collection>
          <web-resource-name>access to the entire application</web-resource-name>
          <url-pattern>/*</url-pattern>
        </web-resource-collection>
            <!-- authorization -->
        <auth-constraint>
          <role-name>sr_developer</role-name>
        </auth-constraint>
      </security-constraint>

#### Deployment Roles and Users

JAAS roles and users are defined depending on the provider type, LDAP-based or XML-based.

For example, with the XML-based provider type, `developer` is listed as a role in the `jazn-data.xml` file:

    <role>
      <name>developer</name>
      <members>
        <member>
          <type>user<type>
          <name>john<name>
        </member>
      </members>
    </role>

#### OC4J Group Mapping to J2EE Security Roles

OC4J enables you to map portable J2EE security roles defined in the J2EE `web.xml` file to groups in an `orion-application.xml` file.

The roles and users defined in your provider environment are mapped to the OC4J `developer` group role in the `orion-application.xml` file.

For example, the `sr_developer` security role is mapped to the group named `developer.`

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

Notice that a `<group>` entry in a `<security-role-mapping>` element corresponds to a role in the OracleAS JAAS Provider. Therefore, this association permits the `developer` group to access the resources allowed for the `sr_developer` security role.

In this paradigm, the user `john` is listed as a member of the `developer` role. Because the `developer` group is mapped to the J2EE security role `sr_developer` in the `orion-application.xml` file, `john` has access to the application resources defined by the `sr_developer` role.

## Lightweight J2EE Single Sign-On

This section describes the use of a lightweight single sign-on (SSO) alternative for OC4J. Oracle Application Server already offers an SSO component, known as OracleAS Single Sign-On and discussed earlier in this chapter, but this requires the installation of several components. For OC4J, a simpler alternative was required.

This chapter contains the following topics:

- Introduction to Lightweight J2EE Single Sign-On

- Configuring Lightweight J2EE Single Sign-On

- Enabling Lightweight J2EE Single Sign-On

### Introduction to Lightweight J2EE Single Sign-On

After a client has been authenticated in a given Web application, SSO allows the current security credential to be applied to additional Web applications within the same J2EE application (EAR file). OracleAS Single Sign-On is available for this functionality in a full Oracle Application Server environment (as described in "Enabling OracleAS Single Sign-On in J2EE Applications"), and now there is also a lighter-weight SSO alternative for use with OC4J.

Security credentials for a Web application are generally stored within HTTP client sessions. However, because the servlet specification dictates that an HTTP session can extend only across the scope of a single Web application, OC4J must use a component outside the session to manage J2EE SSO across Web applications. The chosen component for this implementation of lightweight J2EE Single Sign-On is a stateful session EJB.

When J2EE Single Sign-On is enabled, OC4J creates the stateful session bean automatically, including the home interface, bean interface, and implementation class. Once a user is successfully authorized for a Web application participating in J2EE Single Sign-On, OC4J registers the user with the bean.

OC4J also creates a J2EE SSO cookie. The cookie indicates to Web applications that there is an authenticated user for J2EE Single Sign-On.

Also be aware of the following:

- The lightweight J2EE SSO implementation works across distributed environments, assuming EJB replication is enabled for the J2EE SSO bean as shown in "Contents of Specialized orion-ejb-jar.xml File".

- The J2EE SSO implementation works with standalone OC4J. It will also work in a full Oracle Application Server (OPMN-managed) environment if all of the following are true:

  - Session replication is enabled for each Web application involved, through the `<distributable/>` subelement of `<web-app>` in the `web.xml` file.

  - EJB replication is enabled for the J2EE SSO bean.

  - You use only a single OC4J cluster island.

- The J2EE SSO implementation has a small performance impact.

- If a user who has been looked up has sufficient privilege to access the restricted resource, then OC4J displays the resource. Otherwise, a form authentication page is displayed, allowing a user with sufficient privilege to be specified for the login.

- If the HTTP session is invalidated, the user name is no longer set. The next attempted access of the resource will force another login through the form authentication page.

### Configuring Lightweight J2EE Single Sign-On

The 10.1.2 implementation of lightweight J2EE Single Sign-On requires a specialized JAR file, named `OC4JINTERNAL_httpSession.jar`, to be included in your EAR file. This JAR file must contain the following XML files, each with specific contents as described immediately below:

- `/META-INF/ejb-jar.xml`

- `/META-INF/orion-ejb-jar.xml`

#### Contents of Specialized ejb-jar.xml File

The `ejb-jar.xml` file must contain the following:

    <?xml version="1.0"?>
    <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
     1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">
    <ejb-jar>
       <display-name>stateful, ejb-jar:</display-name>
       <enterprise-beans>
          <session>
             <display-name>WebAppsClusterBean</display-name>
             <ejb-name>WebAppsClusterBean</ejb-name>
             <home>
                oracle.oc4j.server.ejb.httpSession.HttpSessionSharingSFSBHome
             </home>
             <remote>
                oracle.oc4j.server.ejb.httpSession.HttpSessionSharingSFSB
             </remote>
             <ejb-class>
                oracle.oc4j.server.ejb.httpSession.HttpSessionSharingSFSBBean
             </ejb-class>
             <session-type>Stateful</session-type>
             <transaction-type>Container</transaction-type>
          </session>
       </enterprise-beans>
       <assembly-descriptor>
          <container-transaction>
             <method>
                <ejb-name>WebAppsClusterBean</ejb-name>
                <method-name>*</method-name>
             </method>
             <trans-attribute>Supports</trans-attribute>
          </container-transaction>
          <security-role>
             <role-name>users</role-name>
          </security-role>
       </assembly-descriptor>
    </ejb-jar>

Note: The `<display-name>` elements are not required but are by convention. All other elements are required with settings as shown.

#### Contents of Specialized orion-ejb-jar.xml File

For a non-distributed environment, the `orion-ejb-jar.xml` file must contain the following:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE orion-ejb-jar PUBLIC "-//Evermind//DTD Enterprise JavaBeans 1.1
     runtime//EN" "http://xmlns.oracle.com/ias/dtds/orion-ejb-jar.dtd">
    <orion-ejb-jar>
       <enterprise-beans>
          <session-deployment name="WebAppsClusterBean"
                              location="webAppsCluster/WebAppsClusterBean"
                              idletime="600" copy-by-value="false"  />
       </enterprise-beans>
       <assembly-descriptor>
          <security-role-mapping name="users" />
          <default-method-access>
             <security-role-mapping name="default-ejb-caller-role"
                                    impliesAll="true" />
          </default-method-access>
       </assembly-descriptor>
    </orion-ejb-jar>

For a distributed (clustered) environment, you must add the attribute setting `replication="EndOfCall"` to the `<session-deployment>` element, as follows:

          <session-deployment name="WebAppsClusterBean"
                              location="webAppsCluster/WebAppsClusterBean"
                              idletime="600" copy-by-value="false"
                              replication="EndOfCall" />

There are no other configuration differences for a distributed versus non-distributed environment.

Notes: In the `<security-role-mapping>` element, substitute the appropriate role for `default-ejb-caller-role`. The `idletime` attribute specifies a timeout value, in seconds, for the stateful session bean. You can adjust this as desired; however, it must be no less than your HTTP session timeout. Do not change any other settings.

### Enabling Lightweight J2EE Single Sign-On

Enable the lightweight J2EE Single Sign-On implementation by specifying a `true` setting for the system property `oracle.application.sso.``appname` when you start OC4J, where `appname` is the name of your J2EE application. For example, for the application `petstore`:

    java ... -Doracle.application.sso.petstore=true ... -jar oc4j.jar