REST Authorization

The Authorizations checks in the new REST API are based on Spring Authorization annotations. Currently we only make use of the @PreAuthorize annotations. This means Spring will evaluate the expression within the annotations before executing the annotated method. Spring Security relies on Spring AOP Proxies to do this. This means that inner-class method calls are not evaluated by Spring security (unless you autowire a self-reference, see this StackOverflow discussion).

If the evaluation of the expression fails or returns false, Spring will not execute the method and return a 40x response. If the user is authenticated this will be a 403 Forbidden response. If the user is not authenticated, this will be a 401 Unauthorized response. This is configured using the DSpace401AuthenticationEntryPoint class.

The type of expressions we use are:

1. hasPermission(#uuid, 'DSO-TYPE', 'ACTION'): Check if the current user is allowed to execute the listed action on the specified DSpace Object (for example downloading a bitstream).

   # Example #1:  Only allows you to access this method, if you have READ permissions on the BITSTREAM identified by the "id" parameter
   @PreAuthorize("hasPermission(#id, 'BITSTREAM', 'READ')")
   public BitstreamRest findOne(Context context, UUID id) {
   ...
   }
   
   
   # Example #2: Only allows you to access this method, if you have READ permissions on the GROUP identified by the "id" parameter
   @PreAuthorize("hasPermission(#id, 'GROUP', 'READ')")
   public GroupRest findOne(Context context, UUID id) {
   ...
   }

2. hasAuthority('VALUE'): Check if the current user has a specific Spring authority. Currently there are only three authority values: ADMIN, EPERSON and ANONYMOUS. (for example when querying all items).

   # Example #1: Only allows you to access this method if you are logged in as a system Administrator
   @PreAuthorize("hasAuthority('ADMIN')")
   public Page<BitstreamRest> findAll(Context context, Pageable pageable) {
   ...
   }
   
   # Example #2: Only allows you to access this method if you are currently logged in to the system
   @PreAuthorize("hasAuthority('AUTHENTICATED')")
   public AuthorityRest findOne(Context context, String name) {
   ...
   }
   
   
   # Example #3: Only allows you to access this method if you are anonymous (not logged in)
   @PreAuthorize("hasAuthority('ANONYMOUS')")
   public someMethod() {
   ...
   }

For the evaluation of the hasPermission expressions, we wrote a custom "permission evaluator" DSpacePermissionEvaluator that uses a plug-in system. If one of the available plug-ins approves the requested permission, the current user is allowed to execute the action. Plugins are dynamically "discovered" using the Spring auto-wiring functionality. The plug-ins we implemented are:

1. AuthorizeServicePermissionEvaluatorPlugin: Check permissions based on the DSpace AuthorizeService. This service will validate if the authenticated user is allowed to perform an action on the given DSpace Object based on the resource policies attached to that DSpace object.

2. EPersonRestPermissionEvaluatorPlugin: An authenticated user is allowed to view, update or delete his or her own data. Since there are no explicit resource policies for this, the AuthorizeService does not cover this use case.

3. GroupRestPermissionEvaluatorPlugin: An authenticated user is allowed to view the information of all the groups he or she is a member of (READ permission). Since there are no explicit resource policies for this, the AuthorizeService does not cover this use case.

4. AdminRestPermissionEvaluatorPlugin: Repository Administrators are always allowed to perform any action on any DSpace object. This plugin will check if the authenticated EPerson is a repository administrator. If that is the case, the authenticated EPerson is allowed to perform the requested action.

You can easily add your own custom permission evaluator plugins by implementing the DSpacePermissionEvaluator interface and registering your implementation in the Spring application context.