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

java.lang.Object
  org.apache.shiro.web.servlet.ServletContextSupport
      org.apache.shiro.web.servlet.AbstractFilter
          org.apache.shiro.web.servlet.NameableFilter
              org.apache.shiro.web.servlet.OncePerRequestFilter
                  org.apache.shiro.web.servlet.AdviceFilter
                      org.apache.shiro.web.filter.PathMatchingFilter
                          org.apache.shiro.web.filter.AccessControlFilter
                              org.apache.shiro.web.filter.authz.AuthorizationFilter
                                  org.apache.shiro.web.filter.authz.PermissionsAuthorizationFilter
                                      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 Method	Mapped Action	Example Permission	Runtime Check
head	read	perm1	perm1:read
get	read	perm2	perm2:read
put	update	perm3	perm3:update
post	create	perm4	perm4:create
mkcol	create	perm5	perm5:create
options	read	perm6	perm6:read
trace	read	perm7	perm7: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