The Java EE 5 Tutorial

Chapter 29 Securing Java EE Applications

Java EE applications are made up of components that can be deployed into different containers. These components are used to build multitier enterprise applications. Security services are provided by the component container and can be implemented using declarative or programmatic techniques. Java EE security services provide a robust and easily configured security mechanism for authenticating users and authorizing access to application functions and associated data. Java EE security services are separate from the security mechanisms of the operating system.

The ways to implement Java EE security services are discussed in a general way in Securing Containers. This chapter provides more detail and a few examples that explore these security services as they relate to Java EE components. Java EE security services can be implemented in the following ways:

Some of the material in this chapter assumes that you have already read Chapter 28, Introduction to Security in the Java EE Platform.

This chapter includes the following topics:

Chapter 30, Securing Web Applications discusses security specific to web components such as servlets and JSP pages.

Securing Enterprise Beans

Enterprise beans are the Java EE components that implement Enterprise JavaBeans (EJB) technology. Enterprise beans run in the EJB container, a runtime environment within the Application Server, as shown in Figure 29–1.

Figure 29–1 Java EE Server and Containers

Diagram of Java EE server showing web container and EJB
container

Although transparent to the application developer, the EJB container provides system-level services such as transactions and security to its enterprise beans. These services enable you to quickly build and deploy enterprise beans, which form the core of transactional Java EE applications.

The following sections describe declarative and programmatic security mechanisms that can be used to protect enterprise bean resources. The protected resources include methods of enterprise beans that are called from application clients, web components, or other enterprise beans. This section assumes that you have read Chapter 20, Enterprise Beans and Chapter 21, Getting Started with Enterprise Beans before starting this section.

You can protect enterprise beans by doing the following:

Two example applications demonstrate adding security to enterprise beans. These example applications are discussed in the following sections:

You should also read JSR-220: Enterprise JavaBeans 3.0 for more information on this topic. This document can be downloaded from http://jcp.org/en/jsr/detail?id=220. Chapter 16 of this specification, Security Management, discusses security management for enterprise beans.

Accessing an Enterprise Bean Caller’s Security Context

In general, security management should be enforced by the container in a manner that is transparent to the enterprise beans’ business methods. The security API described in this section should be used only in the less frequent situations in which the enterprise bean business methods need to access the security context information.

The javax.ejb.EJBContext interface provides two methods that allow the bean provider to access security information about the enterprise bean’s caller.

The following code sample illustrates the use of the getCallerPrincipal() method:

@Stateless public class EmployeeServiceBean
         implements EmployeeService{
    @Resource SessionContext ctx;
    @PersistenceContext EntityManager em;

    public void changePhoneNumber(...) {
        ...
        // obtain the caller principal.
        callerPrincipal = ctx.getCallerPrincipal();

        // obtain the caller principal’s name.
        callerKey = callerPrincipal.getName();

        // use callerKey as primary key to find EmployeeRecord
        EmployeeRecord myEmployeeRecord =
            em.findByPrimaryKey(EmployeeRecord.class, callerKey);

        // update phone number
        myEmployeeRecord.setPhoneNumber(...);

        ...
    }
}

In the previous example, the enterprise bean obtains the principal name of the current caller and uses it as the primary key to locate an EmployeeRecord entity. This example assumes that application has been deployed such that the current caller principal contains the primary key used for the identification of employees (for example, employee number).

The following code sample illustrates the use of the isCallerInRole(String roleName) method:

@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll {
     @Resource SessionContext ctx;

     public void updateEmployeeInfo(EmplInfo info) {

         oldInfo = ... read from database;

         // The salary field can be changed only by callers
         // who have the security role "payroll"
         if (info.salary != oldInfo.salary &&
             !ctx.isCallerInRole("payroll")) {
                 throw new SecurityException(...);
         }
         ...
     }
     ...
 }

An example application that uses the getCallerPrincipal and isCallerInRole methods is described in Example: Using the isCallerInRole and getCallerPrincipal Methods.

Declaring Security Role Names Referenced from Enterprise Bean Code

You can declare security role names used in enterprise bean code using either the @DeclareRoles annotation (preferred) or the security-role-ref elements of the deployment descriptor. Declaring security role names in this way enables you to link these security role names used in the code to the security roles defined for an assembled application. In the absence of this linking step, any security role name used in the code will be assumed to correspond to a security role of the same name in the assembled application.

A security role reference, including the name defined by the reference, is scoped to the component whose bean class contains the @DeclareRoles annotation or whose deployment descriptor element contains the security-role-ref deployment descriptor element.

You can also use the security-role-ref elements for those references that were declared in annotations and you want to have linked to a security-role whose name differs from the reference value. If a security role reference is not linked to a security role in this way, the container must map the reference name to the security role of the same name. See Linking Security Role References to Security Roles for a description of how security role references are linked to security roles.

For an example using each of these methods, read the following sections:

Declaring Security Roles Using Annotations

The @DeclareRoles annotation is specified on a bean class, where it serves to declare roles that can be tested by calling isCallerInRole from within the methods of the annotated class.

You declare the security roles referenced in the code using the @DeclareRoles annotation. When declaring the name of a role used as a parameter to the isCallerInRole(String roleName) method, the declared name must be the same as the parameter value. You can optionally provide a description of the named security roles in the description element of the @DeclareRoles annotation.

The following code snippet demonstrates the use of the @DeclareRoles annotation. In this example, the @DeclareRoles annotation indicates that the enterprise bean AardvarkPayroll makes the security check using isCallerInRole("payroll") to verify that the caller is authorized to change salary data. The security role reference is scoped to the session or entity bean whose declaration contains the @DeclareRoles annotation.

@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll {
    @Resource SessionContext ctx;

    public void updateEmployeeInfo(EmplInfo info) {

        oldInfo = ... read from database;

        // The salary field can be changed only by callers
        // who have the security role "payroll"
        if (info.salary != oldInfo.salary &&
            !ctx.isCallerInRole("payroll")) {
                throw new SecurityException(...);
        }
        ...
    }
    ...
}

The syntax for declaring more than one role is as shown in the following example:

@DeclareRoles({"Administrator", "Manager", "Employee"})

Declaring Security Roles Using Deployment Descriptor Elements


Note –

Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.


If the @DeclareRoles annotation is not used, you can use the security-role-ref elements of the deployment descriptor to declare the security roles referenced in the code, as follows:

The following example illustrates how an enterprise bean’s references to security roles are declared in the deployment descriptor. In this example, the deployment descriptor indicates that the enterprise bean AardvarkPayroll makes the security check using isCallerInRole("payroll") in its business method. The security role reference is scoped to the session or entity bean whose declaration contains the security-role-ref element.

...
<enterprise-beans>
    ...
    <session>
        <ejb-name>AardvarkPayroll</ejb-name>
        <ejb-class>com.aardvark.payroll.PayrollBean</ejb-class>
        ...
        <security-role-ref>
            <description>
                This security role should be assigned to the
                employees of the payroll department who are
                allowed to update employees’ salaries.
            </description>
            <role-name>payroll</role-name>
        </security-role-ref>
        ...
    </session>
    ...
</enterprise-beans>
...

Defining a Security View of Enterprise Beans

You can define a security view of the enterprise beans contained in the ejb-jar file and pass this information along to the deployer. When a security view is passed on to the deployer, the deployer uses this information to define method permissions for security roles. If you don’t define a security view, the deployer will have to determine what each business method does to determine which users are authorized to call each method.

A security view consists of a set of security roles, a semantic grouping of permissions that a given type of users of an application must have to successfully access the application. Security roles are meant to be logical roles, representing a type of user. You can define method permissions for each security role. A method permission is a permission to invoke a specified group of methods of the enterprise beans’ business interface, home interface, component interface, and/or web service endpoints. You can specify an authentication mechanism that will be used to verify the identity of a user.

It is important to keep in mind that security roles are used to define the logical security view of an application. They should not be confused with the user groups, users, principals, and other concepts that exist in the Application Server.

The following sections discuss setting up security roles, authentication mechanisms, and method permissions that define a security view:

Defining Security Roles

Use the @DeclareRoles and @RolesAllowed annotations to define security roles using Java language annotations. The set of security roles used by the application is the total of the security roles defined by the security role names used in the @DeclareRoles and @RolesAllowed annotations.

You can augment the set of security roles defined for the application by annotations using the security-role deployment descriptor element to define security roles, where you use the role-name element to define the name of the security role.

The following example illustrates how to define security roles in a deployment descriptor:

    ...
<assembly-descriptor>
    <security-role>
        <description>
            This role includes the employees of the
            enterprise who are allowed to access the
            employee self-service application. This role
            is allowed only to access his/her own
            information.
        </description>
        <role-name>employee</role-name>
    </security-role>

    <security-role>
        <description>
            This role includes the employees of the human
            resources department. The role is allowed to
             view and update all employee records.
        </description>
        <role-name>hr-department</role-name>
    </security-role>

    <security-role>
        <description>
            This role includes the employees of the payroll
            department. The role is allowed to view and
            update the payroll entry for any employee.
        </description>
        <role-name>payroll-department</role-name>
    </security-role>

    <security-role>
        <description>
            This role should be assigned to the personnel
            authorized to perform administrative functions
            for the employee self-service application.
            This role does not have direct access to
            sensitive employee and payroll information.
        </description>
        <role-name>admin</role-name>
    </security-role>
    ...
</assembly-descriptor>

Linking Security Role References to Security Roles

The security role references used in the components of the application are linked to the security roles defined for the application. In the absence of any explicit linking, a security role reference will be linked to a security role having the same name.

You can explicitly link all the security role references declared in the @DeclareRoles annotation or security-role-ref elements for a component to the security roles defined by the use of annotations (as discussed in Defining Security Roles) and/or in the security-role elements.

You use the role-link element to link each security role reference to a security role. The value of the role-link element must be the name of one of the security roles defined in a security-role element, or by the @DeclareRoles or @RolesAllowed annotations (as discussed in Defining Security Roles). You do not need to use the role-link element to link security role references to security roles when the role-name used in the code is the same as the name of the security-role to which you would be linking.

The following example illustrates how to link the security role reference name payroll to the security role named payroll-department:

...
 <enterprise-beans>
     ...
     <session>
         <ejb-name>AardvarkPayroll</ejb-name>
         <ejb-class>com.aardvark.payroll.PayrollBean</ejb-class>
         ...
         <security-role-ref>
             <description>
                 This role should be assigned to the
                 employees of the payroll department.
                 Members of this role have access to
                 anyone’s payroll record.
                 The role has been linked to the
                 payroll-department role.
             </description>
             <role-name>payroll</role-name>
             <role-link>payroll-department</role-link>
         </security-role-ref>
         ...
     </session>
     ...
 </enterprise-beans>
 ...

Specifying an Authentication Mechanism

Authentications mechanisms are specified in the runtime deployment descriptor. When annotations, such as the @RolesAllowed annotation, are used to protect methods in the enterprise bean, you can configure the Interoperable Object Reference (IOR) to enable authentication for an enterprise application. This is accomplished by adding the <login-config>element to the runtime deployment descriptor, sun-ejb-jar.xml.

You can use the USERNAME-PASSWORD authentication method for an enterprise bean. You can use either the BASIC or CLIENT-CERT authentication methods for web service endpoints.

For more information on specifying an authentication mechanism, read Configuring IOR Security or Example: Securing an Enterprise Bean.

Specifying Method Permissions

If you have defined security roles for the enterprise beans in the ejb-jar file, you can also specify the methods of the business interface, home interface, component interface, and/or web service endpoints that each security role is allowed to invoke.

You can use annotations and/or the deployment descriptor for this purpose. Refer to the following sections for more information on specifying method permissions:

Specifying Method Permissions Using Annotations

The method permissions for the methods of a bean class can be specified on the class, the business methods of the class, or both. Method permissions can be specified on a method of the bean class to override the method permissions value specified on the entire bean class. The following annotations are used to specify method permissions:

The following example code illustrates the use of these annotations:

@RolesAllowed("admin")
public class SomeClass {
    public void aMethod () {...}
    public void bMethod () {...}
    ...
}

@Stateless public class MyBean implements A extends SomeClass {

    @RolesAllowed("HR")
    public void aMethod () {...}

    public void cMethod () {...}
    ...
}

In this example, assuming aMethod, bMethod, and cMethod are methods of business interface A, the method permissions values of methods aMethod and bMethod are @RolesAllowed("HR") and @RolesAllowed("admin") respectively. The method permissions for method cMethod have not been specified.

To clarify, the annotations are not inherited by the subclass per se, they apply to methods of the superclass which are inherited by the subclass. Also, annotations do not apply to CMP entity beans.

An example that uses annotations to specify method permissions is described in Example: Securing an Enterprise Bean.

Specifying Method Permissions Using Deployment Descriptors


Note –

Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.


You define the method permissions in the deployment descriptor using the method-permission elements, as discussed below:

Here is some other useful information about setting method permissions using deployment descriptors:

There are three legal styles for composing the method element:

The following example illustrates how security roles are assigned method permissions in the deployment descriptor:

 ...
 <method-permission>
     <role-name>employee</role-name>
     <method>
         <ejb-name>EmployeeService</ejb-name>
         <method-name>*</method-name>
     </method>
 </method-permission>

 <method-permission>
     <role-name>employee</role-name>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>findByPrimaryKey</method-name>
     </method>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>getEmployeeInfo</method-name>
     </method>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>updateEmployeeInfo</method-name>
     </method>
 </method-permission>

 <method-permission>
     <role-name>payroll-department</role-name>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>findByPrimaryKey</method-name>
     </method>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>getEmployeeInfo</method-name>
     </method>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>updateEmployeeInfo</method-name>
     </method>
     <method>
         <ejb-name>AardvarkPayroll</ejb-name>
         <method-name>updateSalary</method-name>
     </method>
 </method-permission>

 <method-permission>
     <role-name>admin</role-name>
     <method>
         <ejb-name>EmployeeServiceAdmin</ejb-name>
         <method-name>*</method-name>
     </method>
 </method-permission>
 ...

Mapping Security Roles to Application Server Groups

The Application Server assigns users to principals or groups, rather than to security roles. When you are developing a Java EE application, you don’t need to know what categories of users have been defined for the realm in which the application will be run. In the Java EE platform, the security architecture provides a mechanism for mapping the roles defined in the application to the users or groups defined in the runtime realm.

To map a role name permitted by the application or module to principals (users) and groups defined on the server, use the security-role-mapping element in the runtime deployment descriptor (sun-application.xml, sun-web.xml, or sun-ejb-jar.xml) file. The entry needs to declare a mapping between a security role used in the application and one or more groups or principals defined for the applicable realm of the Application Server. An example for the sun-application.xml file is shown below:

<sun-application>
    <security-role-mapping>
        <role-name>CEO</role-name>
        <principal-name>jschwartz</principal-name>
    </security-role-mapping>
    <security-role-mapping>
        <role-name>ADMIN</role-name>
        <group-name>directors</group-name>
    </security-role-mapping>
</sun-application>

The role name can be mapped to either a specific principal (user), a group, or both. The principal or group names referenced must be valid principals or groups in the current default realm of the Application Server. The role-name in this example must exactly match the role-name in the security-role element of the corresponding web.xml file or the role name defined in the @DeclareRoles or @RolesAllowed annotations.

    Sometimes the role names used in the application are the same as the group names defined on the Application Server. Under these circumstances, you can enable a default principal-to-role mapping on the Application Server using the Admin Console. To enable the default principal-to-role-mapping, follow these steps:

  1. Start the Application Server, then the Admin Console.

  2. Expand the Configuration node.

  3. Select the Security node.

  4. On the Security page, check the Enabled box beside Default Principal to Role Mapping.

For an enterprise application, you can specify the security role mapping at the application layer, in sun-application.xml, or at the module layer, in sun-ejb-jar.xml. When specified at the application layer, the role mapping applies to all contained modules and overrides same-named role mappings at the module layer. The assembler is responsible for reconciling the module-specific role mappings to yield one effective mapping for the application.

Both example applications demonstrate security role mapping. For more information, see Example: Securing an Enterprise Bean and Example: Using the isCallerInRole and getCallerPrincipal Methods.

Propagating Security Identity

You can specify whether a caller’s security identity should be used for the execution of specified methods of an enterprise bean, or whether a specific run-as identity should be used.

Figure 29–2 illustrates this concept.

Figure 29–2 Security Identity Propagation

Diagram of security identity propagation from client
to intermediate container to target container

In this illustration, an application client is making a call to an enterprise bean method in one EJB container. This enterprise bean method, in turn, makes a call to an enterprise bean method in another container. The security identity during the first call is the identity of the caller. The security identity during the second call can be any of the following options:

Configuring a Component’s Propagated Security Identity

You can configure an enterprise bean’s run-as, or propagated, security identity using either of the following:

Alternately, you can use the use-caller-identity element to indicate that you want to use the identity of the original caller, as shown in the code below:

<security-identity>
    <use-caller-identity />
</security-identity>

You must explicitly specify the run-as role name mapping to a given principal in sun-web.xml or sun-ejb-jar.xml if the given roles associate to more than one user principal.

More detail about the elements contained in deployment descriptors is available in the Sun Java System Application Server 9.1 Application Deployment Guide.

In either case, you will have to map the run-as role name to a given principal defined on the Application Server if the given roles associate to more than one user principal. Mapping roles to principals is described in Mapping Security Roles to Application Server Groups.

Trust between Containers

When an enterprise bean is designed so that either the original caller identity or a designated identity is used to call a target bean, the target bean will receive the propagated identity only; it will not receive any authentication data.

There is no way for the target container to authenticate the propagated security identity. However, because the security identity is used in authorization checks (for example, method permissions or with the isCallerInRole() method), it is vitally important that the security identity be authentic. Because there is no authentication data available to authenticate the propagated identity, the target must trust that the calling container has propagated an authenticated security identity.

By default, the Application Server is configured to trust identities that are propagated from different containers. Therefore, there are no special steps that you need to take to set up a trust relationship.

Using Enterprise Bean Security Annotations

Annotations are used in code to relay information to the deployer about security and other aspects of the application. Specifying this information in annotations or in the deployment descriptor helps the deployer set up the appropriate security policy for the enterprise bean application.

Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.

The following is a listing of annotations that address security, can be used in an enterprise bean, and are discussed in this tutorial:

Using Enterprise Bean Security Deployment Descriptor Elements

Enterprise JavaBeans components use an EJB deployment descriptor that must be named META-INF/ejb-jar.xml and must be contained in the EJB JAR file. The role of the deployment descriptor is to relay information to the deployer about security and other aspects of the application. Specifying this information in annotations or in the deployment descriptor helps the deployer set up the appropriate security policy for the enterprise bean application. More detail about the elements contained in deployment descriptors is available in the Sun Java System Application Server 9.1 Application Deployment Guide.


Note –

Using annotations is the recommended method for adding security to enterprise bean applications.


Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.

The following is a listing of deployment descriptor elements that address security, can be used in an enterprise bean, and are discussed in this tutorial:

The schema for ejb-jar deployment descriptors can be found in section 18.5, Deployment Descriptor XML Schema, in the EJB 3.0 Specification (JSR-220) at http://jcp.org/en/jsr/detail?id=220.

Configuring IOR Security

The EJB interoperability protocol is based on Internet Inter-ORB Protocol (IIOP/GIOP 1.2) and the Common Secure Interoperability version 2 (CSIv2) CORBA Secure Interoperability specification.

Enterprise beans that are deployed in one vendor’s server product are often accessed from Java EE client components that are deployed in another vendor’s product. CSIv2, a CORBA/IIOP-based standard interoperability protocol, addresses this situation by providing authentication, protection of integrity and confidentiality, and principal propagation for invocations on enterprise beans, where the invocations take place over an enterprise’s intranet. CSIv2 configuration settings are specified in the Interoperable Object Reference (IOR) of the target enterprise bean. IOR configurations are defined in Chapter 24 of the CORBA/IIOP specification, Secure Interoperability. This chapter can be downloaded from http://www.omg.org/cgi-bin/doc?formal/02-06-60.

The EJB interoperability protocol is defined in Chapter 14, Support for Distribution and Interoperability, of the EJB specification, which can be downloaded from http://jcp.org/en/jsr/detail?id=220.

Based on application requirements, IORs are configured in vendor-specific XML files, such as sun-ejb-jar.xml, instead of in standard application deployment descriptor files, such as ejb-jar.xml.

For a Java EE application, IOR configurations are specified in Sun-specific xml files, for example, sun-ejb-jar_2_1-1.dtd. The ior-security-config element describes the security configuration information for the IOR. A description of some of the major subelements is provided below.

The following is an example that defines security for an IOR:

<sun-ejb-jar>
    <enterprise-beans>
        <unique-id>1</unique-id>
        <ejb>
            <ejb-name>HelloWorld</ejb-name>
            <jndi-name>HelloWorld</jndi-name>
            <ior-security-config>
                <transport-config>
                    <integrity>NONE</integrity>
                    <confidentiality>NONE</confidentiality>
                    <establish-trust-in-target>
                        NONE
                    </establish-trust-in-target>
                    <establish-trust-in-client>
                        NONE
                    </establish-trust-in-client>
                </transport-config>
                <as-context>
                    <auth-method>USERNAME_PASSWORD</auth-method>
                    <realm>default</realm>
                    <required>true</required>
                </as-context>
                <sas-context>
                    <caller-propagation>NONE</caller-propagation>
                </sas-context>
            </ior-security-config>
            <webservice-endpoint>
                <port-component-name>HelloIF</port-component-name>
                <endpoint-address-uri>
                    service/HelloWorld
                </endpoint-address-uri>
                <login-config>
                    <auth-method>BASIC</auth-method>
                </login-config>
            </webservice-endpoint>
        </ejb>
    </enterprise-beans>
</sun-ejb-jar>

Deploying Secure Enterprise Beans

The deployer is responsible for ensuring that an assembled application is secure after it has been deployed in the target operational environment. If a security view (security annotations and/or a deployment descriptor) has been provided to the deployer, the security view is mapped to the mechanisms and policies used by the security domain in the target operational environment, which in this case is the Application Server. If no security view is provided, the deployer must set up the appropriate security policy for the enterprise bean application.

Deployment information is specific to a web or application server. Please read the Sun Java System Application Server 9.1 Application Deployment Guide for more information on deploying enterprise beans.

Accepting Unauthenticated Users

Web applications accept unauthenticated web clients and allow these clients to make calls to the EJB container. The EJB specification requires a security credential for accessing EJB methods. Typically, the credential will be that of a generic unauthenticated user. The way you specify this credential is implementation-specific.

    In the Application Server, you must specify the name and password that an unauthenticated user will use to log in by modifying the Application Server using the Admin Console:

  1. Start the Application Server, then the Admin Console.

  2. Expand the Configuration node.

  3. Select the Security node.

  4. On the Security page, set the Default Principal and Default Principal Password values.

Accessing Unprotected Enterprise Beans

If the deployer has granted full access to a method, any user or group can invoke the method. Conversely, the deployer can deny access to a method.

    To modify which role can be used in applications to grant authorization to anyone, specify a value for Anonymous Role. To set the Anonymous Role field, follow these steps:

  1. Start the Application Server, then the Admin Console.

  2. Expand the Configuration node.

  3. Select the Security node.

  4. On the Security page, specify the Anonymous Role value.

Enterprise Bean Example Applications

The following example applications demonstrate adding security to enterprise beans applications:

Example: Securing an Enterprise Bean

This section discusses how to configure an enterprise bean for username-password authentication. When a bean that is constrained in this way is requested, the server requests a user name and password from the client and verifies that the user name and password are valid by comparing them against a database of authorized users on the Application Server.

If the topic of authentication is new to you, please refer to the section titled Specifying an Authentication Mechanism.

For this tutorial, you will add the security elements to an enterprise bean; add security elements to the deployment descriptors; build, package, and deploy the application; and then build and run the client application.

The completed version of this example can be found at tut-install/javaeetutorial5/examples/ejb/cart-secure/. This example was developed by starting with the unsecured enterprise bean application, cart, which is found in the directory tut-install/javaeetutorial5/examples/ejb/cart/ and is discussed in The cart Example. You build on this example by adding the necessary elements to secure the application using username-password authentication.

    In general, the following steps are necessary to add username-password authentication to an enterprise bean. In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application.

  1. Create an application like the one in The cart Example. The example in this tutorial starts with this example and demonstrates adding basic authentication of the client to this application. The example application discussed in this section can be found at tut-install/javaeetutorial5/examples/ejb/cart-secure/.

  2. If you have not already done so, complete the steps in Building the Examples to configure your system properly for running the tutorial applications.

  3. If you have not already done so, add a user to the file realm and specify user for the group of this new user. Write down the user name and password so that you can use them for testing this application in a later step. Refer to the section Managing Users and Groups on the Application Server for instructions on completing this step.

  4. Modify the source code for the enterprise bean, CartBean.java, to specify which roles are authorized to access which protected methods. This step is discussed in Annotating the Bean.

  5. Modify the runtime deployment descriptor, sun-ejb-jar.xml, to map the role used in this application (CartUser) to a group defined on the Application Server (user) and to add security elements that specify that username-password authentication is to be performed. This step is discussed in Setting Runtime Properties.

  6. Build, package, and deploy the enterprise bean, then build and run the client application by following the steps in Building, Deploying, and Running the Secure Cart Example Using NetBeans IDE or Building, Deploying, and Running the Secure Cart Example Using Ant.

Annotating the Bean

The source code for the original cart application was modified as shown in the following code snippet (modifications in bold, method details removed to save space). The resulting file can be found in the following location:

tut-install/javaeetutorial5/examples/ejb/cart-secure/cart-secure-ejb/src/java/cart/secure/
ejb/CartBean.java

The code snippet is as follows:

package com.sun.tutorial.javaee.ejb;

import java.util.ArrayList;
import java.util.List;
import javax.ejb.Remove;
import javax.ejb.Stateful;
import javax.annotation.security.RolesAllowed;
@Stateful()
public class CartBean implements Cart {

    String customerName;
    String customerId;
    List<String> contents;

    public void initialize(String person) throws BookException {
         ...
        }

    public void initialize(String person, String id) throws BookException {
         ... }

    @RolesAllowed("CartUser")
    public void addBook(String title) {
        contents.add(title);
    }

    @RolesAllowed("CartUser")
    public void removeBook(String title) throws BookException {
         ... }
    }
    @RolesAllowed("CartUser")
    public List<String> getContents() {
        return contents;
    }

    @Remove()
        public void remove() {
        contents = null;
    }
}

The @RolesAllowed annotation is specified on methods for which you want to restrict access. In this example, only users in the role of CartUser will be allowed to add and remove books from the cart, and to list the contents of the cart. An @RolesAllowed annotation implicitly declares a role that will be referenced in the application; therefore, no @DeclareRoles annotation is required.

Setting Runtime Properties

The role of CartUser has been defined for this application, but there is no group of CartUser defined for the Application Server. To map the role that is defined for the application (CartUser) to a group that is defined on the Application Server (user), add a <security-role-mapping> element to the runtime deployment descriptor, sun-ejb-jar.xml, as shown below. In the original example, there was no need for this deployment descriptor, so it has been added for this example.

To enable username-password authentication for the application, add security elements to the runtime deployment descriptor, sun-ejb-jar.xml. The security element that needs to be added to the deployment descriptor is the <ior-security-config> element. The deployment descriptor is located in tut-install/javaeetutorial5/examples/ejb/cart-secure/cart-secure-ejb/src/conf/sun-ejb-jar.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-ejb-jar PUBLIC 
"-//Sun Microsystems, Inc.//DTD Application Server 9.0 EJB 3.0//EN" 
"http://www.sun.com/software/appserver/dtds/sun-ejb-jar_3_0-0.dtd">
<sun-ejb-jar>
    <security-role-mapping>
        <role-name>CartUser</role-name>
        <group-name>user</group-name>
    </security-role-mapping>
    <enterprise-beans>
        <unique-id>0</unique-id>
        <ejb>
            <ejb-name>CartBean</ejb-name>
            <jndi-name>jacc_mr_CartBean</jndi-name>
            <pass-by-reference>false</pass-by-reference>
            <ior-security-config>
                <transport-config>
                    <integrity>supported</integrity>
                    <confidentiality>supported</confidentiality>
                    <establish-trust-in-target>supported</establish-trust-in-target>
                    <establish-trust-in-client>supported</establish-trust-in-client>
                </transport-config>
                <as-context>
                    <auth-method>username_password</auth-method>
                    <realm>default</realm>
                    <required>true</required>
                </as-context>
                <sas-context>
                    <caller-propagation>supported</caller-propagation>
                </sas-context>
            </ior-security-config>
            <is-read-only-bean>false</is-read-only-bean>
            <refresh-period-in-seconds>-1</refresh-period-in-seconds>
            <gen-classes/>
        </ejb>
    </enterprise-beans>
</sun-ejb-jar>

For more information on this topic, read Specifying an Authentication Mechanism and Configuring IOR Security.

Building, Deploying, and Running the Secure Cart Example Using NetBeans IDE

    Follow these instructions to build, deploy, and run the cart-secure example in your Application Server instance using NetBeans IDE.

  1. In NetBeans IDE, select File->Open Project.

  2. In the Open Project dialog, navigate to tut-install/javaeetutorial5/examples/ejb/.

  3. Select the cart-secure folder.

  4. Select the Open as Main Project and Open Required Projects check boxes.

  5. Click Open Project.

  6. In the Projects tab, right-click the cart-secure project and select Clean and Build.

  7. In the Projects tab, right-click the cart-secure project and select Undeploy and Deploy.

    This step builds and packages the application into cart-secure.ear, located in tut-install/javaeetutorial5/examples/ejb/cart-secure/dist/, and deploys this ear file to your Application Server instance.

  8. To run secure cart’s application client, select Run->Run Main Project. You will be prompted for your username and password.

  9. Enter the username and password of a user that has been entered into the database of users for the file realm and has been assigned to the group of user.

If the username and password you enter are authorized, you will see the output of the application client in the Output pane:


...
Retrieving book title from cart: Infinite Jest
Retrieving book title from cart: Bel Canto
Retrieving book title from cart: Kafka on the Shore
Removing "Gravity’s Rainbow" from cart.
Caught a BookException: "Gravity’s Rainbow" not in cart.
Java Result: 1
run-cart-secure-app-client:

Building, Deploying, and Running the Secure Cart Example Using Ant

    To build, deploy, and run the secure EJB example using the Ant tool, follow these steps:

  1. If you have not already done so, specify properties specific to your installation in the tut-install/javaeetutorial5/examples/bp-project/build.properties file and the tut-install/javaeetutorial5/examples/common/admin-password.txt file. See Building the Examples for information on which properties need to be set in which files.

  2. If you have not already done so, add a user to the file realm and specify user for the group of this new user. Refer to the section Managing Users and Groups on the Application Server for instructions on completing this step.

  3. From a terminal window or command prompt, go to the tut-install/javaeetutorial5/examples/ejb/cart-secure/ directory.

  4. Build, package, and deploy the enterprise application, and build and run the client, by entering the following at the terminal window or command prompt in the ejb/cart-secure/ directory:


    ant all
    

    Note –

    This step assumes that you have the executable for ant in your path; if not, you will need to provide the fully qualified path to the ant executable. This command runs the ant target named all in the build.xml file.


  5. A Login for User dialog displays. Enter a user name and password that correspond to a user set up on the Application Server with a group of user. Click OK.

If the user name and password are authenticated, the client displays the following output:


run:
    [echo] Running appclient for Cart.

appclient-command-common:
    [exec] Infinite Jest
    [exec] Bel Canto
    [exec] Kafka on the Shore
    [exec] Caught a BookException: "Gravity’s Rainbow" not in cart.

If the username and password are not authenticated, the client displays the following error:


run:
    [echo] Running appclient for Cart.

appclient-command-common:
    [exec] Caught an unexpected exception!
    [exec] javax.ejb.EJBException: nested exception is: java.rmi.AccessException:
     CORBA NO_PERMISSION 9998 Maybe; nested exception is:
    [exec]     org.omg.CORBA.NO_PERMISSION:
     ----------BEGIN server-side stack trace----------
    [exec] org.omg.CORBA.NO_PERMISSION:   vmcid: 0x2000  minor code: 1806

If you see this response, verify the user name and password of the user that you entered in the login dialog, make sure that user is assigned to the group user, and rerun the client application.

Example: Using the isCallerInRole and getCallerPrincipal Methods

This example demonstrates how to use the getCallerPrincipal() and isCallerInRole(String role) methods with an enterprise bean. This example starts with a very simple EJB application, converter, and modifies the methods of the ConverterBean so that currency conversion will only occur when the requester is in the role of BeanUser.

For this tutorial, you will add the security elements to an enterprise bean; add the security elements to the deployment descriptor; build, package, and deploy the application; and then build and run the client application. The completed version of this example can be found at tut-install/javaeetutorial5/examples/ejb/converter-secure. This example was developed by starting with the unsecured enterprise bean application, converter, which is discussed in Chapter 21, Getting Started with Enterprise Beans and is found in the directory tut-install/javaeetutorial5/examples/ejb/converter/. This section builds on this example by adding the necessary elements to secure the application using the getCallerPrincipal() and isCallerInRole(String role) methods, which are discussed in more detail in Accessing an Enterprise Bean Caller’s Security Context.

    In general, the following steps are necessary when using the getCallerPrincipal() and isCallerInRole(String role) methods with an enterprise bean. In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application.

  1. Create a simple enterprise bean application, such as the converter example. See Chapter 21, Getting Started with Enterprise Beans for more information on creating and understanding this example. This section of the tutorial starts with this unsecured application and demonstrates how to access an enterprise bean caller’s security context. The completed example application discussed in this section can be found at tut-install/javaeetutorial5/examples/ejb/converter-secure/.

  2. If you have not already done so, follow the steps in Building the Examples to set properties specific to your installation.

  3. If you have not already done so, set up a user on the Application Server in the file realm. Make sure that the user is included in the group named user. For information on adding a user to the file realm, read Managing Users and Groups on the Application Server.

  4. Modify ConverterBean to add the getCallerPrincipal() and isCallerInRole(String role) methods. For this example, callers that are in the role of BeanUser will be able to calculate the currency conversion. Callers not in the role of BeanUser will see a value of zero for the conversion amount. Modifying the ConverterBean code is discussed in Modifying ConverterBean.

  5. Modify the sun-ejb-jar.xml file to specify a secure connection, username-password login, and security role mapping. Modifying the sun-ejb-jar.xml file is discussed in Modifying Runtime Properties for the Secure Converter Example.

  6. Build, package, deploy, and run the application. These steps are discussed in Building, Deploying, and Running the Secure Converter Example Using NetBeans IDE and Building, Deploying, and Running the Secure Converter Example Using Ant.

  7. If necessary, refer to the tips in Troubleshooting the Secure Converter Application for tips on errors you might encounter and some possible solutions.

Modifying ConverterBean

The source code for the original converter application was modified as shown in the following code snippet (modifications in bold) to add the if..else clause that tests if the caller is in the role of BeanUser. If the user is in the correct role, the currency conversion is computed and displayed. If the user is not in the correct role, the computation is not performed, and the application displays the result as 0. The code example can be found in the following file:

tut-install/javaeetutorial5/examples/ejb/converter-secure/converter-secure-ejb/src/java/
converter/secure/ejb/ConverterBean.java

The code snippet is as follows:

package converter.secure.ejb;

import java.math.BigDecimal;
import javax.ejb.*;
import java.security.Principal;
import javax.annotation.Resource;
import javax.ejb.SessionContext;
import javax.annotation.security.DeclareRoles;
import javax.annotation.security.RolesAllowed;
@Stateless()
@DeclareRoles("BeanUser")
public class ConverterBean implements converter.secure.ejb.Converter {
    @Resource SessionContext ctx;
    private BigDecimal yenRate = new BigDecimal("115.3100");
    private BigDecimal euroRate = new BigDecimal("0.0071");

    @RolesAllowed("BeanUser")
     public BigDecimal dollarToYen(BigDecimal dollars) {
        BigDecimal result = new BigDecimal("0.0");
        Principal callerPrincipal = ctx.getCallerPrincipal();
        if (ctx.isCallerInRole("BeanUser")) {
            result = dollars.multiply(yenRate);
            return result.setScale(2, BigDecimal.ROUND_UP);
        }else{
            return result.setScale(2, BigDecimal.ROUND_UP);
        }
        }
    @RolesAllowed("BeanUser")
    public BigDecimal yenToEuro(BigDecimal yen) {
        BigDecimal result = new BigDecimal("0.0");
        Principal callerPrincipal = ctx.getCallerPrincipal();
         if (ctx.isCallerInRole("BeanUser")) {
             result = yen.multiply(euroRate);
             return result.setScale(2, BigDecimal.ROUND_UP);
        }else{
            return result.setScale(2, BigDecimal.ROUND_UP);
        }
    }
}

Modifying Runtime Properties for the Secure Converter Example

Secure connections, username-password login, and the mapping of application roles to Application Server groups and principals are specified in the runtime deployment descriptor file sun-ejb-jar.xml. The original converter application that did not include any security mechanisms did not have a need for this file: it has been added specifically for this application.

To map the role of BeanUser that is defined for this application to the group with the name of user in the file realm of the Application Server, specify the security-role-mapping element as shown below. Make sure that the role-name and group-name elements are specified exactly as they are used (the mapping is case-sensitive).

To specify username-password login and a secure connection, use the ior-security-config element. The IOR security elements are described in more detail in Configuring IOR Security.

The following sun-ejb-jar.xml file demonstrates how to specify a secure connection, username-password login, and security role mapping. The completed version of this file can be found in tut-install/javaeetutorial5/examples/ejb/converter-secure/converter-secure-ejb/src/conf/sun-ejb-jar.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-ejb-jar PUBLIC 
"-//Sun Microsystems, Inc.//DTD Application Server 9.0 EJB 3.0//EN" 
"http://www.sun.com/software/appserver/dtds/sun-ejb-jar_3_0-0.dtd">
<sun-ejb-jar>

    <security-role-mapping>
        <role-name>BeanUser</role-name>
        <group-name>user</group-name>
    </security-role-mapping>

     <enterprise-beans>
        <unique-id>0</unique-id>
        <ejb>
            <ejb-name>ConverterBean</ejb-name>
            <jndi-name>ConverterBean</jndi-name>
            <pass-by-reference>false</pass-by-reference>
            <ior-security-config>
                 <transport-config>
                    <integrity>supported</integrity>
                    <confidentiality>supported</confidentiality>
                    <establish-trust-in-target>
                        supported
                    </establish-trust-in-target>
                     <establish-trust-in-client>
                        supported
                    </establish-trust-in-client>
                     </transport-config>
                 <as-context>
                    <auth-method>username_password</auth-method>
                    <realm>file</realm>
                    <required>true</required>
                </as-context>
                <sas-context>
                    <caller-propagation>
                        supported
                    </caller-propagation>
                </sas-context>
                </ior-security-config>
                <is-read-only-bean>false</is-read-only-bean>
                <refresh-period-in-seconds>
                    -1
                </refresh-period-in-seconds>
                <gen-classes/>
            </ejb>
    </enterprise-beans>
 </sun-ejb-jar

Building, Deploying, and Running the Secure Converter Example Using NetBeans IDE

    Follow these instructions to build, package, and deploy the converter-secure example to your Application Server instance using NetBeans IDE.

  1. In NetBeans IDE, select File->Open Project.

  2. In the Open Project dialog, navigate to tut-install/javaeetutorial5/examples/ejb/.

  3. Select the converter-secure folder.

  4. Select the Open as Main Project and Open Required Projects check boxes.

  5. Click Open Project.

  6. In the Projects tab, right-click the converter-secure project and select Clean and Build.

  7. In the Projects tab, right-click the converter-secure project and select Undeploy and Deploy.

    This step builds and packages the application into converter-secure.ear, located in tut-install/javaeetutorial5/examples/ejb/converter-secure/dist/, and deploys this ear file to your Application Server instance.

  8. To run the secure converter’s application client, select Run->Run Main Project. You will be prompted for your username and password.

  9. Enter the username and password of a user that has been entered into the database of users for the file realm and has been assigned to the group of user.

    If the username and password you enter are authorized, you will see the output of the application client in the Output pane:


    [exec] $100.00 is 11531.00 Yen.
    [exec] 11531.00 Yen is 81.88 Euro.

Building, Deploying, and Running the Secure Converter Example Using Ant

    To build the secure converter enterprise beans and client, package and deploy the enterprise application, and run the client application, follow these steps:

  1. Set up your system for running the tutorial examples if you haven’t done so already by following the instructions in Building the Examples.

  2. From a terminal window or command prompt, go to the tut-install/javaeetutorial5/examples/ejb/converter-secure/ directory.

  3. Build, package, deploy, and run the enterprise application and application client by entering the following at the terminal window or command prompt in the ejb/converter-secure/ directory:


    ant all
    

    Note –

    This step assumes that you have the executable for ant in your path; if not, you will need to provide the fully qualified path to the ant executable. This command runs the ant target named all in the build.xml file.


The running application will look like this:


appclient-command-common:

At this point, a system login dialog will display. Enter the user name and password that correspond to a user in the group user on the Application Server. If the user name and password are authenticated, the following text displays in the terminal window or command prompt:


appclient-command-common:
    [exec] $100.00 is 11531.00 Yen.
    [exec] 11531.00 Yen is 81.88 Euro.

Troubleshooting the Secure Converter Application

Problem: The application displays zero values after authentication, as shown here:


appclient-command-common:
    [exec] $100.00 is 0.00 Yen.
    [exec] 0.00 Yen is 0.00 Euro.

Solution: Verify that the user name and password that you entered for authentication match a user name and password in the Application Server, and that this user is assigned to the group named user. User names and passwords are case-sensitive. Read Adding Users to the Application Server for more information on adding users to the file realm of the Application Server.

Discussion: Securing the Duke’s Bank Example

The Duke’s Bank application is an online banking application. Duke’s Bank has two clients: an application client used by administrators to manage customers and accounts, and a web client used by customers to access account histories and perform transactions. The clients access the customer, account, and transaction information maintained in a database through enterprise beans. The Duke’s Bank application demonstrates the way that many of the component technologies presented in this tutorial (enterprise beans, application clients, and web components) are applied to provide a simple but functional application.

To secure the Duke’s Bank example, the following security mechanisms are used:

Read Chapter 37, The Duke’s Bank Application for more information on securing the Duke’s Bank example.

Securing Application Clients

The Java EE authentication requirements for application clients are the same as for other Java EE components, and the same authentication techniques can be used as for other Java EE application components.

No authentication is necessary when accessing unprotected web resources. When accessing protected web resources, the usual varieties of authentication can be used, namely HTTP basic authentication, SSL client authentication, or HTTP login form authentication. These authentication methods are discussed in Specifying an Authentication Mechanism.

Authentication is required when accessing protected enterprise beans. The authentication mechanisms for enterprise beans are discussed in Securing Enterprise Beans. Lazy authentication can be used.

An application client makes use of an authentication service provided by the application client container for authenticating its users. The container’s service can be integrated with the native platform’s authentication system, so that a single sign-on capability is employed. The container can authenticate the user when the application is started, or it can use lazy authentication, authenticating the user when a protected resource is accessed.

An application client can provide a class to gather authentication data. If so, the javax.security.auth.callback.CallbackHandler interface must be implemented, and the class name must be specified in its deployment descriptor. The application’s callback handler must fully support Callback objects specified in the javax.security.auth.callback package. Gathering authentication data in this way is discussed in the next section, Using Login Modules.

Using Login Modules

An application client can use the Java Authentication and Authorization Service (JAAS) to create login modules for authentication. A JAAS-based application implements the javax.security.auth.callback.CallbackHandler interface so that it can interact with users to enter specific authentication data, such as user names or passwords, or to display error and warning messages.

Applications implement the CallbackHandler interface and pass it to the login context, which forwards it directly to the underlying login modules. A login module uses the callback handler both to gather input (such as a password or smart card PIN) from users and to supply information (such as status information) to users. Because the application specifies the callback handler, an underlying login module can remain independent of the various ways that applications interact with users.

For example, the implementation of a callback handler for a GUI application might display a window to solicit user input. Or the implementation of a callback handler for a command-line tool might simply prompt the user for input directly from the command line.

The login module passes an array of appropriate callbacks to the callback handler’s handle method (for example, a NameCallback for the user name and a PasswordCallback for the password); the callback handler performs the requested user interaction and sets appropriate values in the callbacks. For example, to process a NameCallback, the CallbackHandler might prompt for a name, retrieve the value from the user, and call the setName method of the NameCallback to store the name.

For more information on using JAAS for login modules for authentication, refer to the following sources:

Links to this information are provided in Further Information about Security.

Using Programmatic Login

Programmatic login enables the client code to supply user credentials. If you are using an EJB client, you can use the com.sun.appserv.security.ProgrammaticLogin class with their convenient login and logout methods.

Because programmatic login is specific to a server, information on programmatic login is not included in this document, but is included in the Sun Java System Application Server 9.1 Developer’s Guide.

Securing EIS Applications

In EIS applications, components request a connection to an EIS resource. As part of this connection, the EIS can require a sign-on for the requester to access the resource. The application component provider has two choices for the design of the EIS sign-on:

You can also configure security for resource adapters. Read Configuring Resource Adapter Security for more information.

Container-Managed Sign-On

In container-managed sign-on, an application component does not have to pass any sign-on security information to the getConnection() method. The security information is supplied by the container, as shown in the following example.

// Business method in an application component
Context initctx = new InitialContext();
// Perform JNDI lookup to obtain a connection factory
javax.resource.cci.ConnectionFactory cxf =
    (javax.resource.cci.ConnectionFactory)initctx.lookup(
    "java:comp/env/eis/MainframeCxFactory");
// Invoke factory to obtain a connection. The security
// information is not passed in the getConnection method
javax.resource.cci.Connection cx = cxf.getConnection();
...

Component-Managed Sign-On

In component-managed sign-on, an application component is responsible for passing the needed sign-on security information to the resource to the getConnection method. For example, security information might be a user name and password, as shown here:

// Method in an application component
Context initctx = new InitialContext();

// Perform JNDI lookup to obtain a connection factory
javax.resource.cci.ConnectionFactory cxf =
    (javax.resource.cci.ConnectionFactory)initctx.lookup(
    "java:comp/env/eis/MainframeCxFactory");

// Get a new ConnectionSpec
com.myeis.ConnectionSpecImpl properties = //..

// Invoke factory to obtain a connection
properties.setUserName("...");
properties.setPassword("...");
javax.resource.cci.Connection cx =
     cxf.getConnection(properties);
...

Configuring Resource Adapter Security

A resource adapter is a system-level software component that typically implements network connectivity to an external resource manager. A resource adapter can extend the functionality of the Java EE platform either by implementing one of the Java EE standard service APIs (such as a JDBC driver), or by defining and implementing a resource adapter for a connector to an external application system. Resource adapters can also provide services that are entirely local, perhaps interacting with native resources. Resource adapters interface with the Java EE platform through the Java EE service provider interfaces (Java EE SPI). A resource adapter that uses the Java EE SPIs to attach to the Java EE platform will be able to work with all Java EE products.

To configure the security settings for a resource adapter, you need to edit the ra.xml file. Here is an example of the part of an ra.xml file that configures the following security properties for a resource adapter:

<authentication-mechanism>
    <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
    <credential-interface>
        javax.resource.spi.security.PasswordCredential
    </credential-interface>
</authentication-mechanism>
<reauthentication-support>false</reauthentication-support>

You can find out more about the options for configuring resource adapter security by reviewing as-install/lib/dtds/connector_1_0.dtd. You can configure the following elements in the resource adapter deployment descriptor file:

In addition to specifying resource adapter security in the ra.xml file, you can create a security map for a connector connection pool to map an application principal or a user group to a back end EIS principal. The security map is usually used in situations where one or more EIS back end principals are used to execute operations (on the EIS) initiated by various principals or user groups in the application. You can find out more about security maps in the Configuring Security chapter section of the Sun Java System Application Server 9.1 Administration Guide.

Mapping an Application Principal to EIS Principals

When using the Application Server, you can use security maps to map the caller identity of the application (principal or user group) to a suitable EIS principal in container-managed transaction-based scenarios. When an application principal initiates a request to an EIS, the Application Server first checks for an exact principal using the security map defined for the connector connection pool to determine the mapped back end EIS principal. If there is no exact match, then the Application Server uses the wild card character specification, if any, to determine the mapped back-end EIS principal. Security maps are used when an application user needs to execute EIS operations that require to be executed as a specific identity in the EIS.

    To work with security maps, use the Admin Console. From the Admin Console, follow these steps to get to the security maps page:

  1. Expand the Resources node.

  2. Expand the Connectors node.

  3. Select the Connector Connection Pools node.

  4. Select a Connector Connection Pool by selecting its name from the list of current pools, or create a new connector connection pool by selecting New from the list of current pools.

  5. Select the Security Maps page.