org.jsecurity.web.servlet
Class JSecurityFilter

java.lang.Object
  org.jsecurity.web.servlet.ServletContextSupport
      org.jsecurity.web.servlet.OncePerRequestFilter
          org.jsecurity.web.servlet.SecurityManagerFilter
              org.jsecurity.web.servlet.JSecurityFilter

All Implemented Interfaces:

Filter

Direct Known Subclasses:

SpringJSecurityFilter

public class JSecurityFilter
extends SecurityManagerFilter

Main ServletFilter that configures and enables all JSecurity functions within a web application. The following is a fully commented example that documents how to configure it:

<filter>
   <filter-name>JSecurityFilter</filter-name>
   <filter-class>org.jsecurity.web.servlet.JSecurityFilter</filter-class>
   <init-param><param-name>config</param-name><param-value>

   #NOTE:  This config looks pretty long - but its not - its only 5 lines of actual config.
   #       Everything else is just heavily commented to explain things in-depth. Feel free to delete any
   #       comments that you don't want to read from your own configuration ;)
   #
   # Any commented values below are JSecurity's defaults.  If you want to change any values, you only
   # need to uncomment the lines you want to change.

   [main]
   # The 'main' section defines JSecurity-wide configuration.
   #
   # Session Mode: By default, JSecurity's Session infrastructure in a web environment will use the
   # Servlet container's HttpSession.  However, if you need to share session state across client types
   # (e.g. Web MVC plus Java Web Start or Flash), or are doing distributed/shared Sessions for
   # Single Sign On, HttpSessions aren't good enough.  You'll need to use JSecurity's more powerful
   # (and client-agnostic) session management.  You can enable this by uncommenting the following line
   # and changing 'http' to 'jsecurity'
   #
   #sessionMode = http

   [interceptors]
   # This section defines the 'pool' of all the available interceptors that are available to the url path
   # definitions below in the [urls] section.
   #
   # The following commented values are already provided by JSecurity by default and are immediately usable
   # in the [urls] definitions below.  If you like, you may override any values by uncommenting only the lines
   # you need to change.
   #
   # Each interceptor is configured based on its functionality and/or protocol.  You should read each
   # interceptor's JavaDoc to fully understand what each does and how it works as well as how it would
   # affect the user experience.
   #
   # Form Authentication interceptor: requires the requestiing user to be authenticated for the request to continue
   # and if they are not, forces the user to login via a login page that you specify.  If the login attempt fails
   # the AuthenticationException fully qualified class name will be placed as a request attribute under the
   # 'failureKeyAttribute' name below.  This FQCN can then be used as an i18n key or lookup mechanism that can then
   # be used to show the user why their login attempt failed (e.g. no account, incorrect password, etc).
   #authc = org.jsecurity.web.interceptor.authc.FormAuthenticationWebInterceptor
   #authc.url = /login.jsp
   #authc.usernameParam = username
   #authc.passwordParam = password
   #authc.rememberMeParam = rememberMe
   #authc.successUrl = /login.jsp
   #authc.failureKeyAttribute = org.jsecurity.web.interceptor.authc.FormAuthenticationWebInterceptor_AUTHC_FAILURE_KEY
   #
   # Http BASIC Authentication interceptor: requires the requesting user to be authenticated for the request
   # to continue, and if they're not, forces the user to login via the HTTP Basic protocol-specific challenge.
   # Upon successful login, they're allowed to continue on to the requested resource/url.
   #authcBasic = org.jsecurity.web.interceptor.authc.BasicHttpAuthenticationWebInterceptor
   #authcBasic.applicationName = JSecurity Quickstart
   #
   # Roles interceptor: requires the requesting user to have one or more roles for the request to continue.
   # If they do not have the specified roles, they are redirected to the specified URL.
   #roles = org.jsecurity.web.interceptor.authz.RolesAuthorizationWebInterceptor
   #roles.url =
   # (note the above url is null by default, which will cause an HTTP 403 (Access Denied) response instead
   # of redirecting to a page.  If you want to show a 'nice page' instead, you should specify that url.
   #
   # Permissions interceptor: requires the requesting user to have one or more permissions for the request to
   # continue, and if they do not, redirects them to the 'unauthorizedPage' defined in the [main] section.
   #perms = org.jsecurity.web.interceptor.authz.PermissionsAuthorizationWebInterceptor
   #perms.url =
   # (note the above url is null by default, which will cause an HTTP 403 (Access Denied) response instead
   # of redirecting to a page.  If you want to show a 'nice page' instead, you should specify that url.  Many
   # applications like to use the same url specified in roles.url above.
   #
   #
   # Define your own interceptors here.  To properly handle path matching, all interceptor implementations
   # should extend the org.jsecurity.web.interceptor.PathMatchingWebInterceptor abstract class.

   [urls]
   # This section defines url path mappings.  Each mapping entry must be on a single line and conform to the
   # following representation:
   #
   # ant_path_expression = path_specific_interceptor_chain_definition
   #
   # For any request that matches a specified path, the corresponding value defines a comma-delimited chain of
   # filters/interceptors to execute for that request.
   #
   # This is incredibly powerful in that you can define arbitrary filter chains for any given request pattern
   # to greatly customize the security experience.
   #
   # The path_specific_interceptor_chain_definition must match the following format:
   #
   # interceptor1[optional_config1], interceptor2[optional_config2], ..., interceptorN[optional_configN]
   #
   # where 'interceptorN' is the name of an interceptor defined above in the [interceptors] section and
   # '[optional_configN]' is an optional bracketed string that has meaning for that particular interceptor for
   # _that particular path_.  If the interceptor does not need specific config for that url path, you may
   # discard the brackets - that is, interceptorN[] just becomes interceptorN.
   #
   # And because interceptor tokens define chains, order matters!  Define the tokens for each path pattern
   # in the order you want them to filter (comma-delimited).
   #
   # Finally, each interceptor is free to handle the response however it wants if its necessary
   # conditions are not met (redirect, HTTP error code, direct rendering, etc).  Otherwise, it is expected to allow
   # the request to continue through the chain on to the final destination view.
   #
   # Examples:
   #
   # To illustrate chain configuration, look at the /account/** mapping below.  This says
   # "apply the above 'authcBasic' interceptor to any request matching the '/account/**' pattern".  Since the
   # 'authcBasic' interceptor does not need any path-specific config, it doesn't have any config brackets [].
   #
   # The /remoting/** definition on the other hand uses the 'roles' and 'perms' interceptors which do use
   # bracket notation.  That definition says:
   #
   # "To access /remoting/** urls, ensure that the user is first authenticated ('authcBasic'), then ensure that user
   # has the 'b2bClient' role, and then finally ensure that they have the 'remote:invoke:lan,wan' permission."
   #
   # (Note that because elements within brackets [ ] are comma-delimited themselves, we needed to escape the permission
   # actions of 'lan,wan' with quotes.  If we didn't do that, the permission interceptor would interpret
   # the text between the brackets as two permissions: 'remote:invoke:lan' and 'wan' instead of the
   # single desired 'remote:invoke:lan,wan' token.  So, you can use quotes wherever you need to escape internal
   # commas.)

   /account/** = authcBasic
   /remoting/** = authcBasic, roles[b2bClient], perms[remote:invoke:"lan,wan"]

   </param-value></init-param>
</filter>


<filter-mapping>
    <filter-name>JSecurityFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Since:

0.1

Author:

Les Hazlewood, Jeremy Haile

Field Summary

protected String	config
protected Map<String,Object>	filtersAndInterceptors
protected InterceptorBuilder	interceptorBuilder
protected String	interceptors
protected String	main
protected String	unauthorizedPage
protected String	urls

Fields inherited from class org.jsecurity.web.servlet.SecurityManagerFilter

securityManagerListener

Fields inherited from class org.jsecurity.web.servlet.OncePerRequestFilter

ALREADY_FILTERED_SUFFIX, filterConfig

Fields inherited from class org.jsecurity.web.servlet.ServletContextSupport

HTTP_SESSION_MODE, JSECURITY_SESSION_MODE, log, SESSION_MODE_CONTEXT_PARAM_NAME

Constructor Summary

JSecurityFilter()

Method Summary

protected void	applyConfig()
protected void	applyInitParams()
protected void	applySessionMode()
protected void	applyUrlMappings()
protected void	applyWebInterceptorFilters()
void	destroy()
protected void	doFilterInternal(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain origChain) Same contract as for doFilter, but guaranteed to be just invoked once per request.
protected void	ensureWebInterceptors()
String	getConfig()
Map<String,Object>	getFiltersAndInterceptors()
String	getInterceptors()
String	getMain()
String	getUnauthorizedPage()
String	getUrls()
protected boolean	isHttpSessions()
protected void	onFilterConfigSet()
void	setConfig(String config)
void	setFiltersAndInterceptors(Map<String,Object> filtersAndInterceptors)
void	setInterceptors(String interceptors)
void	setMain(String main)
void	setUnauthorizedPage(String unauthorizedPage)
void	setUrls(String urls)

Methods inherited from class org.jsecurity.web.servlet.SecurityManagerFilter

afterSecurityManagerSet, getSecurityManager

Methods inherited from class org.jsecurity.web.servlet.OncePerRequestFilter

doFilter, getAlreadyFilteredAttributeName, getFilterConfig, getFilterName, init, setFilterConfig, shouldNotFilter

Methods inherited from class org.jsecurity.web.servlet.ServletContextSupport

bind, getAttribute, getContextInitParam, getServletContext, getSessionMode, removeAttribute, setAttribute, setServletContext, setSessionMode

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

config

protected String config

main

protected String main

interceptors

protected String interceptors

urls

protected String urls

unauthorizedPage

protected String unauthorizedPage

filtersAndInterceptors

protected Map<String,Object> filtersAndInterceptors

interceptorBuilder

protected InterceptorBuilder interceptorBuilder

Constructor Detail

JSecurityFilter

public JSecurityFilter()

Method Detail

getFiltersAndInterceptors

public Map<String,Object> getFiltersAndInterceptors()

setFiltersAndInterceptors

public void setFiltersAndInterceptors(Map<String,Object> filtersAndInterceptors)

getConfig

public String getConfig()

setConfig

public void setConfig(String config)

getMain

public String getMain()

setMain

public void setMain(String main)

getInterceptors

public String getInterceptors()

setInterceptors

public void setInterceptors(String interceptors)

getUrls

public String getUrls()

setUrls

public void setUrls(String urls)

getUnauthorizedPage

public String getUnauthorizedPage()

setUnauthorizedPage

public void setUnauthorizedPage(String unauthorizedPage)

onFilterConfigSet

protected void onFilterConfigSet()
                          throws Exception

Overrides:

onFilterConfigSet in class SecurityManagerFilter

Throws:

Exception

applySessionMode

protected void applySessionMode()

Overrides:

applySessionMode in class ServletContextSupport

applyConfig

protected void applyConfig()
                    throws Exception

Throws:

Exception

applyInitParams

protected void applyInitParams()

ensureWebInterceptors

protected void ensureWebInterceptors()

applyWebInterceptorFilters

protected void applyWebInterceptorFilters()
                                   throws ServletException

Throws:

ServletException

applyUrlMappings

protected void applyUrlMappings()
                         throws ParseException

Throws:

ParseException

isHttpSessions

protected boolean isHttpSessions()

Overrides:

isHttpSessions in class ServletContextSupport

doFilterInternal

protected void doFilterInternal(ServletRequest servletRequest,
                                ServletResponse servletResponse,
                                FilterChain origChain)
                         throws ServletException,
                                IOException

Description copied from class: OncePerRequestFilter

Same contract as for doFilter, but guaranteed to be just invoked once per request. Provides HttpServletRequest and HttpServletResponse arguments instead of the default ServletRequest and ServletResponse ones.

Specified by:

doFilterInternal in class OncePerRequestFilter

Throws:

ServletException

IOException

destroy

public void destroy()

Specified by:

destroy in interface Filter

Overrides:

destroy in class SecurityManagerFilter