5 Authorization in OC4J

Specifying a Java 2 Security Manager and Policy File

For Java 2 (code-based) security policies to be enforced by OC4J and the underlying JDK, a security manager (java.lang.SecurityManager instance) must be enabled. This may affect, for example, access to class loaders, access to JDK resources, execution of JDK APIs, or execution of JAAS APIs (such as the ability for the Subject.doAs() or Subject.doAsPrivileged() method to be executed). With a security manager enabled, the policies specified in the Java 2 policy file determine the resources that executing code can access.

You can specify a security manager in either of the following ways:

• Call the static setSecurityManager(SecurityManager) method of the java.lang.System class to specify any desired security manager.

• Use the system property java.security.manager when starting OC4J, either with no setting to use the default security manager, or with a setting that indicates a desired security manager.

The following example starts OC4J with the default security manager:

% java -Djava.security.manager ... -jar oc4j.jar

The following example specifies a security manager:

% java -Djava.security.manager=com.abc.MySecurityManager ... -jar oc4j.jar

The permissions granted to particular classes by the default security manager are determined by reading a policy file. The default policy file is supplied as part of the J2SE. You can specify any desired policy file by setting the system property java.security.policy to the full path of the desired file. The following example starts OC4J with the default security manager and the policy file that is supplied with OC4J:

% java -Doracle.home=$ORACLE_HOME -Djava.security.manager \
       -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy \
       -jar oc4j.jar

Using PrintingSecurityManager to Determine Required Java 2 Permissions

To assist you in identifying all the required permissions for an application running on OC4J, Oracle provides a custom security manager, PrintingSecurityManager, that does not throw security exceptions. Instead, it prints a message specifying what exceptions the default security manager would have thrown. PrintingSecurityManager also generates the policy grants that would avoid the security exceptions.

Run PrintingSecurityManager as in the following example, assuming you run OC4J from ORACLE_HOME/j2ee/home:

% java -Xbootclasspath/p:lib/oc4j-psm.jar -Doracle.home=$ORACLE_HOME \
       -Djava.security.manager=oracle.oc4j.security.PrintingSecurityManager \
       -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy \
       -jar oc4j.jar

(-Xbootclasspath puts PrintingSecurityManager into the boot classpath, where it runs with all permissions.)

PrintingSecurityManager generates output that lists the following:

• Which codesources require which permissions

• Policy grants that you can copy and paste into the policy file

By default, these outputs go to System.out, but you can specify output files through the following system properties. The first is for messages about missing permissions; the second is for policy grants:

-Doracle.oc4j.security.manager.printing.file=filenamepath
-Doracle.oc4j.security.manager.printing.generated.grants.file=filenamepath

Creating or Updating a Java 2 Policy File

A Java 2 policy file grants permissions to trusted code or applications, allowing them appropriate access privileges to execute properly in your environment.

A preconfigured Java 2 policy file, java2.policy, is provided in ORACLE_HOME/j2ee/home/config. You can modify this file if desired, or create and specify an alternative policy file. Be aware, however, that the java2.policy file supplied by Oracle includes permissions that are required for OC4J to run with a security manager. If you use a different policy file, make sure the same permissions are included in that file.

The following policy file sample grants all permissions, such as opening system files and opening sockets or ports, to the trusted jazn.jar (the OracleAS JAAS Provider Admintool):

/* grant the JAAS library AllPermission */ 
grant codebase "file:${oracle.home}/j2ee/home/jazn.jar" { 
    permission java.security.AllPermission; 
}; 

Similarly, the following example grants all permissions to wssecurity.jar (for Web services security functions):

/* grant the WSSecurity AllPermission */ 
grant codebase "file:${oracle.home}/webservices/lib/wssecurity.jar" { 
    permission java.security.AllPermission; 
}; 

The following example grants specific permissions to all applications running in the ORACLE_HOME/appdemo directory:

/* Assuming you are running your application demo in $ORACLE_HOME/appdemo/, */ 
/* Grant JAAS permissions to the demo to run JAAS APIs*/ 
grant codebase "file:/${oracle.home}/appdemo/-" {  
   permission oracle.security.jazn.JAZNPermission "getPolicy"; 
   permission oracle.security.jazn.JAZNPermission "getRealmManager"; 
   permission oracle.security.jazn.policy.AdminPermission;
}

You can grant additional permissions for your application code or for classes generated by OC4J, as necessary, by manually creating additional entries in the .policy file. (There is currently no tool for this.) The required permissions will depend on the details of your application, and the required codebase will depend on the details of your installation.

JAAS Authorization and OracleAS JAAS Provider 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 builds upon the J2SE standard, using standard APIs to support the following features related to fine-grained authorization:

• JAAS mode, which is related to standard Subject.doAs() and Subject.doAsPrivileged() functionality for either Web applications or EJBs

• OracleAS JAAS Provider realm and policy API features

• Features for granting permissions

• Features for checking permissions

Setting a Subject Into the OC4J Container

JAAS based authentication is not well integrated with Java EE. Typically JAAS authentication requires the use of a login module. However, a login module (including custom login modules) do not assert the Subject into the container. This behavior causes applications to not use the authenticating subject. To solve this problem OC4J provides an API that allows a Subject to be asserted into the OC4J container that can be used in place of container managed security (declarative security).The API is located in the oracle.oc4j.security package and is used as follows:

Security.setSubject(Subject subject, Longevity longevity);

The setSubject method asserts the Subject identity into the container for this request and all further requests associated with the Web container if applicable. If the current application context does not have a Web component, then only the current application server thread context will make use of the Subject and upon returning to the pool it will be cleared. This API is only relevant for server-side execution and not for application client-side code.

• subject – the identity to assert into the container

• longevity – the duration for which the identity assertion should be held. This can be Longevity.REQUEST or Longevity.SESSION.

Implementation of Java Authorization Contract for Containers

OC4J 10.1.3.x implementations support the Java Authorization Contract for Containers (JACC), 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 JACC provider.

Note that as a result of the JACC contract, J2EE security constraints are translated into Java 2 permissions, so that the J2EE security model fully leverages the J2SE security model. Yet JACC still fully preserves the existing J2EE declarative security model as well as the J2EE security API. Essentially, you can enable JACC to use an extended version of J2EE authorization, using the same configuration and code for authorization in your application.

JACC is typically invisible to a developer; it is more of a deployment-time consideration.

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

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

• Defining roles 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

Granting Permissions through the OracleAS JAAS Provider Admintool

With either system-jazn-data.xml or Oracle Internet Directory as the policy repository, you can use the OracleAS JAAS Provider Admintool to grant, revoke, or list permissions—using the grantperm, revokeperm, or listperm command, respectively. (An alternative, for runtime, is to use APIs discussed in the next section, "Using OracleAS JAAS Provider Policy Management APIs".) Complete syntax for these commands is documented in "Granting and Revoking Permissions" and "Listing Permissions".

You can grant permissions to a user (through the grantperm -user option), to a role (through the -role option), or to a principal.

For example, to grant RMI permission "login" to the role developers in the realm myrealm:

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

(RMI permission "login" is a permission you must often grant to allow EJB/RMI access.)

To grant this same permission to the user JDOE_ENDUSER:

% java -jar jazn.jar -grantperm myrealm -user JDOE_ENDUSER \
     com.evermind.server.rmi.RMIPermission login

To grant this permission to the LDAP principal hobbes (when using an external LDAP provider):

% java -jar jazn.jar -grantperm oracle.security.jazn.realm.LDAPPrincipal hobbes \
       com.evermind.server.rmi.RMIPermission login 

To grant FilePermission for a file sample.txt for actions "read, write" to user martha in realm foo:

% java -jar jazn.jar -grantperm foo -user martha java.io.FilePermission
     sample.txt read,write

Resulting configuration from the grantperm command is discussed in "OracleAS JAAS Provider Policy Configuration".

Using OracleAS JAAS Provider Policy Management APIs

With either system-jazn-data.xml or Oracle Internet Directory as the policy repository, you can use OracleAS JAAS Provider policy management APIs to grant or revoke permissions. (An alternative, for nonruntime, is to use OracleAS JAAS Provider Admintool commands discussed in the preceding section, "Granting Permissions through the OracleAS JAAS Provider Admintool".) In this example, the doGet() method shown in "Using J2EE Authorization APIs" 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.isUserInRole('ar_developers') = " +
                request.isUserInRole("ar_developers") + "<br>");
   try { 
   //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 developer 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);
      }
   } catch (Exception e) { /* print stack trace */ }
 
   out.println("</BODY>");
   out.println("</HTML>");
}

OracleAS JAAS Provider Policy Configuration

This section documents subject-based policy configuration that results from granting permissions when you use the OracleAS JAAS Provider Admintool or policy management APIs, as discussed in preceding sections. In OC4J, this configuration can be located in either the system-jazn-data.xml file or in Oracle Internet Directory, depending on the security provider.

The following topics are covered:

• Policy Repository Setting in jazn.xml

• Policy Configuration in system-jazn-data.xml

• Policy Configuration in Oracle Internet Directory

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

<jazn-data>
   ...
   <jazn-policy>
     <grant>
       <grantee>
         <principals>
           <principal>
             <realm-name>myrealm</realm-name>
             <type>role</type>
             <class>oracle.security.jazn.XMLRealmRole</class>
             <name>developers</name>
           </principal>
         </principals>
       </grantee>
       <permissions>
         <permission>
           <class>com.evermind.server.rmi.RMIPermission</class>
           <name>login</name>
         </permission>
       </permissions>
     </grant>
     ...
   </jazn-policy>
   ...
</jazn-data>

Specification of the Oracle Policy Provider

If you use the Java virtual machine shipped with Oracle Application Server, the JAAS policy provider supplied with OracleAS JAAS Provider is automatically specified as the policy provider to use in OC4J. If you use another JVM (in other words, if you run an application outside OC4J), then the Oracle JAAS policy provider, oracle.security.jazn.spi.PolicyProvider, must be explicitly specified as the policy provider. (By default, a non-Oracle JVM uses the Sun Microsystems JAAS provider.)

You can specify Oracle-specific JAAS properties, such as the policy provider, in a security properties file that you supply to the JVM when you run OC4J. Oracle offers a default security properties file, ORACLE_HOME/j2ee/home/config/jazn.security.props, that specifies oracle.security.jazn.spi.PolicyProvider as the policy provider to use in OC4J, with the following configuration:

auth.policy.provider=oracle.security.jazn.spi.PolicyProvider

To append default Oracle-specific security property settings, including the above specification of the Oracle JAAS policy provider, to existing security properties, set the java.security.properties system property as follows:

-Djava.security.properties=ORACLE_HOME/j2ee/home/config/jazn.security.props

To replace all security properties with the Oracle properties (note the two equals signs, "=="):

-Djava.security.properties==ORACLE_HOME/j2ee/home/config/jazn.security.props

Using J2EE Authorization APIs

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.isUserInRole('ar_developers') = " +
                 request.isUserInRole("ar_developers") + "<br>");
    out.println("</BODY>");
    out.println("</HTML>");
}

Obtaining a Subject

To perform authorization in your code, you will often have to obtain a Subject instance for the authenticated user who is attempting to access resources. You can accomplish this through standard JAAS functionality, using the static Subject.getSubject() method and specifying an access control context.

Typically, use the default access control context:

mysubject = Subject.getSubject(AccessController.getContext());

Alternatively, you can specify a particular access control context (such as one you have constructed from a set of protection domains, for example):

mysubject = Subject.getSubject(acc);

Note that when you use JAAS mode, OC4J associates an authenticated subject and its permissions with the default access control context and its permissions.

Using the checkPermission() Method

You will typically use a checkPermission(Permission) call in your authorization code, which checks whether the access request indicated by the specified permission should be allowed, based on the security policy currently in effect, and throws an exception if not.

This method is available in the AccessController and AccessControlContext classes. Assuming you use the default implementations (provided with the Sun JDK), the checkPermission() method of either class can enforce Java 2 (code-based) policy in your application regardless of whether a security manager is enabled.

When you use a security manager, the method is also available in the SecurityManager class, but the default SecurityManager implementation of checkPermission() calls AccessController.checkPermission().

You will typically use the AccessController.checkPermission() method, which is static. This call uses the default access control context (the context inherited when the thread was created). If you want the permissions check to be with respect to some other context, however, you can call the instance method checkPermission() on a particular AccessControlContext instance. The following example uses the AccessController method:

//create permission
      FilePermission perm = new FilePermission("/home/developer/foo.txt","read");
      //check permission
      AccessController.checkPermission(perm);

In OC4J, any JAAS mode setting is relevant with respect to what the access control context consists of when AccessController.checkPermission() is called, as follows:

• With no JAAS mode (jaas-mode="null"), checkPermission() enforces code-based security based on the security policy in effect, as presumably specified in a Java 2 policy file. There is no provision for subject-based security.

• With doAs JAAS mode (jaas-mode="doas"), checkPermission() enforces a combination of code-based and subject-based security according to the new access control context created through the doAs() block within which OC4J executes your application code. OC4J appends the permissions of the subject to the permissions of the default access control context.

• With doAsPrivileged JAAS mode (jaas-mode="doasprivileged"), checkPermission() has the same functionality as in doAs mode, but OC4J uses a null access control context, as specified when OC4J calls doAsPrivileged(). This is to use subject-based security only.

Configuring and Using JAAS Mode

In this example, the doGet() method shown in "Using J2EE Authorization APIs" 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:

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

The code follows, using two different ways to check permissions, for demonstration purposes. 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.isUserInRole('ar_developers') = " +
                    request.isUserInRole("ar_developers") + "<br>");
 
      //create Permission
      FilePermission perm = new FilePermission("/home/developer/foo.txt","read");
      {
         // CHECK PERMISSION VIA ACCESS CONTROLLER
         AccessController.checkPermission(perm);

         // CHECK PERMISSION VIA JAAS POLICY
         //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.implies permission: "+ perm +" ? " +
         currPolicy.getPermissions(Subject.getSubject(acc),null).implies(perm));
      }
      out.println("</BODY>");
      out.println("</HTML>");
   }

Enabling the Java Authorization Contract for Containers

This section describes how to enable the Oracle JACC provider in OC4J. With JACC, J2EE security constraints are translated into Java 2 permissions to effectively provide an extended version of J2EE authorization, using the same configuration and code for authorization in your application.

The following topics are covered:

• System Property to Enable JACC Features

• System Properties to Specify the JACC Provider

-Doracle.oc4j.security.jacc=true

Considering J2EE Security

J2EE (static role-based) security is a coarse-grained model that specifies what security roles can access a Web application or EJB.

When Should You Use It?

In a J2EE application, this is the simplest and most basic form of security. Almost any J2EE application will use it, and it will often be enough to suit your needs. It is standard and therefore platform-independent.

Because of its limitations, however, it is sometimes used in conjunction with the other security models. Note that with J2EE security alone, you cannot control access to particular resources or define particular permissions for a role. You also cannot control access by particular code entities. In addition, the J2EE security model is a static model; policies cannot be changed at runtime.

How Do You Set It Up?

Set up J2EE security through standard specifications for security roles, role-linking, and security constraints through the web.xml and ejb-jar.xml files, in addition to specifications for role-mapping through the OC4J-specific descriptors such as orion-application.xml.

If you use only J2EE security, JAAS mode is unnecessary (jaas-mode="null").

How Is It Enforced?

J2EE security is enforced by the J2EE container (OC4J).

Considering Java 2 Security

Java 2 (code-based) security controls access to resources based on the location of executing code or on code signers.

When Should You Use It?

Use Java 2 security when your application must check code-based permissions, perhaps regardless of the user or role trying to access it. With Java 2 security, an administrator can enable or disable a security manager to control when the security manager performs security checks.

Generally, code-based security and the use of a security manager is required only if a situation may arise where the application server is exposed to untrusted code. Also be aware that there may be a performance impact with the use of a security manager.

Java 2 security may be used in conjunction with either J2EE security, JAAS security, or both.

How Do You Set It Up?

Specify Java 2 policies through a standard .policy file, typically named java.policy or java2.policy. The policy file ORACLE_HOME/j2ee/home/config/java2.policy is supplied with OC4J and includes permissions that are required for OC4J to run with a security manager.

Oracle provides no tools to maintain Java 2 policy files; you must do so manually or use tools provided by the JDK vendor or a third-party vendor.

If you use Java 2 security alone or with J2EE security only, JAAS mode is unnecessary (jaas-mode="null").

How Is It Enforced?

For Java 2 security policies to be enforced by an application server and the underlying JDK, a security manager must be enabled.

For Java 2 security policies to be enforced within your application:

• If you want the capability of code-based security in your application, but with an administrator being able to control when the security checks are performed, you can choose to enforce code-based security only when a security manager is enabled. In this case, you can use the checkPermission() method of the SecurityManager instance.

  Be aware that for this scenario, the JVM must be started with a security manager enabled.

• If code-based security requirements in your application are independent of a security manager, you can choose to enforce code-based security within your application regardless of the presence of a security manager. In this case, you can use the static AccessController.checkPermission() method to check permissions.

  In this scenario, it is important to note that the overall environment will not be secure without a security manager. Other code in the environment, including JDK classes, will not be running in a secure mode.

• To specify the particular protection domains to be checked, you can construct an AccessControlContext instance from an array of ProtectionDomain instances, and call the checkPermission() method on the AccessControlContext instance. (This is not a common usage scenario, however.)

Considering JAAS Security

JAAS (subject-based) security is a relatively fine-grained model that controls access to resources according to the particular permissions of the authenticated subject.

When Should You Use It?

Usually, the coarser-grained security of the J2EE model will suffice. JAAS security is more complicated to administer and deploy; however, JAAS security is valuable if you want finer control over resources, such as:

• According to factors other than whether the resource is accessed as part of the execution of a Web module or EJB

• According to individual permissions that can be granted or revoked either by an administrator beforehand or in your code at runtime

J2EE security, by contrast, is more static—access control cannot be modified at runtime.

JAAS security is typically used together with J2EE security, and may also be used together with Java 2 security.

How Do You Set It Up?

You can grant (or revoke) permissions either beforehand, using the OracleAS JAAS Provider Admintool (as shown in "Granting Permissions through the OracleAS JAAS Provider Admintool") or at runtime through OracleAS JAAS Provider APIs (as shown in "Using OracleAS JAAS Provider Policy Management APIs"). The resulting JAAS (subject-based) policy is reflected in system-jazn-data.xml, or Oracle Internet Directory if you use Oracle Identity Management as the security provider.

How you set the JAAS mode is also relevant. To use JAAS authorization without Java 2 (code-based) authorization, use the doAsPrivileged JAAS mode by setting jaas-mode="doasprivileged", and check permissions by using the Policy.implies() method.

To use JAAS authorization together with Java 2 authorization:

• Use the doAs JAAS mode by setting jaas-mode="doas".

• Specify Java 2 policies through a standard .policy file, typically the java2.policy file supplied by Oracle.

How Is It Enforced?

You can enforce JAAS security through the AccessController.checkPermission() method or Policy.implies() method.

If you are also using Java 2 security and have a security manager enabled, you can alternatively use the SecurityManager.checkPermission() method.

(Also refer to earlier discussion regarding enforcement of Java 2 policy.)