org.apache.shiro.web.filter.authz
Class HttpMethodPermissionFilter

java.lang.Object
  extended by org.apache.shiro.web.servlet.ServletContextSupport
      extended by org.apache.shiro.web.servlet.AbstractFilter
          extended by org.apache.shiro.web.servlet.NameableFilter
              extended by org.apache.shiro.web.servlet.OncePerRequestFilter
                  extended by org.apache.shiro.web.servlet.AdviceFilter
                      extended by org.apache.shiro.web.filter.PathMatchingFilter
                          extended by org.apache.shiro.web.filter.AccessControlFilter
                              extended by org.apache.shiro.web.filter.authz.AuthorizationFilter
                                  extended by org.apache.shiro.web.filter.authz.PermissionsAuthorizationFilter
                                      extended by org.apache.shiro.web.filter.authz.HttpMethodPermissionFilter
All Implemented Interfaces:
Filter, Nameable, PathConfigProcessor

public class HttpMethodPermissionFilter
extends PermissionsAuthorizationFilter

A filter that translates an HTTP Request's Method (eg GET, POST, etc) into an corresponding action (verb) and uses that verb to construct a permission that will be checked to determine access.

This Filter is primarily provided to support REST environments where the type (Method) of request translates to an action being performed on one or more resources. This paradigm works well with Shiro's concepts of using permissions for access control and can be leveraged to easily perform permission checks.

This filter functions as follows:

  1. The incoming HTTP request's Method (GET, POST, PUT, DELETE, etc) is discovered.
  2. The Method is translated into a more 'application friendly' verb, such as 'create', edit', 'delete', etc.
  3. The verb is appended to any configured permissions for the currently matching path.
  4. If the current Subject isPermitted to perform the resolved action, the request is allowed to continue.

For example, if the following filter chain was defined, where 'rest' was the name given to a filter instance of this class:

 /user/** = rest[user]
Then an HTTP GET request to /user/1234 would translate to the constructed permission user:read (GET is mapped to the 'read' action) and execute the permission check Subject.isPermitted("user:read") in order to allow the request to continue.

Similarly, an HTTP POST to /user would translate to the constructed permission user:create (POST is mapped to the 'create' action) and execute the permission check Subject.isPermitted("user:create") in order to allow the request to continue.

Method To Verb Mapping

The following table represents the default HTTP Method-to-action verb mapping:
HTTP MethodMapped ActionExample PermissionRuntime Check
headreadperm1perm1:read
getreadperm2perm2:read
putupdateperm3perm3:update
postcreateperm4perm4:create
mkcolcreateperm5perm5:create
optionsreadperm6perm6:read
tracereadperm7perm7:read

Since:
1.0

Field Summary
 
Fields inherited from class org.apache.shiro.web.filter.AccessControlFilter
DEFAULT_LOGIN_URL, GET_METHOD, POST_METHOD
 
Fields inherited from class org.apache.shiro.web.filter.PathMatchingFilter
appliedPaths, pathMatcher
 
Fields inherited from class org.apache.shiro.web.servlet.OncePerRequestFilter
ALREADY_FILTERED_SUFFIX
 
Fields inherited from class org.apache.shiro.web.servlet.AbstractFilter
filterConfig
 
Constructor Summary
HttpMethodPermissionFilter()
          Creates the filter instance with default method-to-action values in the instance's http method actions map.
 
Method Summary
protected  String[] buildPermissions(HttpServletRequest request, String[] configuredPerms, String action)
          Returns a collection of String permissions with which to perform a permission check to determine if the filter will allow the request to continue.
protected  String[] buildPermissions(String[] configuredPerms, String action)
          Builds a new array of permission strings based on the original argument, appending the specified action verb to each one per WildcardPermission conventions.
protected  String getHttpMethodAction(ServletRequest request)
          Determines the action (verb) attempting to be performed on the filtered resource by the current request.
protected  String getHttpMethodAction(String method)
          Determines the corresponding application action that will be performed on the filtered resource based on the specified HTTP method (GET, POST, etc).
protected  Map<String,String> getHttpMethodActions()
          Returns the HTTP Method name (key) to action verb (value) mapping used to resolve actions based on an incoming HttpServletRequest.
 boolean isAccessAllowed(ServletRequest request, ServletResponse response, Object mappedValue)
          Resolves an 'application friendly' action verb based on the HttpServletRequest's method, appends that action to each configured permission (the mappedValue argument is a String[] array), and delegates the permission check for the newly constructed permission(s) to the superclass isAccessAllowed implementation to perform the actual permission check.
 
Methods inherited from class org.apache.shiro.web.filter.authz.AuthorizationFilter
getUnauthorizedUrl, onAccessDenied, setUnauthorizedUrl
 
Methods inherited from class org.apache.shiro.web.filter.AccessControlFilter
getLoginUrl, getSubject, isLoginRequest, onAccessDenied, onPreHandle, redirectToLogin, saveRequest, saveRequestAndRedirectToLogin, setLoginUrl
 
Methods inherited from class org.apache.shiro.web.filter.PathMatchingFilter
getPathWithinApplication, isEnabled, pathsMatch, pathsMatch, preHandle, processPathConfig
 
Methods inherited from class org.apache.shiro.web.servlet.AdviceFilter
afterCompletion, cleanup, doFilterInternal, executeChain, postHandle
 
Methods inherited from class org.apache.shiro.web.servlet.OncePerRequestFilter
doFilter, getAlreadyFilteredAttributeName, isEnabled, isEnabled, setEnabled, shouldNotFilter
 
Methods inherited from class org.apache.shiro.web.servlet.NameableFilter
getName, setName, toStringBuilder
 
Methods inherited from class org.apache.shiro.web.servlet.AbstractFilter
destroy, getFilterConfig, getInitParam, init, onFilterConfigSet, setFilterConfig
 
Methods inherited from class org.apache.shiro.web.servlet.ServletContextSupport
getContextAttribute, getContextInitParam, getServletContext, removeContextAttribute, setContextAttribute, setServletContext, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

HttpMethodPermissionFilter

public HttpMethodPermissionFilter()
Creates the filter instance with default method-to-action values in the instance's http method actions map.

Method Detail

getHttpMethodActions

protected Map<String,String> getHttpMethodActions()
Returns the HTTP Method name (key) to action verb (value) mapping used to resolve actions based on an incoming HttpServletRequest. All keys and values are lower-case. The default key/value pairs are defined in the top class-level JavaDoc.

Returns:
the HTTP Method lower-case name (key) to lower-case action verb (value) mapping

getHttpMethodAction

protected String getHttpMethodAction(ServletRequest request)
Determines the action (verb) attempting to be performed on the filtered resource by the current request.

This implementation expects the incoming request to be an HttpServletRequest and returns a mapped action based on the HTTP request method.

Parameters:
request - to pull the method from.
Returns:
The string equivalent verb of the http method.

getHttpMethodAction

protected String getHttpMethodAction(String method)
Determines the corresponding application action that will be performed on the filtered resource based on the specified HTTP method (GET, POST, etc).

Parameters:
method - to be translated into the verb.
Returns:
The string equivalent verb of the method.

buildPermissions

protected String[] buildPermissions(HttpServletRequest request,
                                    String[] configuredPerms,
                                    String action)
Returns a collection of String permissions with which to perform a permission check to determine if the filter will allow the request to continue.

This implementation merely delegates to buildPermissions(String[], String) and ignores the inbound HTTP servlet request, but it can be overridden by subclasses for more complex request-specific building logic if necessary.

Parameters:
request - the inbound HTTP request - ignored in this implementation, but available to subclasses for more complex construction building logic if necessary
configuredPerms - any url-specific permissions mapped to this filter in the URL rules mappings.
action - the application-friendly action (verb) resolved based on the HTTP Method name.
Returns:
a collection of String permissions with which to perform a permission check to determine if the filter will allow the request to continue.

buildPermissions

protected String[] buildPermissions(String[] configuredPerms,
                                    String action)
Builds a new array of permission strings based on the original argument, appending the specified action verb to each one per WildcardPermission conventions. The built permission strings will be the ones used at runtime during the permission check that determines if filter access should be allowed to continue or not.

For example, if the configuredPerms argument contains the following 3 permission strings:

  1. permission:one
  2. permission:two
  3. permission:three
And the action is read, then the return value will be:
  1. permission:one:read
  2. permission:two:read
  3. permission:three:read
per WildcardPermission conventions. Subclasses are of course free to override this method or the buildPermissions request variant for custom building logic or with different permission formats.

Parameters:
configuredPerms - list of configuredPerms to be converted.
action - the resolved action based on the request method to be appended to permission strings.
Returns:
an array of permission strings with each element appended with the action.

isAccessAllowed

public boolean isAccessAllowed(ServletRequest request,
                               ServletResponse response,
                               Object mappedValue)
                        throws IOException
Resolves an 'application friendly' action verb based on the HttpServletRequest's method, appends that action to each configured permission (the mappedValue argument is a String[] array), and delegates the permission check for the newly constructed permission(s) to the superclass isAccessAllowed implementation to perform the actual permission check.

Overrides:
isAccessAllowed in class PermissionsAuthorizationFilter
Parameters:
request - the inbound ServletRequest
response - the outbound ServletResponse
mappedValue - the filter-specific config value mapped to this filter in the URL rules mappings.
Returns:
true if the request should proceed through the filter normally, false if the request should be processed by this filter's AccessControlFilter.onAccessDenied(ServletRequest,ServletResponse,Object) method instead.
Throws:
IOException


Copyright © 2004-2016 The Apache Software Foundation. All Rights Reserved.