Skip Headers

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

Previous | Next |

# 2 Overview of OC4J Security

This chapter introduces the Oracle Containers for J2EE (OC4J) security implementation. This implementation allows developers to integrate authentication, authorization, and delegation services with their applications.

The key component of this implementation is the Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider, which supports the JAAS specification.

This chapter introduces OC4J security, including the OracleAS JAAS Provider, and related key topics:

- Introducing the OracleAS JAAS Provider and Security Providers

- Authentication in the OC4J Environment

- Authorization in the OC4J Environment

- Overview of Security Role Mapping

- See Also: For Oracle Application Server general security information and infrastructure, the 10.1.2 version of the Oracle Application Server Security Guide, a document that is not part of the 10.1.3 documentation set but is available at the following location:
      http://www.oracle.com/technology/documentation/appserver1012.html

## Introducing the OracleAS JAAS Provider and Security Providers

The JAAS framework and the Java 2 Security model form the foundation of JAAS, which Oracle supports through the Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider. The OracleAS JAAS Provider is easily integrated with J2SE and J2EE applications that use the Java 2 Security model, and implements user authentication, authorization, and delegation services that developers can integrate into their application environments. Instead of devoting resources to developing these services, application developers can focus on the presentation and business logic of their applications.

In addition to the OracleAS JAAS Provider, the other key aspect of the security framework for OC4J applications is support for several particular security providers: file-based, LDAP directory-based, external LDAP directory, and custom.

The rest of this section covers the following topics:

- Overview of the OracleAS JAAS Provider

- Summary of JAAS Framework Features

- Supported Security Providers

- Support for DataSourceUserManager

### Overview of the OracleAS JAAS Provider

The OracleAS JAAS Provider implements the JAAS Login Configuration Provider interface and the JAAS Policy Provider interface:

- The Login Configuration Provider implementation is involved in retrieving login module configuration information and ensuring that the appropriate login module is invoked for authentication. An XML file is used to store JAAS login module configurations.

- The Policy Provider implementation supports either of two repositories to store policies for authorization: an XML file or directory service. (This is as opposed to the Sun Microsystems Policy Provider implementation, for example, which uses the file `java2.security` as a policy repository.) Policies contain the rules, referred to as the permissions or privileges, that authorize a user to access and use resources, such as reading from or writing to a file.

Using OracleAS JAAS Provider, applications can enforce fine-grained access control upon resource users. The three key steps when a security-aware application is running in OC4J are the following:

1. Set up and invoke the login module, which involves the OracleAS JAAS Provider.

2. Authenticate the user attempting to log in, which is the role of the security provider.

3. Authorize the user by checking permissions for whatever the user is attempting to accomplish, which involves the OracleAS JAAS Provider.

By default, OracleAS JAAS Provider is configured as part of the OC4J product.

Note: In earlier releases, the term "JAZN" was used to refer to the OracleAS JAAS Provider. This term is no longer used in general, but still appears in code (such as class and package names) and the Admintool shell prompt.

### Summary of JAAS Framework Features

Table 2-1 summarizes JAAS framework features implemented by the OracleAS JAAS Provider.

Table 2-1 JAAS Framework Features

Feature | Description | See Also
--- | --- | ---
Authentication | Integrates with OracleAS Single Sign-On for login authentication in J2EE application environments. Supplies an out-of-the-box `RealmLoginModule` class for non-SSO environments, such as OracleAS Core or Java Edition. Supports any JAAS-compliant custom login module. | "Authentication in the OC4J Environment"
Declarative model | Integrates J2EE deployment descriptors, such as. `web.xml`, with JAAS security. |
Authorization | Supports the J2EE authorization model. Supports the JAAS authorization model. Supports the Java Authorization Contract for Containers | "Authorization in the OC4J Environment"
Realm management | The package `oracle.security.jazn.realm` is provided to support user and role management. |
Policy management | The package `oracle.security.jazn.policy` is provided for administration of authorization policy. |
Administration | Supports administration and configuration using Oracle Enterprise Manager 10g or a command-line tool (the OracleAS JAAS Provider Admintool). | "Tools for Oracle Application Server and OracleAS JAAS Provider"
`JAZNUserManager` | Supplies a security provider implementation that integrates with the file-based provider, Oracle Identity Management, and COREid Access. This class is in the `oracle.security.jazn.oc4j` package. |

### Supported Security Providers

Oracle Application Server supports the following security providers. Each security provider is associated with an appropriate login module (`RealmLoginModule` for the file-based and LDAP-based providers), which is effectively part of the security provider. In addition, each security provider uses a repository for secure and centralized storage, retrieval, and administration of data that consists of realm information (users and roles) and JAAS policy information (permissions).

- File-based (X ML-based) provider

  The file-based provider, discussed in Chapter 7, "File-Based Security Provider", is a fast, lightweight JAAS login module implementation that uses an XML repository. User, role, and policy information is typically stored in the OC4J instance-level file `system-jazn-data.xml`.

  This is the default security provider.

- LD AP-based provider: Oracle Identity Management

  This is the security provider if you want to use the Oracle Internet Directory (OID) as your user repository, with or without Oracle Application Server Single Sign-On, as described in Chapter 6, "Oracle Identity Management Security Provider". The Oracle Identity Management provider stores user, role, realm, and policy information in Oracle Internet Directory, which is based on the Lightweight Directory Access Protocol (LDAP) for centralized storage of information.

  This security provider, intended for production environments, is scalable, secure, enterprise-ready, and integrated with OracleAS Single Sign-On.

  OC4J must be associated with an Oracle Internet Directory instance in order to use Oracle Identity Management.

- Exter nal LDAP providers

  Oracle Application Server supports external (third-party) LDAP providers such as Sun Java System Directory Server or Microsoft Active Directory, as described in Chapter 9, "External LDAP Security Providers". The external LDAP provider implements a custom login module, `LDAPLoginModule`.

- Custom security providers

  Oracle Application Server allows you or a third party to implement a custom security provider using custom login modules to implement special authentication functionality for an application, as described in Chapter 8, "Login Modules". A custom login module implements the standard JAAS login module interface. You can configure custom login modules when you deploy an application through Oracle Enterprise Manager 10g. The configuration is stored in the OC4J `system-jazn-data.xml` file.

  Support for custom login modules is implemented through an extension of the file-based provider.

- COREid Access

  Beginning with the OC4J 10.1.3 implementation, an additional choice for security provider is COREid Access, part of Oracle COREid Access and Identity, as described in Chapter 10, "COREid Access Security Provider". This is an enterprise-class authentication, authorization, and auditing solution that provides centralized security administration. This includes functionality for access control, single sign-on (separate from OracleAS Single Sign-On), personalization, and user profile management in heterogeneous application environments across a variety of application servers, legacy applications, and databases. Use `CoreIDLoginModule` with this security provider.

Note: Note the following terminology in this document: The terms "file-based provider" and "XML-based provider" (sometimes referred to as "JAZN-XML") are equivalent. In the context of Oracle Application Server, the term "LDAP-based provider" (also sometimes "JAZN-LDAP") refers to Oracle Identity Management and its repository, the Oracle Internet Directory. In the OC4J 10.1.3 implementation, the term "custom security provider" is essentially synonymous with "custom login module".

Figure 2-1 shows how the supported security providers interact with the overall security provider framework.

Figure 2-1 OC4J Security Architecture

Description of "Figure 2-1 OC4J Security Architecture"

### Support for DataSourceUserManager

As an alternative to using security providers introduced in the preceding section, the OC4J 10.1.3 implementation continues to support the `DataSourceUserManager` class, for retrieving and managing user data from a database. The database must be specified as a data source, for which you provide a JNDI location in your configuration. The configuration also specifies the relevant database tables and fields.

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 by a JAAS-based login module.

See Also: "Tasks for DataSourceUserManager" for information about `DataSourceUserManager` methods, initialization parameters, and configuration

## Authentication in the OC4J 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. User authentication in the OC4J environment is performed by one of the following:

- OracleAS Single Sign-On

- COREid Access (optionally including single sign-on)

- OracleAS JAAS Provider `RealmLoginModule` login module or desired custom login module (for non-SSO environments)

Before HTTP requests can be dispatched to the target servlet, the OracleAS JAAS Provider `JAZNUserManager` (or, alternatively, a developer-supplied `UserManager` implementation), which coordinates authentication, gets the authenticated user information (set by `mod_osso` for SSO, for example) from the HTTP request object, and sets the JAAS subject in OC4J.

Important: Developer-supplied `UserManager` classes are deprecated in the OC4J 10.1.3 implementation and will be desupported in a future release. Use custom login modules instead.

Several different methods of authentication can be used for a J2EE Web application. The following are standard:

- Basic

  With basic authentication, the user is prompted directly for a user name and password, without going through OracleAS Single Sign-On. A login module (such as `RealmLoginModule`, for example) is used to generate a login dialog.

- Digest

  With the digest authentication mechanism, the password that a client presents to authenticate itself is encrypted through the use of an MD5 digest. This is transmitted in the request message. From a user perspective, digest authentication behaves in the same way as basic authentication. (The digest method is not supported for an external LDAP provider or custom provider.)

- Form

  When the user attempts to access a protected resource through form-based authentication, OC4J displays an application-specific login screen, prompting for user name and password. (The form method is not supported for a custom provider.)

- Client-cert

  This method authenticates the client through HTTPS. The user must possess a public key certificate.

The following are Oracle-specific:

- SSO

  For this authentication method, OracleAS Single Sign-On is used to authenticate users.

- COREIDSSO

  For this authentication method, COREid single sign-on (distinct from OracleAS Single Sign-On) is used to authenticate users.

Note: For either the file-based provider or Oracle Identity Management, we recommend digest authentication as a more secure solution than basic authentication.

See Also: "Specifying the Authentication Method (auth-method)"

## Authorization in the OC4J Environment

There are three main aspects of authorization in OC4J:

- J2EE authorization

- OracleAS JAAS Provider authorization and "JAAS mode"

- Java Authorization Contract for Containers (an enhancement of the J2EE authorization model)

See Also: "JAAS Security Model Versus J2EE Security Model" for an overview of fine-grained versus coarse-grained authorization

### J2EE Authorization

There are standard J2EE implementations that allow servlets and EJBs to retrieve information about a user or caller. You can use these methods in determining if a user or caller should be allowed to access a resource.

A Web application can use the following methods in a `javax.servlet.http.HttpServletRequest` instance:

- `User getUserPrincipal()`

  Returns a principal object containing the name of the authenticated user making the request. The OC4J implementation returns an instance of `oracle.j2ee.security.User`, which extends the standard `java.security.Principal`.

- `String getRemoteUser()`

  Returns the login name of the authenticated user making the request (or `null` if the user is not authenticated).

- `boolean isUserInRole(String rolename)`

  Determines whether the authenticated user making the request is a member of the specified role.

An EJB application can use the following methods in a `javax.ejb.EJBContext` instance:

- `Principal getCallerPrincipal()`

  Returns a principal object that identifies the caller. The OC4J implementation returns an instance of `oracle.j2ee.security.User`, which extends the standard `java.security.Principal`.

- `boolean isCallerInRole(String rolename)`

  Determines whether the caller is a member of the specified role.

### JAAS Authorization and JAAS Mode

OracleAS JAAS Provider allows any protected resource to be modeled using Java permissions. The Java permission model (and associated `java.security.Permission` class) is extensible and allows a flexible way to define fine-grained access control.

OracleAS JAAS Provider supports the following features related to fine-grained authorization:

- JAAS mode, which is related to standard `Subject.doAs()` and `Subject.doAsPrivileged()` functionality for either servlets or EJBs

- OracleAS JAAS Provider realm and policy API features

- Features for granting permissions

- Features for checking permissions

- See Also: "Tasks for JAAS Mode and Authorization" for related task-oriented steps and examples For standard JAAS programming reference information:
      http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html
- For detailed JAAS API information, `java.security.*` packages and `javax.security.auth.*` packages:
      http://java.sun.com/j2se/1.4.2/docs/api/
JAAS Provider API Reference for Javadoc for the OracleAS JAAS Provider

#### Introduction to JAAS Mode

The OC4J 10.1.3 implementation provides a fine-grained authorization feature called JAAS mode, which is related to standard functionality of the static methods `doAs()` and `doAsPrivileged()` in the `Subject` class. These methods work as follows:

- `Object doAs(Subject, PrivilegedAction)`

  Performs the specified privileged action (a computation to be performed with privileges enabled) as the specified subject. This method associates the subject with the access control context (`AccessControlContext` instance) of the current thread, appending the subject's permissions to the permission of that access control context. The returned object is what is returned by the `run()` method of the privileged action. There is also a variation that takes `java.security.PrivilegedExceptionAction` instead of `java.security.PrivilegedAction`, for computations that can throw checked exceptions.

- `Object doAsPrivileged(Subject, PrivilegedAction, AccessControlContext)`

  This method has the same functionality as the `doAs()` method, but within the specified access control context instead of using the access control context of the thread, appending the subject's permissions to the permissions of the specified context.

These methods are used in your application according to your JAAS mode setting. Set JAAS mode in the `jaas-mode` attribute of the `<jazn>` element in the `orion-application.xml` file of your application. JAAS mode determines `doAs()` or `doAsPrivileged()` usage as follows:

- With the setting `jaas-mode="doAs"`, application modules are executed under `Subject.doAs()`.

- With the setting `jaas-mode="doAsPrivileged"`, modules are executed under `Subject.doAsPrivileged()`, therefore not being limited by the access-control restrictions of the server.

- With the setting `jaas-mode="null"` (default), modules are executed under neither method.

Because `jaas-mode` is set in the application-level `orion-application.xml` file, it will affect any Web module or EJB in the application.

Note: JAAS mode replaces `runas-mode` and `doasprivileged-mode` settings in the `<jazn-web-app>` element of `orion-application.xml` or `orion-web.xml`. These settings are deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. The setting `jaas-mode="null"` is equivalent to `runas-mode="false"`; `jaas-mode="doas"` is equivalent to `runas-mode="true"` with `doasprivileged-mode="false"`; `jaas-mode="doAsPrivileged"` is equivalent to `runas-mode="true"` with `doasprivileged-mode="true"`.

See Also: "Security Managers and Access Control" for an introduction to access controllers and access control contexts "Tasks for JAAS Mode and Authorization"

#### OracleAS JAAS Provider Realm and Policy Features

This section discusses OracleAS JAAS Provider classes and methods related to JAAS authorization.

An instance of the `oracle.security.jazn.JAZNConfig` class represents a configuration of the `<jazn>` element. This class includes the following methods:

- `JAZNConfig getJAZNConfig()`

  This static method of the `JAZNConfig` class returns a `JAZNConfig` instance.

- `RealmManager getRealmManager()`

  This instance method of the `JAZNConfig` class returns a `RealmManager` instance, which is used to manage realms.

The `oracle.security.jazn.realm.RealmManager` class includes the following instance method:

- `Realm getRealm(String)`

  This method returns a realm object for the specified realm name.

An instance of the `oracle.security.jazn.realm.Realm` class provides access to the store of users and roles for the particular realm. In the `realm` package, user management is defined by the `UserManager` interface and role management is defined by the `RoleManager` interface. The `Realm` class includes the following instance methods:

- `UserManager getUserManager()`

  This method returns a `UserManager` instance, which you can use to manage users in this realm.

- `RoleManager getRoleManager()`

  This method returns a `RoleManager` instance, which you can use to manage roles in this realm.

Use an `oracle.security.jazn.realm.UserManager` instance to manage (add, retrieve, or remove) users in the realm. This interface includes the following method:

- `RealmUser getUser(String)`

  This method returns a user object, for the specified name of a user in the realm.

#### Features for Granting Permissions

The `JAZNConfig` class, mentioned in the preceding section, also has the following method:

- `JAZNPolicy getPolicy()`

  This method returns an `oracle.security.jazn.policy.JAZNPolicy` instance, which represents the repository of authorization policies.

The `JAZNPolicy` interface includes the following methods:

- `void grant(Grantee, Permission)`

  This method grants the specified permission to the specified grantee, taking as input an `oracle.security.jazn.policy.Grantee` instance and a `java.security.Permission` instance.

- `void revoke(Grantee, Permission)`

  This method revokes the specified permission for the specified grantee.

- `boolean hasPermission(Grantee, Permission)`

  This method determines whether the specified grantee has the specified permission.

The `Grantee` constructor takes a `Principal` instance as input:

- `new Grantee(Principal)`

There are various types of permissions that can be constructed, including the following. (These are all standard JDK features.)

- `new Permission(String permname)`

  The `java.security.Permission` constructor takes a string to specify the name of the permission.

- `new BasicPermission(String permname)`

  The `java.security.Permission` constructor takes a string to specify the name of the permission.

- `new FilePermission(String path, String actions)`

  The `java.security.FilePermission` constructor takes one string to specify the path of the file in question, and another string that is a comma-delimited list of permissible actions. Supported actions are "read", "write", "execute", and "delete".

- `new AllPermission()`

  An instance of the `java.security.AllPermission` class is a permission that represents all other permissions. Its constructor takes no parameters.

Notes: While there are standard mechanisms for checking permissions (as described in the next section), JAAS does not provide standard mechanisms for managing users and granting permissions. This is why the classes and methods described in this section are Oracle-specific. You can also grant, list, and revoke permissions using the OracleAS JAAS Provider Admintool, as discussed in Appendix C, "OracleAS JAAS Provider Admintool Reference".

#### Features for Checking Permissions

Access control, such as checking permissions, was introduced in "Security Managers and Access Control". You can retrieve and check permissions using a policy object.

The abstract class `javax.security.auth.Policy` includes the following methods:

- `Policy getPolicy()`

  This static method returns a `Policy` instance.

- `PermissionCollection getPermissions(Subject, CodeSource)`

  This method, given a `javax.security.auth.Subject` instance and a `java.security.CodeSource` instance, returns a `java.security.PermissionCollection` instance that indicates the set of permissions allowed, given the characteristics of the protection domain. The codesource field can be `null`.

The `PermissionCollection` class includes the following method:

- `boolean implies(Permission)`

  This abstract method indicates whether the specified permission is implied by the set of permissions in the permission collection.

Note: The `javax.security.auth.Policy` class is deprecated in JDK 1.4 but fully supported in the OC4J 10.1.3 implementation and still supported by the Sun Microsystems JDK and J2SE. As of this release, the replacement `java.security.Policy` class is not yet supported by OC4J.

See Also: "Security Policies" for an introduction to codesources

### OracleAS JAAS Provider Per mission Classes

Table 2-2 summarizes permission classes supplied by the OracleAS JAAS Provider.

See Also: For information about the classes discussed, the OracleAS JAAS Provider Javadoc: JAAS Provider API Reference.

Table 2-2 OracleAS JAAS Provider Permission Classes

Permission | Part of Package | Description
--- | --- | ---
`AdminPermission` | `oracle.security.jazn.policy` | Represents the right to administer a permission (that is, grant or revoke another user's permission assignment).
`RoleAdminPermission` | `oracle.security.jazn.policy` | The grantee of this permission is granted the right to further grant/revoke the target role.
`JAZNPermission` | `oracle.security.jazn` | For authorization permissions. `JAZNPermission` contains a name (also called a target name), but no actions list; you either have or do not have the named permission.
`RealmPermission` | `oracle.security.jazn`.`realm` | Represents permission actions for a realm (such as `createRealm` and `dropRealm`). `RealmPermission` extends the class `java.security.Permission`, and is used like any regular Java permission. A `RealmPermission` instance associates a realm name (target name) with a list of actions.

### Implementation of Java Authorization Contract for Containers

The OC4J 10.1.3 implementation supports the Java Authorization Contract for Containers (Java ACC), as specified in JSR-115. This is a contract between containers and authorization service providers, allowing authorization to be decoupled from the container. OC4J authorization functionality is delegated to a standard Java ACC provider. The contract defined in JSR-115 interacts with an application server container, deployment tools, and policy provider, and is divided into the following subcontracts:

- Provider configuration subcontract

- Policy configuration subcontract

- Policy decision and enforcement subcontract

Java ACC provides new `java.security.Permission` class implementations that adhere to the J2EE authorization model. Under Java ACC, access decisions by the container are made according to operations on instances of these `Permission` classes. Java ACC defines the ways that policy providers make use of the new permission classes to address requirements of the J2EE authorization model, as follows:

- Roles defined as collections of permissions

- Granting the permissions of a role to a principal

- Determining whether a principal has been granted the permissions of a role

Note that as a result of the Java ACC contract, J2EE security constraints are translated into Java 2 permissions, so that the J2EE security model now fully leverages the J2SE security model. Yet Java ACC still fully preserves the existing J2EE declarative security model as well as the J2EE security API.

- See Also: "Using the Java Authorization Contract for Containers" For general information about Java ACC:
      http://java.sun.com/j2ee/javaacc/

## Overview of Security Role Map ping

Two distinct role types are available to application developers creating secure applications in J2EE environments: J2EE roles and JAAS roles. OC4J allows you to map a J2EE role to a JAAS role, so that a user who is a member of a given J2EE role has access to resources that are accessible from the associated JAAS role.

The basic steps in security roles and mapping are as follows:

1. Specify logical J2EE security roles, through standard J2EE functionality, in deployment descriptors such as `web.xml` and `ejb-jar.xml`. There is nothing OC4J-specific in this step. A role is declared in a `<security-role>` element.

2. As applicable, specify security role references to link roles in your application code to roles declared through `<security-role>` elements. This is accomplished in standard deployment descriptors through `<security-role-ref>` elements. Through this mechanism, you can adjust your definitions of logical security roles without having to change your application code, then simply map logical roles to application roles as desired. There is nothing OC4J-specific in this step.

3. Configure JAAS roles, or use default roles. For the file-based provider, for example, JAAS roles are reflected in the OC4J `system-jazn-data.xml` file, or optionally in an application-specific `jazn-data.xml` file.

4. Map J2EE roles to JAAS roles. You can accomplish this through Application Server Control, and mappings are reflected in `<security-role-mapping>` elements in `orion-application.xml`, `orion-ejb-jar.xml`, or `orion-web.xml`.

See Also: "Mapping J2EE Security Roles to JAAS Roles" "Web Application Security Role Configuration" "Authenticating and Authorizing EJB Applications"