7.15.2. Permission Check by annotation¶

7.15.2.1.1. Permission checks can be performed without complicated data management¶

Permission check by annotation assigns roles to users. Also, for functions that you want to check for authorization, assign the roles necessary to perform them. Then authorization is determined by whether the current user has the role assigned to the function to be performed.

Roles are basically assigned to functions by an annotation. You can choose any method for assigning users and roles, because the framework does not specify any particular method.

Thus, the permission check by annotation can manage authorization with a simpler data structure than Permission Check by handler.

7.15.2.1.2. You can check the permission by the annotation¶

@CheckRole("ADMIN")
public HttpResponse index(HttpRequest request, ExecutionContext context) {

In the permission check by annotation, roles can be assigned to methods of the action class using annotations. The above example defines that the ADMIN role is required to execute the index method.

7.15.2.1.3. Difference from permission check by handler function¶

This section explains the criteria for using this permission check by annotation versus Permission Check by handler.

Permission check by annotation manages authorization in units of roles as described above. And the mechanism for assigning roles and functions is through Java annotations. Therefore, the use of this permission check by annotation is appropriate when the increase or decrease of roles themselves or changes in functions assigned to roles do not occur frequently.

For example, if the types of roles and combinations of functions that require authorization management have been determined and are not expected to change significantly in the future, this permission check by annotation can be used to easily perform permission checks.

On the other hand, in a system where users want to control permissions according to the department to which they belong, it is expected that the composition of departments and the combination of available functions will change significantly due to organizational changes. If this permission check by annotation is used in such a system, the annotations will need to be rewritten for each change, which will require a large amount of man-hours for modification. In such a system, it is recommended that Permission Check by handler be used to manage the combination of authorizations with data.

7.15.2.3.1. Advance preparation¶

<component name="roleEvaluator"
           class="nablarch.common.authorization.role.BasicRoleEvaluator">
    <property name="userRoleResolver" ref="userRoleResolver" />
</component>

<component name="userRoleResolver"
           class="nablarch.common.authorization.role.session.SessionStoreUserRoleResolver" />

<import file="nablarch/common/authorization/role/session/authorization-session.xml" />

<!-- The definition of execution order of interceptors. -->
<list name="interceptorsOrder">
  <!-- Add the CheckRole -->
  <value>nablarch.common.authorization.role.CheckRole</value>
  <!-- Other interceptor descriptions are omitted. -->
</list>

public class Roles {
    /** The role of the system administrator. */
    public static final String ROLE_ADMIN = "ADMIN";
    /** The role of the project manager. */
    public static final String ROLE_PROJECT_MANAGER = "PROJECT_MANAGER";
}

List<String> userRoles = resolveUserRoles(loginId);
SessionStoreUserRoleUtil.save(userRoles, executionContext);

7.15.2.3.2. Assign roles to methods of actions with annotations¶

@CheckRole(Roles.ROLE_ADMIN)
public HttpResponse index(HttpRequest request, ExecutionContext context) {

You can assign roles to an action method by the value of CheckRole annotation. In the above example, the ADMIN role is assigned to the index method. This allows the index method to be executed only by users with the ADMIN role. If a user without the ADMIN role tries to execute a method, Forbidden is thrown.

If you want assign multiple roles, you can specify by an array. An example implementation is shown below.

@CheckRole({Roles.ROLE_ADMIN, Roles.ROLE_PROJECT_MANAGER})
public HttpResponse index(HttpRequest request, ExecutionContext context) {

In this case, the ADMIN and PROJECT_MANAGER roles must both be held (AND condition) in order to execute the index method.

Set anyOf to true if you want an OR condition. An example implementation is shown below.

@CheckRole(
    value = {Roles.ROLE_ADMIN, Roles.ROLE_PROJECT_MANAGER},
    anyOf = true
)
public HttpResponse index(HttpRequest request, ExecutionContext context) {

In the above example, to execute the index method, a user need to have either the ADMIN or PROJECT_MANAGER role.

7.15.2.3.3. List CheckRole settings¶

To check for errors in CheckRole annotations set for action methods, this function is provided to list the annotation setting status. By using this function, it will be possible to check whether there are any omissions in the annotation settings and whether the set contents are excessive or insufficient.

This function is achieved by collecting annotation setting information at system startup and outputting them to the log at the debug level. The configuration method is described below.

First, define the CheckRoleLogger component as follows.

<!-- Components that need to be initialized -->
<component name="initializer"
           class="nablarch.core.repository.initialization.BasicApplicationInitializer">
  <property name="initializeList">
    <list>
      <!-- Omit other components that require initialization. -->

      <component class="nablarch.common.authorization.role.CheckRoleLogger">
        <property name="targetPackage" value="com.nablarch.example.app.web.action" />
      </component>
    </list>
  </property>
</component>

CheckRoleLogger is set in the initializeList of the BasicApplicationInitializer as the component that needs to be initialized. Also, at this time, specify the package in which action classes exist in the targetPackage property (including subpackages).

By default, classes with names ending in Action are processed. This setting can be changed by specifying any regular expression for the targetClassPattern property. See CheckRoleLogger‘s Javadoc for details.

After completing the above settings, start the system with the log level set to debug level. This will result in the following log output at system startup.

2023-01-11 14:29:31.643 -DEBUG- nablarch.common.authorization.role.CheckRoleLogger [null] boot_proc = [] proc_sys = [nablarch-example-web] req_id = [null] usr_id = [null] CheckRole Annotation Settings
class signature       role    anyOf
com.nablarch.example.app.web.action.AuthenticationAction      index(nablarch.fw.web.HttpRequest, nablarch.fw.ExecutionContext)
(omission)
com.nablarch.example.app.web.action.ProjectBulkAction update(nablarch.fw.web.HttpRequest, nablarch.fw.ExecutionContext)
com.nablarch.example.app.web.action.ProjectUploadAction       index(nablarch.fw.web.HttpRequest, nablarch.fw.ExecutionContext)        ADMIN   true
com.nablarch.example.app.web.action.ProjectUploadAction       index(nablarch.fw.web.HttpRequest, nablarch.fw.ExecutionContext)        PROJECT_MANAGER true

The following elements are output in the log, separated by tabs.

If multiple roles are assigned, each role is output on a separate line. For example, in the above output example, we see that the index method of ProjectUploadAction is assigned two roles, ADMIN and PROJECT_MANAGER. When replaced by an implementation, this would be set up as follows.

@CheckRole(
    value = {Roles.ROLE_ADMIN, Roles.ROLE_PROJECT_MANAGER},
    anyOf = true
)
public HttpResponse index(HttpRequest request, ExecutionContext context) {

7.15.2.3.4. Programmatic check¶

The presence or absence of a role can be checked anywhere in the program.

if (CheckRoleUtil.checkRole(Roles.ROLE_ADMIN, executionContext)) {
    // Processing when user has the ADMIN role
}

To programmatic check the presence or absence of a role, use CheckRoleUtil. In the above example, the checkRole method is used to check if the current user has the ADMIN role.

Multiple roles can be checked using the checkRoleAllOf or checkRoleAnyOf methods.

7.15.2.3.5. Check in JSP¶

Permission Check by handler provides a mechanism for JSP custom tags to perform permision checks and automatically show or hide buttons. However, this permission check by annotation does not provide such a mechanism.

Therefore, this section describes how to control the display of tags in JSP by role after adopting this permission check by annotation.

The control of display by role is achieved by storing the results of the check on the server side in a session store or other location. An example implementation is shown below.

UserContext userContext = new UserContext();
userContext.setAdmin(CheckRoleUtil.checkRole(Roles.ROLE_ADMIN, executionContext));
userContext.setProjectManager(CheckRoleUtil.checkRole(Roles.ROLE_PROJECT_MANAGER, executionContext));

SessionUtil.put(executionContext, "userContext", userContext);

In this example, the result of check the user’s role at login is stored in the UserContext class and stored in the session store (UserContext is just Java Beans, created as needed for each project). This will allow you to use EL expressions and JSTL in JSP to control the display as follows

<c:if test="${userContext.admin}">
  <%-- Show when a user has the ADMIN role --%>
</c:if>
<c:if test="${userContext.projectManager}">
  <%-- Show when a user has the PROJECT_MANAGER role  --%>
</c:if>