Configuring Security in Applications and Modules
This chapter explains how to configure security in Jakarta EE applications, EJB, and Web modules.
1. Overview
This section explains basic information related to security configuration for Jakarta EE applications and modules.
The basic procedure for configuring security settings of Jakarta EE 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.
1.1. Module Deployment vs. 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 Jakarta EE application (.ear) by compressing several EJB, Web, and connector modules (.rar files) into an EAR file.
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:
<?xml version="1.0"?>
<ejb-jar xmlns="https://jakarta.ee/xml/ns/jakartaee">
<display-name>product</display-name>
<enterprise-beans>
<entity>
<ejb-name>product</ejb-name> (1)
. . .
<security-role-ref> (2)
<role-name>cust</role-name>
<role-link>customer</role-link>
</security-role-ref>
</entity>
</enterprise-beans>
<assembly-descriptor>
. . .
<security-role> (3)
<role-name>administrator</role-name>
</security-role>
<security-role> (4)
<role-name>customer</role-name>
</security-role>
<method-permission> (5)
<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> (6)
<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> (7)
<role-name>customer</role-name>
<method>
<ejb-name>product</ejb-name>
<method-name>test1</method-name>
</method>
</method-permission>
<exclude-list> (8)
<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:
| 1 | There is an EJB entity called product. |
| 2 | 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. |
| 3 | The logical role administrator is declared. |
| 4 | The logical role customer is declared. |
| 5 | 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. |
| 6 | doSomeAdmin method is declared as unchecked. This means that anyone can call the method regardless of the Role. |
| 7 | Any principal in the role customer can call the test1 method of the product EJB. |
| 8 | 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 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 Principal-to-Role Mapping for more information about the mapping.
1.3. Principal-to-Role Mapping
It is usually the task of the deployer to map the role defined in Jakarta EE 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 a role with the same name, these are recognized as different roles and are not shared.
These concepts are illustrated in the following figure.
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 (Jakarta EE application)
The following is the example of the configuration of jeus-ejb-dd.xml for ejb-jar.xml.
<?xml version="1.0"?>
<jeus-ejb-dd xmlns=“http://www.tmaxsoft.com/xml/ns/jeus”>
<module-info>
<role-permission> (1)
<principal>user1</principal>
<role>administrator</role>
<classname>mypackage.MyRolePermission</classname>
</role-permission>
<role-permission> (2)
<principal>user2</principal>
<role>customer</role>
</role-permission>
<role-permission> (3)
<role>roleA</role>
</excluded>
</role-permission>
<role-permission> (4)
<role>roleB</role>
</unchecked>
</role-permission>
<unspecified-method-permission> (5)
<role>administrator</role>
</unspecified-method-permission>
</module-info>
<beanlist>
. . .
</beanlist>
</jeus-ejb-dd>The previous example contains the following security information.
| 1 | 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 Configuring Security System for more information about the custom role permission. |
| 2 | 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. |
| 3 | The role roleA is excluded from all Principals, which means that no principal can be in roleA. |
| 4 | The role roleB is unchecked in the authorization system, which means that all Principals are automatically included in roleB. |
| 5 | 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. |
|
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. |
1.4. User Configurations
There are two user configuration methods:
-
Use the following file for user configurations of the domain used by applications. (Refer to Configuring the Security System User Information)
JEUS_HOME/domains/<domain name>/config/security/<security domain name>/accounts.xml
-
Configure accounts.xml in the WEB-INF (Web module) or META-INF (EJB module or EAR) directories to set user configurations of EJB module (.jar file), Web module (.war file), or Jakarta EE application (.ear).
|
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. |
2. Configuring EJB Module Security
This section describes in detail how to configure security for EJB modules. For information about security settings such as CSI that are not covered in this section, refer to JEUS EJB Guide.
There are two security configuration methods as follows:
2.1. Configuring ejb-jar.xml
The following security items can be specified in ejb-jar.xml.
-
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.
<?xml version="1.0"?>
<ejb-jar xmlns="https://jakarta.ee/xml/ns/jakartaee">
<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>.
The configurable child tags are as follows.
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-descriptior> 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.
The following describes the child tags of the <method-permission>.
Tag Description <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.
-
<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. 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.
-
|
Refer to 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 JEUS EJB Guide for information about deploying EJB modules in JEUS. |
2.2. Configuring jeus-ejb-dd.xml
The following security items can be configured 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.
<?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)
Descriptions of each child tag of <role-permission> are as follows. Each tag specifies permission for a role (usually a principal-to-role mapping).
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)
An 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)
An 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.
-
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.
|
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.1. Configuring web.xml
web.xml is the main DD file for a Web archive (WAR file). This is a standard Jakarta EE 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.
-
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 <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
-
-
<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.
<?xml version="1.0"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee">
<servlet>
<servlet-name>HelloWorld</servlet-name>
. . .
<run-as> (1)
<role-name>R1</role-name>
</run-as>
<security-role-ref> (2)
<role-name>adminRef</role-name>
<role-link>R1</role-link>
</security-role-ref>
. . .
</servlet>
<security-constraint> (3)
<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> (4)
<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> (5)
<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>The following describes the previous example:
| 1 | 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. |
| 2 | 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. |
| 3 | 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/>. |
| 4 | 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. |
| 5 | Declares three logical roles: R1, R2, and R3. |
If a web resource (URL pattern + HTTP method) is not set separately in web.xml, it means that anyone can access the resource regardless of role. This is the default setting for web application access in Jakarta EE.
|
For detailed information on all tags in web.xml, refer to the servlet specifications. Also, for additional information on deploying servlets in JEUS, refer to JEUS Web Engine Guide. |
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><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).
Tag Description <principal> (0 or more)
The principal name that is mapped to a 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 <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.
|
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.
<?xml version="1.0"?>
<jeus-web-dd xmlns=“http://www.tmaxsoft.com/xml/ns/jeus”>
<context-path>/tutorial</context-path>
<docbase>Tutorial</docbase>
. . .
<role-mapping>
<role-permission> (1)
<principal>user1</principal>
<principal>user2</principal>
<principal>customerGroup</principal>
<role>R1</role>
</role-permission>
<role-permission> (2)
<role>R2</role>
</excluded>
</role-permission>
<role-permission> (3)
<role>R3</role>
</unchecked>
</role-permission>
<role-permission> (4)
<principal>tellerGroup</principal>
<role>R4</role>
<actions>09:00-17:00</actions>
<classname>
jeus.security.resource.TimeConstrainedRolePermission
</classname>
</role-permission>
</role-mapping>
<servlet> (5)
<servlet-name>HelloWorld</servlet-name>
<run-as-identity>
<principal-name>user1</principal-name>
</run-as-identity>
. . .
</servlet>
. . .
</jeus-web-dd>The following describes the previous example:
| 1 | The Principals user1, user2, and customerGroup are in the role R1. |
| 2 | The role R2 is excluded so no one will be in the role. |
| 3 | The role R3 is unchecked so any one can be in the role. |
| 4 | 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. |
| 5 | 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. |
4. Configuring Jakarta EE Application Security
This section explains how to set security for Jakarat EE 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.
4.1. Configuring application.xml
Jakarta EE 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.
<?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> (1)
<role-name>Administrator</role-name>
</security-role>
<security-role> (2)
<role-name>Customer</role-name>
</security-role>
</application>In the previous example, the following two roles are declared.
| 1 | "Administrator" |
| 2 | "Customer" |
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 Configuring EJB Module Security and 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 Configuring jeus-ejb-dd.xml)
-
For Web modules: jeus-web-dd.xml (for more information about principal-to-role mapping, refer to Configuring jeus-web-dd.xml)
It is important to understand all the modules in a Jakarta EE 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.
|
Note that all principal-to-role mappings in Jakarta EE 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. |
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 is mapped to a 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 <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.
<application>
. . .
<role-permission> (1)
<principal>user2</principal>
<role>Administrator</role>
</role-permission>
<role-permission> (2)
<role>Customer</role>
</unchecked>
</role-permission>
. . .
</application>In the previous example, the Jakarta EE application security is set as follows:
| 1 | The principal user2 is mapped to the role Administrator, and uses the default RolePermission. |
| 2 | Since the role is unchecked, all principals are in the role Customer. |
|
5. Example
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 page will directly go to the main page. If the excluded permission is set, authorization will fail and an error page will appear.
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.
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.