Chapter 3. Configuring Security for Applications and Modules

Tag	Description
<ejb-name>	The EJB name that contains the method.
<method-intf>	The EJB interface type that contains the method. If omitted, all interfaces in local and remote servers are implied.
<method-name>	EJB method name.
<method-params> (optional)	Can have multiple <method-param> tags. The <method-param> tag represents each parameter of the EJB method. If the <method-param> tag is omitted, the same permissions will be applied to any method with the given method-name, regardless of the parameter. (In EJB, there may be multiple methods that have the same name but different parameters. The Method Permission will be applied to all the methods with the same name.) The value of the <method-param> tag must be a fully qualified Java class name that includes the package name or Java Primitive type such as int. If <method-params> is empty (<method-params/>), the method has no parameters.

Tag	Description
<principal>(0 or more)	The principal name that is mapped to a Role.
<role> (required)	Only one is allowed. A required name of the logical role. This name will be passed as the first parameter of the constructor of the Java class that implements the role permission. The role name must match the logical name specified in ejb-jar.xml.
<actions>(optional)	Contains additional data for the role permission. If set, this action data will be passed as the second parameter of the constructor of the Java class that implements the role permission.
<classname> (optional)	The fully qualified Java class name of the class that implements the role permission. This class must be a subclass of the java.security.Permission class and have a public constructor that accepts at least one parameter for the role name. If omitted, the jeus.security. resource.RolePermission class is used.
<excluded> (optional)	The empty tag. If set, the role will be excluded (no one can access the Role(s) defined for the role permission). This takes precedence over the <principal> and <unchecked> tags.
<unchecked> (optional)	The empty tag. If set, the role will be unchecked (anyone can access the Role(s) defined in the role permission). This takes precedence over the <principal> tag.

Tag	Description
<principal> (0 or more)	The principal name to be mapped to the Role.
<role>(1, required)	The logical role name. This will be passed as the first parameter of the constructor of the Java class that implements the role permission. The role name must match the logical role name in web.xml.
<actions>(optional)	Contains additional data for the role permission. If set, this action data will be passed as the second parameter of the constructor of the Java class that implements the role permission.
<classname>(optional)	The Java class name that implements the role permission. This class must be a sub class of the java.security.Permission class and have a public constructor that accepts at least one string parameter (the role name). If omitted, the jeus.security.resource.RolePermission class is used.
<excluded>(optional)	An empty tag. If set, the role will be excluded. In other words, no principal can be in the role. This takes precedence over the <principal> and the <unchecked> tags.
<unchecked>(optional)	An empty tag. If set, the role will be unchecked. In other words, any principal can be in the role. This takes precedence over the <principal> tag.

3.1. Overview

This section explains basic information related to security configuration for J2EE applications and modules.

The basic procedure for configuring security settings of J2EE application, EJB module, and web module is as follows.

Configure Role-to-Resource mapping for each module.
Configure principal-to-role mapping for each application.

3.1.1. Module Deployment and Application Deployment

There are two ways of deploying an application in JEUS:

Deploy each EJB module (EJB.jar file) and Web module (.war file) independently.
Deploy a J2EE application (.ear) by compressing several EJB, Web, and connector modules (.rar files) into an EAR file.

3.1.2. Role-to-Resource Mapping

Before deploying an EJB or Web module, the assembler must first configure the role-to-resource mapping for the module. The role-to-resource mapping is also called the security constraint, which refers to mapping a resource of a module to a logical Role.

In EJB modules, resources refer to EJB methods, and they are configured in META-INF/ejb-jar.xml

In web modules, resources refer to the servlet URLs, and they are configured in WEB-INF/web.xml.

The following are the security constraints configured in the META-INF/ejb-jar.xml file for an EJB module:

[Example 3.1] Security Constraints Configured in EJB Module: <<ejb-jar.xml>>

<?xml version="1.0"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee">
    <display-name>product</display-name>
    <enterprise-beans>
        <entity>
           <ejb-name>product</ejb-name>
            . . .
           <security-role-ref>
                <role-name>cust</role-name>
                <role-link>customer</role-link>
            </security-role-ref>
        </entity>
    </enterprise-beans>
    <assembly-descriptor>
        . . .
       <security-role>
            <role-name>administrator</role-name>
        </security-role>
       <security-role>
            <role-name>customer</role-name>
        </security-role>
       <method-permission>
            <role-name>administrator</role-name>
            <method>
                <ejb-name>product</ejb-name>
                <method-intf>Remote</method-intf>
                <method-name>getSecretKey</method-name>
                <method-params>
                   <method-param>java.lang.Integer</method-param>
                </method-params>
            </method>
        </method-permission>
      <method-permission>
            <unchecked/>
            <method>
                <ejb-name>product</ejb-name>
                <method-name>doSomeAdmin</method-name>
                <method-params>
                    <method-param>java.lang.String</method-param>
                </method-params>
            </method>
        </method-permission>
       <method-permission>
            <role-name>customer</role-name>
            <method>
                <ejb-name>product</ejb-name>
                <method-name>test1</method-name>
            </method>
        </method-permission>
       <exclude-list>
            <method>
                <ejb-name>product</ejb-name>
                <method-intf>Remote</method-intf>
                <method-name>getCustomerProfile</method-name>
                <method-params></method-params>
            </method>
        </exclude-list>
    </assembly-descriptor>
</ejb-jar>

Descriptions of security constraints in the previous DD (deployment descriptor) file are as follows:

	There is an EJB entity called product.
	The role-to-role reference mapping is declared. The actual declared Role, customer, can be referred to by the role reference name, cust, which means that the role named cust in the EJB code corresponds to the customer Role.
	The logical role administrator is declared.
	The logical role customer is declared.
	The role-to-resource mapping is declared. This enables the role administrator to call the getSecreteKey method of the remote EJB interface. According to this mapping, only Principals belonging to the administrator role can call the getSecreteKey method.
	doSomeAdmin method is declared as unchecked. This means that anyone can call the method regardless of the Role.
	Any principal in the role customer can call the test1 method of the product EJB.
	The getCustomerProfile method is included in the Excluded list. This means that no role can call this method.

The configuration for Web modules is similar to that for EJB modules except that the Roles access Servlet URLs instead of EJB methods. Refer to "3.3. Configuring Web Module Security" for more information about security configuration for Web modules.

The two Roles, administrator and customer, are purely logical and do not have any meaning in the target deployment environment. Therefore, these logical Roles must be mapped to the actual users or user groups of the target system. This is referred to as principal-to-role mapping. Refer to "3.1.3. Principal-to-Role Mapping" for more information about the mapping.

3.1.3. Principal-to-Role Mapping

It is usually the task of the deployer to map the role defined in J2EE modules or applications to users or user groups in the actual environment. Note that mappings from Principals to logical Roles have application scope.

For example, if two modules M1 and M2 are deployed as parts of the same application A1, the principal-to-role mappings will be shared by the two modules. Furthermore, another application A2 may have a totally different principal-to-role from A1. Even if A1 and A2 each have the a role with the same name, these are recognized as different roles and are not shared.

These concepts are illustrated in the following figure.

[Figure 3.1] Principal-to-Role Mapping

As shown in the previous figure, two different applications A1 and A2 have different principal-to-role mappings, and two modules M1 and M2 share the mapping included in the application.

The principal-to-role mapping is defined in the following files in JEUS.

jeus-ejb-dd.xml, the JEUS DD file (EJB module)
jeus-web-dd.xml (web module)
jeus-application-dd.xml (J2EE application)

The following is the example of the configuration of jeus-ejb-dd.xml for ejb-jar.xml.

[Example 3.2] Principal-to-Role Mapping: <<jeus-ejb-dd.xml>>

<?xml version="1.0"?>

<jeus-ejb-dd xmlns=“http://www.tmaxsoft.com/xml/ns/jeus”>
     <module-info>
       <role-permission>
            <principal>user1</principal>
            <role>administrator</role>
            <classname>mypackage.MyRolePermission</classname>
        </role-permission>
       <role-permission>
            <principal>user2</principal>
            <role>customer</role>
        </role-permission>
       <role-permission>
            <role>roleA</role>
            </excluded>
        </role-permission>
       <role-permission>
            <role>roleB</role>
            </unchecked>
        </role-permission>
       <unspecified-method-permission>
            <role>administrator</role>
        </unspecified-method-permission>
    </module-info>
    <beanlist>
        . . .
    </beanlist>
</jeus-ejb-dd>

The previous example contains the following security information.

	The role permission that grants the principal (user) named user1 to be in the role administrator. This means that user1 is mapped to the role administrator, and consequently, user1 will inherit all the rights of the Role. As can be seen in the previous example, custom role permission is defined in the <classname> tag. Refer to "Chapter 2. Configuring the Security System" for more information about the custom role permission.
	The Role-permission that grants the principal (user) named user2 to be in role customer. This means that user2 is mapped to the role customer and consequently, user2 will inherit all the rights of role Customer. Since no <classname> tag is specified, the default role permission will be used.
	The role roleA is excluded from all Principals, which means that no principal can be in roleA.
	The role roleB is unchecked in the authorization system, which means that all Principals are automatically included in roleB.
	The <unspecified-method-permission> tag determines how unspecified EJB methods are to be handled. An unspecified EJB method is an EJB method that is not included in the <method-permission> tag in ejb-jar.xml. The <unspecified-method-permission> can be handled in the following three ways: be mapped to a role (like in this example where they are mapped to the role administrator), be marked as excluded (accessible to no one) or be marked as unchecked (be accessible to everyone). The last option, unchecked, is the default value.

Note

The configurations for Web modules (jeus-web-dd.xml) is similar to that for EJB modules, except that the <unspecified-method-permission> tag is not used for Web modules.

3.1.4. User Configurations

There are two user configuration methods:

Using user configuration method of the domain that is used by applications, configure the JEUS_HOME/domains/<domain name>/config/security/<security domain name>/accounts.xml file. (Refer to "2.5. Configuring the Security System User Information")
Using the user configuration method of EJB modules (EJB .jar file), Web modules (.war file), and J2EE applications (.ear file), configure the accounts.xml file in the WEB-INF (web module) or META-INF ( EJB module and EAR) directory.

Note

User information has application security domain scope, regardless of the way it is configured. In other words, a user in a security domain is shared by all applications using the same security domain.

3.2. Configuring EJB Module Security

This section explains in detail how to configure security for EJB modules. For more information about security configurations that are not covered here, such as CSI, refer to "JEUS EJB Guide".

There are two security configuration methods as follows:

Configuring ejb-jar.xml

Configuring jeus-ejb-dd.xml

3.2.1. Configuring ejb-jar.xml

The ejb-jar.xml file is used to configure the following security items.

Role-to-Role Reference mapping

security identity configuration

Logical role declaration

EJB method permission configurations

The following example illustrates how to specify the aforementioned security items in ejb-jar.xml.

[Example 3.3] Security Configurations: <<ejb-jar.xml>>

<?xml version="1.0"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee">
    <display-name>product</display-name>
    <enterprise-beans>
        <entity>
            <ejb-name>product</ejb-name>
            . . .
            <security-role-ref>
                <role-name>cust</role-name>
                <role-link>customer</role-link>
            </security-role-ref>
            <security-identity>
                <run-as>
                    <role-name>administrator</role-name>
                </run-as>
            </security-identity>
        </entity>
    </enterprise-beans>
    <assembly-descriptor>
        . . .
        <security-role>
            <role-name>administrator</role-name>
        </security-role>
        <security-role>
            <role-name>customer</role-name>
        </security-role>
        <method-permission>
            <role-name>administrator</role-name>
            <method>
                <ejb-name>product</ejb-name>
                <method-intf>Remote</method-intf>
                <method-name>getSecretKey</method-name>
                <method-params>
                   <method-param>java.lang.Integer</method-param>
                </method-params>
            </method>
        </method-permission>
        <method-permission>
            <unchecked/>
            <method>
                <ejb-name>product</ejb-name>
                <method-name>doSomeAdmin</method-name>
                <method-params>
                    <method-param>java.lang.String</method-param>
                </method-params>
            </method>
        </method-permission>
        <method-permission>
            <role-name>customer</role-name>
            <method>
                <ejb-name>product</ejb-name>
                <method-name>test1</method-name>
            </method>
        </method-permission>
        <exclude-list>
            <method>
                <ejb-name>product</ejb-name>
                <method-intf>Remote</method-intf>
                <method-name>getCustomerProfile</method-name>
                <method-params></method-params>
            </method>
        </exclude-list>
    </assembly-descriptor>
</ejb-jar>

The following security items can be specified in ejb-jar.xml.

Role-to-Role Reference mapping

The role-to-role reference mapping is specified in the <security-role-ref> tag. Its purpose is to map a role reference to a logical role. In the EJB code, the role reference is used instead of the actual Role.

The following tags are used inside the <security-role-ref> tag.

Tag	Description
<role-name>	The role reference which is used in EJB code instead of the actual role name.
<role-link>	The name of the actual role declared in the security-role tag. The role reference is mapped to a role indicated by the role-link.

security identity configuration

Every EJB in the module has a security identity, which will be propagated to other EJBs during remote calls. The security identity for an EJB is configured using the tags, <ejb-jar> <enterprise-beans> <type><security-identity>.

It has the following child tags.

Tag	Description
<use-caller-identity>	If this tag is empty, the caller of the EJB will be used as the security identity.
<run-as>	If this tag is used, the principal of the role specified in <role-name> will be used as the security identity when an EJB is called. If the <run-as-identity> tag exists in jeus-ejb-dd.xml, this setting will be ignored.

Logical role declaration

The <security-role> tag under the <assembly-descriptor> tag specifies the logical Roles that will apply to the corresponding EJB module. All role names in ejb-jar.xml must be specified in this tag.

EJB method Permission configuration

The <method-permission> tag, inside the <assembly-descriptor> tag, specifies security constraints for each EJB method. Child tags are as follows.

<role-name> (optional)

Specifies the name of a logical role defined in <security-role>. It has access to the methods defined in the following.

<unchecked> (optional)

An empty tag. If specified, the following methods will be unchecked. Anyone can access these methods, regardless of its Role.

<method> (One or more)

The method to which the <role-name> and <unchecked> tags will be applied. The child tags are as follows.

Tag Description
<ejb-name> The EJB name that contains the method.
<method-intf> The EJB interface type that contains the method. If omitted, all interfaces in local and remote servers are implied.
<method-name> EJB method name.
<method-params>
(optional)
Can have multiple <method-param> tags.
The <method-param> tag represents each parameter of the EJB method.
If the <method-param> tag is omitted, the same permissions will be applied to any method with the given method-name, regardless of the parameter. (In EJB, there may be multiple methods that have the same name but different parameters. The Method Permission will be applied to all the methods with the same name.)
The value of the <method-param> tag must be a fully qualified Java class name that includes the package name or Java Primitive type such as int.
If <method-params> is empty (<method-params/>), the method has no parameters.

<exclude-list> (one)

Defines excluded EJB methods that no one can access. Only one <excluded-list> tag can exist, but can have multiple child <method> tags.

Note

Refer to "3.1.2. Role-to-Resource Mapping" for an explanation of the previous example. Refer to the EJB specification for more information about these tags. Also refer to the "JEUS EJB Guide" for information about deploying EJB modules in JEUS.

3.2.2. Configuring jeus-ejb-dd.xml

The following security configuration items can be specified in jeus-ejb-dd.xml.

Security-related configurations

Configuring EJB methods that are not defined in ejb-jar.xml

Configuring EJB principal which uses the run-as identity

While the ejb-jar.xml file takes care of most role-to-method mappings for the EJB, it still needs to determine where to declare the principal-to-role mappings and how to handle EJB methods that were not handled in ejb-jar.xml. These mappings and handling are configured in the jeus-ejb-dd.xml file, which usually resides in the META-INF directory of the deployed EJB .jar archive.

The following example illustrates how to configure the previous security configuration items in jeus-ejb-dd.xml.

[Example 3.4] Security Configurations: <<jeus-ejb-dd.xml>>

<?xml version="1.0"?>
<jeus-ejb-dd xmlns=“http://www.tmaxsoft.com/xml/ns/jeus”>
     <module-info>
        <role-permission>
            <principal>user1</principal>
            <role>administrator</role>
            <classname>mypackage.MyRolePermission</classname>
        </role-permission>
        <role-permission>
            <principal>user2</principal>
            <role>customer</role>
        </role-permission>
        <role-permission>
            <role>roleA</role>
            </excluded>
        </role-permission>
        <role-permission>
            <role>roleB</role>
            </unchecked>
        </role-permission>
        <unspecified-method-permission>
            <role>administrator</role>
        </unspecified-method-permission>
    </module-info>
    <beanlist>
        <jeus-bean>
            . . .
            <run-as-identity>
                <principal-name>user1</principal-name>
            </run-as-identity>
        </jeus-bean>
        . . .
    </beanlist>
</jeus-ejb-dd>

The following security items can be configured in jeus-ejb-dd.xml.

Security-related configurations

Most security-related settings in jeus-ejb-dd.xml are set in the <jeus-ejb-dd> tag just below the parent tag, <module-info>.

<role-permission> (0 or more)

Each tag specifies permission for a role (usually a principal-to-role mapping).

Descriptions of each child tag of <role-permission> are as follows.

Tag Description
<principal>(0 or more) The principal name that is mapped to a Role.
<role> (required)
Only one is allowed. A required name of the logical role.
This name will be passed as the first parameter of the constructor of the Java class that implements the role permission. The role name must match the logical name specified in ejb-jar.xml.
<actions>(optional) Contains additional data for the role permission. If set, this action data will be passed as the second parameter of the constructor of the Java class that implements the role permission.
<classname> (optional)
The fully qualified Java class name of the class that implements the role permission. This class must be a subclass of the java.security.Permission class and have a public constructor that accepts at least one parameter for the role name.
If omitted, the jeus.security. resource.RolePermission class is used.
<excluded> (optional)
The empty tag. If set, the role will be excluded (no one can access the Role(s) defined for the role permission).
This takes precedence over the <principal> and <unchecked> tags.
<unchecked> (optional)
The empty tag. If set, the role will be unchecked (anyone can access the Role(s) defined in the role permission).
This takes precedence over the <principal> tag.

Configuring EJB methods that are not defined in ejb-jar.xml

There are three ways to handle EJB methods that are not specified in ejb-jar.xml. They are defined in the child tag, <unspecified-method-permission>, inside the <module-info> tag.

The configurable child tags are as follows.

Tag	Description
<role>(optional)	If set, all unspecified methods will be mapped to this Role.
<excluded>(optional)	If set, all unspecified methods will be excluded (accessible by no one). This takes precedence over the <Role> and the <unchecked> tags.
<unchecked>(optional)	If set, all unspecified methods will be unchecked (accessible by anyone). This takes precedence over the <Role> tag.

Tag

Description

<role>(optional)

If set, all unspecified methods will be mapped to this Role.

<excluded>(optional)

If set, all unspecified methods will be excluded (accessible by no one).

This takes precedence over the <Role> and the <unchecked> tags.

<unchecked>(optional)

If set, all unspecified methods will be unchecked (accessible by anyone).

This takes precedence over the <Role> tag.

Configuring EJB Principal which uses the run-as identity

The principal needs to be set for an EJB that uses the run-as identity. The principal name specified in the <jeus-bean> <run-as-identity> <principal-name> tag is used. The principal must be in the role that is specified in the <security-identity><run-as><role-name> tag of ejb-jar.xml.

Note

1. Refer to "3.1.2. Role-to-Resource Mapping" for an explanation of the example.

2. Refer to "JEUS EJB Guide" for more information about these tags.

3.3. Configuring Web Module Security

This section explains in detail how to configure security for web (Servlet) modules.

The security of web modules is divided into two parts:

Configuring web.xml: Role-to-Web Resource mapping configurations

Configuring jeus-web-dd.xml: principal-to-role mapping configurations

3.3.1. Configuring web.xml

web.xml is the main DD file for a Web archive (WAR file). This is a standard J2EE DD file that usually resides in the WEB-INF directory of the WAR file.

The security items that can be configured in web.xml are as follows.

run-as identity

Every Servlet in the Web module has a security identity, which will be propagated to EJBs during a remote call.

The security identity for a servlet is configured in the <web-app><servlet><run-as> tag, which has the following child tag.

Tag Description
<role-name>(optional) The role that runs the servlet. If omitted, the caller identity will be used.

Tag	Description
<role-name>(optional)	The role that runs the servlet. If omitted, the caller identity will be used.

Role-to-role reference mapping

The role-to-role reference mappings are configured in the <security-role-ref> tag. Its purpose is to map a role reference to a logical Role. The role reference represents the role in the servlet code.

The <security-role-ref> tag is configured inside the <servlet> tag of web.xml and has the following child tags.

Tag	Description
<role-name>	The role name that is used in Servlet codes.
<role-link>	The actual role name defined in the <security-role> tag. The role reference will be mapped to the actual role defined in the <role-name> tag.

Permissions to access servlet URL (Security constraints)

To restrict the access to Servlet URL, the <security-constraint> tag inside the <web-app> tag is used.

<security-constraint> has the following child tags.

<web-resource-collection> (one or more)

Specifies a list of Web resources for which access constrains are set.

Tag	Description
<web-resource-name>	The name of the web resource.
<url-patterns>(0 or more)	The URL (relative to the context root) pattern that is a part of the Web resource. The following are URL pattern examples. "/mywebapp/": All URL that includes mywebapp "/something": The exact URL ".jsp" : All resources that ends with "Jsp"
<http-method>(0 or more)	The HTTP methods that apply to the web resources. GET POST PUT

Tag

Description

<web-resource-name>

The name of the web resource.

<url-patterns>(0 or more)

The URL (relative to the context root) pattern that is a part of the Web resource.

The following are URL pattern examples.

"/mywebapp/*": All URL that includes mywebapp
"/something": The exact URL
"*.jsp" : All resources that ends with "Jsp"

<http-method>(0 or more)

The HTTP methods that apply to the web resources.

GET
POST
PUT

<auth-constraint> (optional)

Specifies the roles that can access the web resource defined in the <security-constraint> tag. There must be zero or more <role-name> child tag(s), each specifying a logical role name that allows access to the resource.

If no role name is specified and it is empty (<auth-constraint/>), no one can access the web resource (same as excluded Web resources).

If the <auth-constraint> tag is omitted, the web resource will be unchecked so that any one can access it regardless of the role.

<user-data-constraint> (optional)

Sets whether to declare a "transport guarantee" for connections that are made to the web resources.

It has the <transport-guarantee> child tag, which specifies the guarantee level for the Web resource connections.

Value	Description
NONE	The connection is unprotected.
INTEGRAL	The connection guarantees the message integrity (ensures that the sent message has not been modified).
CONFIDENTIAL	Ensures that the messages sent are encrypted to prevent eavesdropping.

Logical Role Declaration

After the <security-constraint> tag, there is the <security-role> tag that declares the logical roles. Each tag has the <role-name> tag, that declares the logical role names defined in DD.

The following is an example of security configurations of web.xml.

[Example 3.5] Web Module Security Configurations: <<web.xml>>

<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee">
    <servlet>
        <servlet-name>HelloWorld</servlet-name>
        . . .

       <run-as>
            <role-name>R1</role-name>
        </run-as>
       <security-role-ref>
            <role-name>adminRef</role-name>
            <role-link>R1</role-link>
        </security-role-ref>
        . . .

    </servlet>
   <security-constraint>
       <web-resource-collection>
            <web-resource-name>A</web-resource-name>
            <url-pattern>/a/*</url-pattern>
            <url-pattern>/b/*</url-pattern>
            <url-pattern>/a</url-pattern>
            <url-pattern>/b</url-pattern>
            <http-method>DELETE</http-method>
            <http-method>PUT</http-method>
        </web-resource-collection>
        <web-resource-collection>
            <web-resource-name>B</web-resource-name>
            <url-pattern>*.asp</url-pattern>
        </web-resource-collection>
        <auth-constraint/>
    </security-constraint>
   <security-constraint>
        <web-resource-collection>
            <web-resource-name>C</web-resource-name>
            <url-pattern>/a/*</url-pattern>
            <url-pattern>/b/*</url-pattern>
            <http-method>GET</http-method>
        </web-resource-collection>
        <web-resource-collection>
            <web-resource-name>D</web-resource-name>
            <url-pattern>/b/*</url-pattern>
            <http-method>POST</http-method>
        </web-resource-collection>

        <auth-constraint>
            <role-name>R1</role-name>
        </auth-constraint>
        <user-data-constraint>
            <transport-guarantee>
                CONFIDENTIAL
            </transport-guarantee>
        </user-data-constraint>
    </security-constraint>
   <security-role>
        <role-name>R1</role-name>
    </security-role>
    <security-role>
        <role-name>R2</role-name>
    </security-role>
    <security-role>
        <role-name>R3</role-name>
    </security-role>
</web-app>

Descriptions of the previous example are as follows:

	The run-as-identity is set to role R1, meaning that the propagated security identity of the servlet must be a principal that is in R1. The actual principal is specified in the JEUS DD file.
	In the <security-role-ref> tag, the actual role R1 is mapped to the role reference adminRef. In the actual Servlet source codes, the role reference adminRef is used instead of the Role.
	The first security constraint specifies that the URLs with patterns, "/a", "/b", "/a/", "/b/" and HTTP methods DELETE and PUT, and all URLs that end with "*.asp" must NOT be accessible to anyone. This is because it is set to <auth-constraint/>.
	The second security constraint says that the URLs with patterns, "/a/", "/b/" and HTTP method GET, and all URLs with the pattern /b/* and HTTP method POST should only be accessible by Principals that are in the role R1 and the connection should be CONFIDENTIAL.
	Declares three logical roles: R1, R2, and R3.

If a web resource (URL patterns + HTTP methods) is not configured in web.xml, anyone can access the resource regardless of the Role. This is the default rule for Web applications in J2EE.

Note

Refer to the Servlet specifications for more information about the tags in web.xml. Also refer to "JEUS Web Engine Guide" for additional information about deploying Servlets in JEUS.

3.3.2. Configuring jeus-web-dd.xml

This section explains how to configure jeus-web-dd.xml, which is the JEUS DD file for web modules.

Defining Principal-to-Role mapping

To define a principal-to-role mapping in jeus-web-dd.xml, use the <jeus-web-dd> <context><role-mapping> tag.

The following are child tags of <role-mapping>.

<role-permission> (0 or more)

Specifies permission for a role (usually a principal-to-role mapping).

The following are descriptions for the child tags.

Tag Description
<principal> (0 or more) The principal name to be mapped to the Role.
<role>(1, required)
The logical role name.
This will be passed as the first parameter of the constructor of the Java class that implements the role permission. The role name must match the logical role name in web.xml.
<actions>(optional) Contains additional data for the role permission. If set, this action data will be passed as the second parameter of the constructor of the Java class that implements the role permission.
<classname>(optional)
The Java class name that implements the role permission.
This class must be a sub class of the java.security.Permission class and have a public constructor that accepts at least one string parameter (the role name).
If omitted, the jeus.security.resource.RolePermission class is used.
<excluded>(optional)
An empty tag. If set, the role will be excluded.
In other words, no principal can be in the role.
This takes precedence over the <principal> and the <unchecked> tags.
<unchecked>(optional)
An empty tag. If set, the role will be unchecked.
In other words, any principal can be in the role.
This takes precedence over the <principal> tag.

Setting <run-as-principal> in servlet

To set <run-as-principal> tag in a servlet, define the <servlet> tag and add the <run-as><principal-name> tag to it. The value of the <principal-name> tag must be the principal that belongs to the role defined in <run-as><role-name> tag of web.xml.

Caution

Currently, there are no tags to specify how to handle the Servlet URLs that are not defined in web.xml of jeus-web-dd.xml. In the Servlet specifications, all unspecified Servlet URLs are always regarded as unchecked and accessible by everyone.

The following is an example of security configurations in jeus-web-dd.xml.

[Example 3.6] Web Module Security Configurations: <<jeus-web-dd.xml>>

<?xml version="1.0"?>
<jeus-web-dd xmlns=“http://www.tmaxsoft.com/xml/ns/jeus”>
    <context>
        <context-path>/tutorial</context-path>
        <docbase>Tutorial</docbase>
        . . .
        <role-mapping>
           <role-permission>
                <principal>user1</principal>
                <principal>user2</principal>
                <principal>customerGroup</principal>
                <role>R1</role>
            </role-permission>
           <role-permission>
                <role>R2</role>
                </excluded>
            </role-permission>
           <role-permission>
                <role>R3</role>
                </unchecked>
            </role-permission>
           <role-permission>
                <principal>tellerGroup</principal>
                <role>R4</role>
                <actions>09:00-17:00</actions>
                <classname>
                    jeus.security.resource.TimeConstrainedRolePermission
                </classname>
            </role-permission>
        </role-mapping>
     <servlet>
           <servlet-name>HelloWorld</servlet-name>
        <run-as-identity>
           <principal-name>user1</principal-name>
        </run-as-identity>
        . . .
    </context>
</servlet>
        . . .
</jeus-web-dd>

Explanation of the previous example are as follows.

	The Principals user1, user2, and customerGroup are in the role R1.
	The role R2 is excluded so no one will be in the role.
	The role R3 is unchecked so any one can be in the role.
	The principal tellerGroup will be in the role R4 on the condition that the current time is between 9 am and 5 pm. This logic is implemented in the implies() method of the jeus.security.resource.TimeConstrainedRolePermission class.
	user1 is used as a run-as-principal. When the Servlet calls an EJB, user1 will be passed as the security identity. Note that the deployer must check that user1 is in the role R1, which is defined in web.xml.

3.4. Configuring J2EE Application Security

This section explains how to set security for J2EE applications (EAR file).

The basic procedure is as follows:

Configuring application.xml: Declare logical roles.
Configuring jeus-application-dd.xml: Configure the security domain for deployment and principal-to-role mapping.

3.4.1. Configuring application.xml

J2EE application is an archive file with the ".ear" extension. The EAR archive consists of EJB, Web, and connector modules, and any other necessary supporting classes. The META-INF directory contains the application.xml configuration file that provides various information about the application.

This section explains the security-related information in application.xml.

There is basically only one type of security information in application.xml: declaration of logical security Roles. The role declaration applies to all EJB and Web modules in the EAR file and has an application scope.

[Example 3.7] J2EE Application Security Configuration: <<application.xml>>

<?xml version="1.0" encoding="UTF-8"?>
<application version="1.4" . . .>
    <description>Application description</description>
    <display-name>myApp</display-name>
    <module>
        <web>
            <web-uri>myWebApp.war</web-uri>
            <context-root>myWebApp</context-root>
        </web>
    </module>
    <module>
        <ejb>myEjbApp.jar</ejb>
    </module>
   <security-role>
        <role-name>Administrator</role-name>
    </security-role>
   <security-role>
        <role-name>Customer</role-name>
    </security-role>
</application>

In the previous example, the two Roles, Administrator and Customer, are declared.

These two roles are used in the DD files of EJB and Web modules to define role-to-resource mappings. Securities for EJB and web modules are explained in "3.2. Configuring EJB Module Security" and "3.3. Configuring Web Module Security".

Before deploying applications to the JEUS Server, ensure that logical roles are mapped to the actual Principals. This mapping is configured in the following files.

For applications: jeus-application-dd.xml

For EJB modules: jeus-ejb-dd.xml (for more information about principal-to-role mapping, refer to "3.2.2. Configuring jeus-ejb-dd.xml")

For Web modules: jeus-web-dd.xml (for more information about principal-to-role mapping, refer to "3.3.2. Configuring jeus-web-dd.xml")

It is important to understand all the modules in a J2EE application, because Roles and principal-to-role mappings are shared within the limits of the application. If the role Administrator is defined in the application. xml file, and the principal user2 is granted the role Administrator in jeus-application-dd.xml, this role will be applied to all EJBs and Web modules in the application.

In the same way, even though this role and principal-to-role mapping are defined only in jeus-ejb-dd.xml of a particular EJB module, they are accessible to all modules in the EAR file.

Caution

Note that all principal-to-role mappings in J2EE applications have an application scope whether it is configured in jeus-application-dd.xml, or in a certain jeus-ejb-dd.xml or jeus-web-dd.xml file.

3.4.2. Configuring jeus-application-dd.xml

The principal-to-role mappings on the application level are set in jeus-application-dd.xml.

To define a principal-to-role mapping, add the following tags under the <application> tag in jeus-application-dd.xml.

<role-permission>(optional)

Each <role-permission> tag defines a principal-to-role mapping and can optionally configure Excluded and Unchecked Roles. This tag works exactly the same that in jeus-web-dd.xml, jeus-ejb-dd.xml, and policies.xml files.

It has the following child tags.

Tag	Description
<principal>(0 or more)	The principal name that will be mapped to the Role.
<role>(1, required)	The logical role name. This will be passed as the first parameter of the constructor of the Java class that implements the role permission. The role name must match the logical role name in application.xml.
<actions>(optional)	Contains additional data for the role permission. If set, this action data will be passed as the second parameter of the constructor of the Java class that implements the role permission.
<classname>(optional)	The name of the Java class that implements the role permission. This class must be a subclass of the java.security.Permission class and have a public constructor that accepts at least one string parameter (the role name). If omitted, the jeus.security.resource.RolePermission class is used.
<excluded>(optional)	An empty tag. If set, the role will be excluded. No one can be in the Role(s) defined in the role permission. This takes precedence over the <principal> and the <unchecked> tags.
<unchecked>(optional)	An empty tag. If set, the role will be unchecked. Anyone can be in the Role(s) defined in the role permission. This takes precedence over the <principal> tag.

The security domain to which the application is deployed must be specified inside the <application> tag. By default, the security domain, SYSTEM_DOMAIN, will be used, but if a particular application requires a specific security service, a new domain that includes the security service must be created and deployed.

The security domain name can be specified using the deploy command of jeusadmin.

[Example 3.8] J2EE Application Security Configurations: <<jeus-application-dd.xml>>

    <application>
        . . .
       <role-permission>
           <principal>user2</principal>
           <role>Administrator</role>
        </role-permission>
       <role-permission>
           <role>Customer</role>
           </unchecked>
        </role-permission>
        . . .
    </application>

In the previous example, the J2EE application security is set as follows:

	The principal user2 is mapped to the role Administrator, and uses the default RolePermission.
	Since the role is unchecked, All principals are in the role Customer.

Note

1. For more information about configuring a security domain, refer to "2.2. Configuring the Security System Domain".

2. For more information about how to develop and configure Custom Permissions, refer to "2.6. Configuring Security System Policies".

3. For more information about how to deploy J2EE applications to JEUS, refer to "JEUS Server Guide".

3.5. Examples

This section briefly introduces the configuration examples from the previous sections.

The following page shows the login page for accessing the main page. The following page can be accessed only when the checked permission has been set for the URL. If the unchecked permission is set, the screen will directly go to the main page. If the excluded permission is set, authorization will fail and an error page will appear.

[Figure 3.2] Login Page

If authorization fails or an attempt was made to login using an unauthorized account, an error page will appear. If the login is successful, the following page will appear.

[Figure 3.3] Main Page

The previous main page has three Servlet links, and can call three EJB methods. A successful login is dependent on the login account and the configuration files. Thus, a user can directly check for accessibility using different configurations and login accounts.

Prev		Next
Chapter 2. Configuring the Security System	Home	Chapter 4. Programming with the Security System API