10 Integrating J2EE Applications and Oracle Internet Directory

This chapter is designed to provide a short overview of APIs you can use in J2EE applications to get information about user permissions, groups, and policies from Oracle Internet Directory.

Oracle Application Server Containers for J2EE (OC4J) is a J2EE certified server implementation. OC4J supports the standard J2EE security APIs.

In addition to the standard security APIs, OC4J provides a set of security features collectively known as JAZN. JAZN includes the Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider, the JAZN User Manager, the JAAS Policy Management API, and the Realm API. OC4J is fully integrated with Oracle Application Server Single Sign-On and Oracle Internet Directory. JAZN security APIs provide features not found in standard J2EE security APIs.

The OracleAS JAAS Provider is an implementation of Java Authentication and Authorization Services (JAAS) that stores security policies in either XML files or in Oracle Internet Directory. OC4J applications can use JAAS Policy Management APIs for fine-grained authorization.

This document discusses the following topics:

Standard J2EE Security APIs
OC4J Security APIs
JAAS Policy Management APIs

10.1 Stand ard J2EE Security APIs

The J2EE standard implementation includes security APIs that can be used by Java Servlets and Enterprise JavaBeans (EJBs) to get information about users and roles. These APIs work independently from Oracle Internet Directory. They retrieve information about users who have already been authenticated, regardless of whether the application is integrated with Oracle Identity Management.

The javax.servlet.http package, which is part of the Java Servlet specification, includes the following methods for obtaining information about users:

javax.servlet.http.HttpServletRequest.getUserPrincipal()
javax.servlet.http.HttpServletRequest.isUserInRole()
javax.servlet.http.HttpServletRequest.getRemoteUser()

To learn more about the javax.servlet.http package, see:

http://java.sun.com/products/servlet/2.2/javadoc/index.html

Similarly, the javax.ejb package, which is part of the Enterprise JavaBeans specification, includes the following methods for obtaining information about users:

javax.ejb.EJBContext.getCallerPrincipal()
javax.ejb.EJBContext.isCallerInRole()

To learn more about the javax.ejb package, see:

http://java.sun.com/j2ee/1.4/docs/api/javax/ejb/package-tree.html

10.2 OC 4J Security APIs

JAZN security APIs are based on the package com.evermind.security. This class specifies a user manager to authenticate and authorize users and groups that attempt to access a J2EE application. The default JAZN user manager is JAZNUserManager, which supports LDAP-based providers and is integrated with Oracle Application Server Single Sign-On and Oracle Internet Directory.

To access Oracle Internet Directory information using JAZNUserManager, you must configure JAZN to use the LDAP-based provider, jazn-ldap, as described in the Oracle Application Server Containers for J2EE Security Guide.

JAZN supports the following com.evermind.security.User methods to retrieve user attributes from Oracle Internet Directory:

getDescription() returns a short description of this user or null if no description is present.
getGroups() returns the groups that this user belongs to, if known and supported.
getName() returns the username of this user.
hasPermission() checks whether this user has the named permission.
isMemberOf() checks whether this user is a member of the specified group.

See JAAS Provider API Reference for more information.

Applications that need additional user attributes, such as email address or Oracle Internet Directory-specific attributes, must use the Oracle Internet Directory APIs. These are found in Oracle Internet Directory API Reference and discussed in Chapter 2 and Chapter 4.

JAZN APIs do not support user creation. Use either the Oracle Internet Directory APIs or Oracle Delegated Administration Services to create users.

Sample Code

The sample code that follows shows both standard J2EE and JAZN APIs being used to retrieve user information after authentication has occurred.

package oracle.security.jazn.samples.http;
 
import java.io.IOException;
import java.util.Date;
import java.util.Properties;
import javax.naming.*;
import javax.servlet.*;
import javax.servlet.http.*;
 
 
/**
 * A simple demo that exercises the Servlet security APIs.
 *
 */
public class CallerInfo extends HttpServlet {
 
    public CallerInfo()
    {
                super();
    }
 
    public void init(ServletConfig config)
        throws ServletException
    {
                super.init(config);
    }
 
    public void doGet(HttpServletRequest request, HttpServletResponse
             response)
        throws ServletException, IOException
    {
                ServletOutputStream out = response.getOutputStream();
 
                response.setContentType("text/html");
                out.println("<HTML><BODY bgcolor='#FFFFFF'>");
 
                //Standard J2EE APIs
                out.println("request.getRemoteUser = " +
                             request.getRemoteUser() + "<br>");
                out.println("request.isUserInRole('FOO') = " +
                             request.isUserInRole("FOO") + "<br>");
                out.println("request.isUserInRole('ar_manager') = " +
                             request.isUserInRole("ar_manager") + "<br>");
                out.println("request.isUserInRole('ar_developer') = " +
                             request.isUserInRole("ar_developer") + "<br>");
                out.println("request.getUserPrincipal = " +
                             request.getUserPrincipal() + "<br>");
 
 
 
                //JAZN-LDAP APIs
                //Get the User principal from request
                com.evermind.security.User user =
(com.evermind.security.User)request.getUserPrincipal();
                //getDescription API Test
                try {
                        java.lang.String s = user.getDescription();
                        out.println("<b>getDescription</b> API Result: ["
                                    +s+ "]<br>");
                }catch(Throwable e) {
                        out.println("<b>getDescription</b> API FAILED: " +
                                     e.toString() + "<br>");
                }
 
                //getGroups API Test
                try {
                        java.util.Set s = user.getGroups();
                        out.println("<b>getGroups</b> API Result: [" +s+
                                    "]<br>");
                }catch(Throwable e) {
                        out.println("<b>getGroups</b> API FAILED: " +
                                     e.toString() + "<br>");
                }
 
                //getName API Test
                try {
                        java.lang.String s = user.getName();
                        out.println("<b>getName</b> API Result: [" +s+
                                    "]<br>");
                }catch(Throwable e) {
                        out.println("<b>getName</b> API FAILED: " +
                                     e.toString() + "<br>");
                }
 
                //hasPermission API Test
                try {
                        com.evermind.server.rmi.RMIPermission p = new
                            com.evermind.server.rmi.RMIPermission("login");
                        boolean b = user.hasPermission(p);
                        out.println("<b>hasPermission</b> API Result: [" + b
                                    + "]<br>");
                }catch(Throwable e) {
                        out.println("<b>hasPermission</b> API FAILED: " +
                                    e.toString() + "<br>");
                }
 
                //isMemberOf API Test
                try {
                        java.util.Set s = user.getGroups();
                        java.util.Iterator itr = s.iterator();
                        boolean b = false;
                        if(itr.hasNext())
                        {
                                b =
                    user.isMemberOf((com.evermind.security.Group)itr.next());
                        }
                        out.println("<b>isMemberOf</b> API Result: [" +b+
                                    "]<br>");
                }catch(Throwable e) {
                        out.println("<b>isMemberOf</b> API FAILED: " +
                                    e.toString() + "<br>");
                }
 
 
                out.println("</BODY>");
                out.println("</HTML>");
    }
}

10.3 JAAS Policy Management APIs

OC4J includes a highly scalable Java Authentication and Authorization Service (JAAS) provider, OracleAS JAAS Provider. J2EE applications integrated with Oracle Internet Directory can take advantage of the JAAS provider for enforcing fine-grained access control over protected resources.

OracleAS JAAS Provider supports using Oracle Internet Directory as the JAAS permissions and policies repository. OracleAS JAAS Provider is integrated with Oracle Internet Directory and OracleAS Single Sign-On to enhance application security.

This section includes the following topics

JAAS Policy Management
Retrieving User Policies and Permissions using Standard JAAS APIs

10.3.1 JAAS Policy Management

Permissions may be granted or revoked either by using the JAZN Admintool from the command line or programmatically, by using JAZN APIs.

The Admintool jazn.jar is found in the infrastructure installation under $ORACLE_HOME/j2ee/home. Set the ORACLE_HOME and J2EE_HOME environment variables before using it.

The following command line grants user scott permissions to read the file foo.txt. The realm name scottsRealm is defined in Oracle Internet Directory and the user name scott exists in Oracle Internet Directory:

java -jar jazn.jar -grantperm scottsRealm -user scott java.io.FilePermission foo.txt, read

For more details on using the Admintool for User Management, see Oracle Application Server Containers for J2EE Security Guide Appendix B, "Using the JAZN Admintool".

To programmatically grant users permissions, you can use the JAZN's API as follows:

//get JAZNConfiguration related info
JAZNConfig jc = JAZNConfig.getJAZNConfig();
 
//create a Grantee for "scott"
RealmManager realmmgr = jc.getRealmManager();
Realm realm = realmMgr.getRealm("scottsRealm");
UserManager userMgr = realm.getUserManager();
final RealmUser user = userMgr.getUser("scott");
 
//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);
}

For further details, see the JAAS Provider API Reference and the Oracle Application Server Containers for J2EE Security Guide.

10.3.2 Retrieving User Policies and Permissions using Standard JAAS APIs

Servlets may be run in either doasprivileged or runasmode. This causes them to be run in Subject.doAsPrivileged or Subject.doAs blocks, respectively. When servlets are run in either of these modes, you can check permissions by using either of two standard APIs: Policy APIs or AccessController. To retrieve policies, configure your servlet to use doasprivileged mode. For more information on how to configure doasprivileged or runas mode, see "Configuring J2EE Authorization" in Oracle Application Server Containers for J2EE Security Guide.

The following code snippets show how to check permissions if user scott has permission to read foo.txt.

Checking or Listing Permissions Using javax.security.auth.Policy.

This approach allows you not only to check permissions, but also to list all the permissions granted to a user or group. If you only need to check the permissions granted to the user or group, and not code-based permissions, this approach is faster.

//create Permission
FilePermission perm = new FilePermission("/home/scott/foo.txt","read");
{
javax.security.auth.Policy currPolicy =    
    javax.security.auth.Policy.getPolicy();
// Query policy now
System.out.println("Policy permissions for this subject are " +
    currPolicy.getPermissions(Subject.getSubject(acc),null));
 
//Check Permissions
System.out.println("Policy.impiles permission: "+ perm +" ?  " +
    currPolicy.getPermissions(Subject.getSubject(acc),null).implies(perm));
}

Checking Permissions Using AccessController

Irrespective of whether the Security Manager is turned on or off, this code will check to see whether the subject or user executing this has permissions.

Note:

If this snippet is executed in a servlet configured for runas mode, the code base also might require permission.

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

For information about policy APIs provided by the OracleAS JAAS Provider, please see Oracle Application Server Containers for J2EE Security Guide Appendix A, "OracleAS JAAS Provider and Sample" and Oracle Application Server Containers for J2EE Security Guide Appendix B, "Using the JAZN Admintool"

For information about the Oracle Internet Directory Java APIs, see Oracle Internet Directory API Reference and Chapter 4, "Using the Java API Extensions to JNDI".