diff --git a/docs/manual/src/docbook/appendix-namespace.xml b/docs/manual/src/docbook/appendix-namespace.xml index 706c53fa33..4f9ccfa4d7 100644 --- a/docs/manual/src/docbook/appendix-namespace.xml +++ b/docs/manual/src/docbook/appendix-namespace.xml @@ -117,10 +117,7 @@
<literal>access-denied-page</literal> - Allows the access denied page to be set (the user will be redirected here if an - AccessDeniedException is raised). Corresponds to the - errorPage property set on the AccessDeniedHandlerImpl which is - used by the ExceptionTranslationFilter. + Deprecated in favour of the access-denied-handler child element.
@@ -145,6 +142,16 @@ + +
+ <literal>access-denied-handler</literal> + + This element allows you to set the errorPage property for the default + AccessDeniedHandler used by the ExceptionTranslationFilter, + (using the error-page attribute, or to supply your own implementation using the ref + attribute. See for more information on the implementation details. + +
The <literal><intercept-url></literal> Element diff --git a/docs/manual/src/docbook/basic-and-digest-auth.xml b/docs/manual/src/docbook/basic-and-digest-auth.xml new file mode 100644 index 0000000000..8eec346175 --- /dev/null +++ b/docs/manual/src/docbook/basic-and-digest-auth.xml @@ -0,0 +1,170 @@ + + + Basic and Digest Authentication + + Basic and digest authentiation are alternative authentication mechanisms which are popular + in web applications. Basic authentication is often used with stateless clients which pass + their credentials on each request. It's quite common to use it in combination with form-based + authentication where an application is used through both a browser-based user interface + and as a web-service. However, basic authentication transmits the password as plain text so it + should only really be used over an encrypted transport layer such as HTTPS. +
+ + <classname>BasicProcessingFilter</classname> + + BasicProcessingFilter is responsible for processing basic + authentication credentials presented in HTTP headers. This can be used for + authenticating calls made by Spring remoting protocols (such as Hessian and Burlap), as + well as normal browser user agents (such as Firefox and Internet Explorer). The standard + governing HTTP Basic Authentication is defined by RFC 1945, Section 11, and + BasicProcessingFilter conforms with this RFC. Basic + Authentication is an attractive approach to authentication, because it is very widely + deployed in user agents and implementation is extremely simple (it's just a Base64 + encoding of the username:password, specified in an HTTP header). +
+ + Configuration + + To implement HTTP Basic Authentication, you need to add a + BasicProcessingFilter to your filter chain. The application + context should contain BasicProcessingFilter and its + required collaborator: + + + + + + + + +]]> + + + The configured AuthenticationManager processes each + authentication request. If authentication fails, the configured + AuthenticationEntryPoint will be used to retry the + authentication process. Usually you will use the filter in combination with a + BasicProcessingFilterEntryPoint, which returns a 401 response + with a suitable header to retry HTTP Basic authentication. If authentication is + successful, the resulting Authentication object will be + placed into the SecurityContextHolder as usual. + If the authentication event was successful, or authentication was not attempted + because the HTTP header did not contain a supported authentication request, the filter + chain will continue as normal. The only time the filter chain will be interrupted is if + authentication fails and the AuthenticationEntryPoint is + called. +
+
+ +
+ <classname>DigestProcessingFilter</classname> + DigestProcessingFilter is capable + of processing digest authentication credentials presented in HTTP headers. Digest + Authentication attempts to solve many of the weaknesses of Basic authentication, + specifically by ensuring credentials are never sent in clear text across the wire. Many + user agents support Digest Authentication, including FireFox and Internet Explorer. The + standard governing HTTP Digest Authentication is defined by RFC 2617, which updates an + earlier version of the Digest Authentication standard prescribed by RFC 2069. Most user + agents implement RFC 2617. Spring Security's DigestProcessingFilter is + compatible with the "auth" quality of protection + (qop) prescribed by RFC 2617, which also provides backward + compatibility with RFC 2069. Digest Authentication is a more attractive option if you + need to use unencrypted HTTP (i.e. no TLS/HTTPS) and wish to maximise security of the + authentication process. Indeed Digest Authentication is a mandatory requirement for the + WebDAV protocol, as noted by RFC 2518 Section 17.1. + Digest Authentication is definitely the most secure choice between Form + Authentication, Basic Authentication and Digest Authentication, although extra security + also means more complex user agent implementations. Central to Digest Authentication is + a "nonce". This is a value the server generates. Spring Security's nonce adopts the + following format: + + + base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key)) + + expirationTime: The date and time when the nonce expires, expressed in milliseconds + key: A private key to prevent modification of the nonce token + + + The DigestProcessingFilterEntryPoint has a property specifying the + key used for generating the nonce tokens, along with a + nonceValiditySeconds property for determining the expiration time + (default 300, which equals five minutes). Whist ever the nonce is valid, the digest is + computed by concatenating various strings including the username, password, nonce, URI + being requested, a client-generated nonce (merely a random value which the user agent + generates each request), the realm name etc, then performing an MD5 hash. Both the + server and user agent perform this digest computation, resulting in different hash codes + if they disagree on an included value (eg password). In Spring Security implementation, + if the server-generated nonce has merely expired (but the digest was otherwise valid), + the DigestProcessingFilterEntryPoint will send a + "stale=true" header. This tells the user agent there is no need + to disturb the user (as the password and username etc is correct), but simply to try + again using a new nonce. + An appropriate value for DigestProcessingFilterEntryPoint's + nonceValiditySeconds parameter will depend on your application. + Extremely secure applications should note that an intercepted authentication header can + be used to impersonate the principal until the expirationTime + contained in the nonce is reached. This is the key principle when selecting an + appropriate setting, but it would be unusual for immensely secure applications to not be + running over TLS/HTTPS in the first instance. + Because of the more complex implementation of Digest Authentication, there are often + user agent issues. For example, Internet Explorer fails to present an + "opaque" token on subsequent requests in the same session. Spring + Security filters therefore encapsulate all state information into the + "nonce" token instead. In our testing, Spring Security's + implementation works reliably with FireFox and Internet Explorer, correctly handling + nonce timeouts etc. +
+ Configuration + Now that we've reviewed the theory, let's see how to use it. To implement HTTP Digest + Authentication, it is necessary to define DigestProcessingFilter in + the fitler chain. The application context will need to define the + DigestProcessingFilter and its required collaborators: + + + + + + + + + + + +]]> + + + The configured UserDetailsService is needed because + DigestProcessingFilter must have direct access to the clear text + password of a user. Digest Authentication will NOT work if you are using encoded + passwords in your DAO. The DAO collaborator, along with the + UserCache, are typically shared directly with a + DaoAuthenticationProvider. The + authenticationEntryPoint property must be + DigestProcessingFilterEntryPoint, so that + DigestProcessingFilter can obtain the correct + realmName and key for digest + calculations. + Like BasicAuthenticationFilter, if authentication is successful an + Authentication request token will be placed into the + SecurityContextHolder. If the authentication event was + successful, or authentication was not attempted because the HTTP header did not contain + a Digest Authentication request, the filter chain will continue as normal. The only time + the filter chain will be interrupted is if authentication fails and the + AuthenticationEntryPoint is called, as discussed in + the previous paragraph. + Digest Authentication's RFC offers a range of additional features to further increase + security. For example, the nonce can be changed on every request. Despite this, Spring + Security implementation was designed to minimise the complexity of the implementation + (and the doubtless user agent incompatibilities that would emerge), and avoid needing to + store server-side state. You are invited to review RFC 2617 if you wish to explore these + features in more detail. As far as we are aware, Spring Security's implementation does + comply with the minimum standards of this RFC. +
+
+ diff --git a/docs/manual/src/docbook/basic-authentication.xml b/docs/manual/src/docbook/basic-authentication.xml deleted file mode 100644 index 225f91725d..0000000000 --- a/docs/manual/src/docbook/basic-authentication.xml +++ /dev/null @@ -1,60 +0,0 @@ -BASIC Authentication Mechanism - - -
Overview - - - Spring Security provides a - BasicProcessingFilter which is capable of - processing basic authentication credentials presented in HTTP headers. - This can be used for authenticating calls made by Spring remoting - protocols (such as Hessian and Burlap), as well as normal user agents - (such as Internet Explorer and Navigator). The standard governing HTTP - Basic Authentication is defined by RFC 1945, Section 11, and the - BasicProcessingFilter conforms with this RFC. Basic - Authentication is an attractive approach to authentication, because it - is very widely deployed in user agents and implementation is extremely - simple (it's just a Base64 encoding of the username:password, - specified in an HTTP header). -
- -
Configuration - - - To implement HTTP Basic Authentication, it is necessary to - define BasicProcessingFilter in the filter chain. - The application context will need to define the - BasicProcessingFilter and its required - collaborator: - - - - - - - - -]]> - - - The configured AuthenticationManager - processes each authentication request. If authentication fails, the - configured AuthenticationEntryPoint will be used to - retry the authentication process. Usually you will use the - BasicProcessingFilterEntryPoint, which returns a - 401 response with a suitable header to retry HTTP Basic - authentication. If authentication is successful, the resulting - Authentication object will be placed into the - SecurityContextHolder. - - If the authentication event was successful, or authentication - was not attempted because the HTTP header did not contain a supported - authentication request, the filter chain will continue as normal. The - only time the filter chain will be interrupted is if authentication - fails and the AuthenticationEntryPoint is called, - as discussed in the previous paragraph -
- \ No newline at end of file diff --git a/docs/manual/src/docbook/common-auth-services.xml b/docs/manual/src/docbook/common-auth-services.xml deleted file mode 100644 index 9007a578a4..0000000000 --- a/docs/manual/src/docbook/common-auth-services.xml +++ /dev/null @@ -1,347 +0,0 @@ - - - Common Authentication Services - -
- - Mechanisms, Providers and Entry Points - - To use Spring Security's authentication services, you'll usually need to configure a web - filter, together with an AuthenticationProvider and - AuthenticationEntryPoint. In this section we are going to - explore an example application that needs to support both form-based authentication (so a nice - HTML page is presented to a user for them to login) and BASIC authentication (so a web service - or similar can access protected resources). - The filter-chain-map syntax from the security namespace allows you to - define the mapping from URLs to filter chains, using a sequence of - filter-chain child elements. Each of these defines a set of URLs using - the pattern attribute and a chain of filters using the - filters attribute.What's important to note at this stage is that a series - of filters will be run - in the order specified by the declaration - and each of those filters - are actually the id of another bean in the application context. So, in our - case some extra beans will also appear in the application context, and they'll be named - httpSessionContextIntegrationFilter, logoutFilter and - so on. The order that the filters should appear is discussed in the filters section of the - reference guide - although they are correct in the above example. - In our example we have the - UsernamePasswordAuthenticationProcessingFilter and - BasicProcessingFilter being used. These are the "authentication - mechanisms" that respond to form-based authentication and BASIC HTTP header-based - authentication respectively (we discussed the role of authentication mechanisms earlier in - this reference guide). If you weren't using form or BASIC authentication, neither of these - beans would be defined. You'd instead define filters applicable to your desired authentication - environment, such as DigestProcessingFilter or - CasProcessingFilter. Refer to the individual chapters of this part of the - reference guide to learn how to configure each of these authentication mechanisms. - Recall that HttpSessionContextIntegrationFilter keeps the contents - of the SecurityContext between invocations inside an HTTP - session. This means the authentication mechanisms are only used once, being when the principal - initially tries to authenticate. The rest of the time the authentication mechanisms sit there - and silently pass the request through to the next filter in the chain. That is a practical - requirement due to the fact that few authentication approaches present credentials on each and - every call (BASIC authentication being a notable exception), but what happens if a principal's - account gets cancelled or disabled or otherwise changed (eg an increase or decrease in - GrantedAuthority[]s) after the initial authentication step? Let's look at - how that is handled now. - The major authorization provider for secure objects has previously been introduced as - AbstractSecurityInterceptor. This class needs to have access to an - AuthenticationManager. It also has configurable settings to - indicate whether an Authentication object should be - re-authenticated on each secure object invocation. By default it just accepts any - Authentication inside the - SecurityContextHolder is authenticated if - Authentication.isAuthenticated() returns true. This is great for - performance, but not ideal if you want to ensure up-to-the-moment authentication validity. For - such cases you'll probably want to set the - AbstractSecurityInterceptor.alwaysReauthenticate property to true. - You might be asking yourself, "what's this - AuthenticationManager?". We haven't explored it before, but - we have discussed the concept of an AuthenticationProvider. Quite - simply, an AuthenticationManager is responsible for passing - requests through a chain of AuthenticationProviders. It's a little like the filter chain we - discussed earlier, although there are some differences. There is only one - AuthenticationManager implementation shipped with Spring - Security, so let's look at how it's configured for the example we're using in this - chapter: - - - - - - - - - -]]> - - It's probably worth mentioning at this point that your authentication mechanisms (which - are usually filters) are also injected with a reference to the - AuthenticationManager. So both - AbstractSecurityInterceptor as well as the authentication mechanisms - will use the above ProviderManager to poll a list of - AuthenticationProviders. - In our example we have three providers. They are tried in the order shown (which is - implied by the use of a List instead of a Set), with - each provider able to attempt authentication, or skip authentication by simply returning - null. If all implementations return null, the - ProviderManager will throw a suitable exception. If you're interested in - learning more about chaining providers, please refer to the ProviderManager - JavaDocs. - The providers to use will sometimes be interchangeable with the authentication mechanisms, - whilst at other times they will depend on a specific authentication mechanism. For example, - the DaoAuthenticationProvider just needs a string-based username and - password. Various authentication mechanisms result in the collection of a string-based - username and password, including (but not limited to) BASIC and form authentication. Equally, - some authentication mechanisms create an authentication request object which can only be - interpreted by a single type of AuthenticationProvider. An example of - this one-to-one mapping would be JA-SIG CAS, which uses the notion of a service ticket which - can therefore only be authenticated by CasAuthenticationProvider. A further - example of a one-to-one mapping would be the LDAP authentication mechanism, which can only be - processed an the LdapAuthenticationProvider. The specifics of such - relationships are detailed in the JavaDocs for each class, plus the authentication - approach-specific chapters of this reference guide. You need not be terribly concerned about - this implementation detail, because if you forget to register a suitable provider, you'll - simply receive a ProviderNotFoundException when an attempt to authenticate - is made. - After configuring the correct authentication mechanisms in the - FilterChainProxy, and ensuring that a corresponding - AuthenticationProvider is registered in the - ProviderManager, your last step is to configure an - AuthenticationEntryPoint. Recall that earlier we discussed - the role of ExceptionTranslationFilter, which is used when HTTP-based - requests should receive back an HTTP header or HTTP redirect in order to start authentication. - Continuing on with our earlier example: - - - - - - - - - - - - - -]]> - - Notice that the ExceptionTranslationFilter requires two - collaborators. The first, AccessDeniedHandlerImpl, uses a - RequestDispatcher forward to display the specified access denied error - page. We use a forward so that the SecurityContextHolder still contains - details of the principal, which may be useful for display to the user (in old releases of - Spring Security we relied upon the servlet container to handle a 403 error message, which - lacked this useful contextual information). AccessDeniedHandlerImpl will - also set the HTTP header to 403, which is the official error code to indicate access denied. - In the case of the AuthentionEntryPoint, here we're setting what action we - would like taken when an unauthenticated principal attempts to perform a protected operation. - Because in our example we're going to be using form-based authentication, we specify - AuthenticationProcessinFilterEntryPoint and the URL of the login page. - Your application will usually only have one entry point, and most authentication approaches - define their own specific AuthenticationEntryPoint. Details of - which entry point to use for each authentication approach is discussed in the authentication - approach-specific chapters of this reference guide. -
-
- - UserDetails and Associated Types - - As mentioned in the first part of the reference guide, most authentication providers take - advantage of the UserDetails and - UserDetailsService interfaces. The contract for this latter - interface consists of a single method: - - - UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException; - - - The returned UserDetails is an interface that provides - getters that guarantee non-null provision of basic authentication information such as the - username, password, granted authorities and whether the user is enabled or disabled. Most - authentication providers will use a UserDetailsService, even if - the username and password are not actually used as part of the authentication decision. - Generally such providers will be using the returned UserDetails - object just for its GrantedAuthority[] information, because some other - system (like LDAP or X509 or CAS etc) has undertaken the responsibility of actually validating - the credentials. - A single concrete implementation of UserDetails is provided - with Spring Security, being the User class. Spring Security users will need - to decide when writing their UserDetailsService what concrete - UserDetails class to return. In most cases - User will be used directly or subclassed, although special circumstances - (such as object relational mappers) may require users to write their own - UserDetails implementation from scratch. This is not such an - unusual situation, and users should not hesitate to simply return their normal domain object - that represents a user of the system. This is especially common given that - UserDetails is often used to store additional - principal-related properties (such as their telephone number and email address), so that they - can be easily used by web views. - Given UserDetailsService is so simple to implement, it - should be easy for users to retrieve authentication information using a persistence strategy - of their choice. Having said that, Spring Security does include a couple of useful base - implementations, which we'll look at below. -
- - In-Memory Authentication - - Whilst it is easy to use create a custom - UserDetailsService implementation that extracts information - from a persistence engine of choice, many applications do not require such complexity. This - is particularly true if you're undertaking a rapid prototype or just starting integrating - Spring Security, when you don't really want to spend time configuring databases or writing - UserDetailsService implementations. For this sort of - situation, a simple option is to use the user-service element from the - security namespace: - - - - ]]> - This also suppots the use of an external properties file: - ]]> The properties file should contain entries in the form - - username=password,grantedAuthority[,grantedAuthority][,enabled|disabled] - - For example - - jimi=jimispassword,ROLE_USER,ROLE_ADMIN,enabled - bob=bobspassword,ROLE_USER,enabled - -
-
- - JDBC Authentication - - Spring Security also includes a UserDetailsService that - can obtain authentication information from a JDBC data source. Internally Spring JDBC is - used, so it avoids the complexity of a fully-featured object relational mapper (ORM) just to - store user details. If your application does use an ORM tool, you might prefer to write a - custom UserDetailsService to reuse the mapping files you've - probably already created. Returning to JdbcDaoImpl, an example - configuration is shown below: - - - - - - - - - - - - ]]> - - You can use different relational database management systems by modifying the - DriverManagerDataSource shown above. You can also use a global data - source obtained from JNDI, as per normal Spring options. -
- Default User Database Schema - Irrespective of the database you are using and how a DataSource is - obtained, a standard schema must be in place. The DDL for an HSQL database instance would - be: - - CREATE TABLE users ( - username VARCHAR(50) NOT NULL PRIMARY KEY, - password VARCHAR(50) NOT NULL, - enabled BIT NOT NULL - ); - - CREATE TABLE authorities ( - username VARCHAR(50) NOT NULL, - authority VARCHAR(50) NOT NULL - ); - - ALTER TABLE authorities ADD CONSTRAINT fk_authorities_users \ - foreign key (username) REFERENCES users(username); - - If the default schema is unsuitable for your needs, JdbcDaoImpl - provides properties that allow customisation of the SQL statements. Please refer to the - JavaDocs for details, but note that the class is not intended for complex custom - subclasses. If you have a complex schema or would like a custom - UserDetails implementation returned, you'd be better off - writing your own UserDetailsService. The base - implementation provided with Spring Security is intended for typical situations, rather - than catering for all possible requirements. -
-
-
-
- - Concurrent Session Handling - - Spring Security is able to prevent a principal from concurrently authenticating to the - same application more than a specified number of times. Many ISVs take advantage of this to - enforce licensing, whilst network administrators like this feature because it helps prevent - people from sharing login names. You can, for example, stop user "Batman" from logging onto - the web application from two different sessions. - To use concurrent session support, you'll need to add the following to - web.xml: - - org.springframework.security.web.session.HttpSessionEventPublisher - - ]]> - - In addition, you will need to add the - org.springframework.security.web.authentication.concurrent.ConcurrentSessionFilter - to your FilterChainProxy. The - ConcurrentSessionFilter requires two properties, - sessionRegistry, which generally points to an instance of - SessionRegistryImpl, and expiredUrl, which points to - the page to display when a session has expired. - The web.xml - HttpSessionEventPublisher causes an ApplicationEvent to - be published to the Spring ApplicationContext every time a - HttpSession commences or terminates. This is critical, as it allows the - SessionRegistryImpl to be notified when a session ends. - You will also need to wire up the ConcurrentSessionControllerImpl - and refer to it from your ProviderManager bean: - - - - - - - - - - - - - - -]]> - -
-
- - Authentication Tag Libraries - - AuthenticationTag is used to simply output a property of the current - Authentication object to the web page. - The following JSP fragment illustrates how to use the - AuthenticationTag: - - <security:authentication property="principal.username"/> - - This tag would cause the principal's name to be output. Here we are assuming the - Authentication.getPrincipal() is a - UserDetails object, which is generally the case when using - one of Spring Security's stadard AuthenticationProvider - implementations. -
- diff --git a/docs/manual/src/docbook/digest-authentication.xml b/docs/manual/src/docbook/digest-authentication.xml deleted file mode 100644 index fa80d9df49..0000000000 --- a/docs/manual/src/docbook/digest-authentication.xml +++ /dev/null @@ -1,144 +0,0 @@ -Digest Authentication - - -
Overview - - - Spring Security provides a - DigestProcessingFilter which is capable of - processing digest authentication credentials presented in HTTP - headers. Digest Authentication attempts to solve many of the - weaknesses of Basic authentication, specifically by ensuring - credentials are never sent in clear text across the wire. Many user - agents support Digest Authentication, including FireFox and Internet - Explorer. The standard governing HTTP Digest Authentication is defined - by RFC 2617, which updates an earlier version of the Digest - Authentication standard prescribed by RFC 2069. Most user agents - implement RFC 2617. Spring Security - DigestProcessingFilter is compatible with the - "auth" quality of protection - (qop) prescribed by RFC 2617, which also provides - backward compatibility with RFC 2069. Digest Authentication is a - highly attractive option if you need to use unencrypted HTTP (ie no - TLS/HTTPS) and wish to maximise security of the authentication - process. Indeed Digest Authentication is a mandatory requirement for - the WebDAV protocol, as noted by RFC 2518 Section 17.1, so we should - expect to see it increasingly deployed and replacing Basic - Authentication. - - Digest Authentication is definitely the most secure choice - between Form Authentication, Basic Authentication and Digest - Authentication, although extra security also means more complex user - agent implementations. Central to Digest Authentication is a "nonce". - This is a value the server generates. Spring Security's nonce adopts - the following format: - - - base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key)) - - expirationTime: The date and time when the nonce expires, expressed in milliseconds - key: A private key to prevent modification of the nonce token - - - The DigestProcessingFilterEntryPoint has a - property specifying the key used for generating the - nonce tokens, along with a nonceValiditySeconds - property for determining the expiration time (default 300, which - equals five minutes). Whist ever the nonce is valid, the digest is - computed by concatenating various strings including the username, - password, nonce, URI being requested, a client-generated nonce (merely - a random value which the user agent generates each request), the realm - name etc, then performing an MD5 hash. Both the server and user agent - perform this digest computation, resulting in different hash codes if - they disagree on an included value (eg password). In Spring Security - implementation, if the server-generated nonce has merely expired (but - the digest was otherwise valid), the - DigestProcessingFilterEntryPoint will send a - "stale=true" header. This tells the user agent - there is no need to disturb the user (as the password and username etc - is correct), but simply to try again using a new nonce. - - An appropriate value for - DigestProcessingFilterEntryPoint's - nonceValiditySeconds parameter will depend on your - application. Extremely secure applications should note that an - intercepted authentication header can be used to impersonate the - principal until the expirationTime contained in the - nonce is reached. This is the key principle when selecting an - appropriate setting, but it would be unusual for immensely secure - applications to not be running over TLS/HTTPS in the first - instance. - - Because of the more complex implementation of Digest - Authentication, there are often user agent issues. For example, - Internet Explorer fails to present an "opaque" - token on subsequent requests in the same session. Spring Security - filters therefore encapsulate all state information into the - "nonce" token instead. In our testing, Spring - Security implementation works reliably with FireFox and Internet - Explorer, correctly handling nonce timeouts etc. -
- -
Configuration - - - Now that we've reviewed the theory, let's see how to use it. To - implement HTTP Digest Authentication, it is necessary to define - DigestProcessingFilter in the fitler chain. The - application context will need to define the - DigestProcessingFilter and its required - collaborators: - - - - - - - - - - - - -]]> - - - - The configured UserDetailsService is needed - because DigestProcessingFilter must have direct - access to the clear text password of a user. Digest Authentication - will NOT work if you are using encoded passwords in your DAO. The DAO - collaborator, along with the UserCache, are - typically shared directly with a - DaoAuthenticationProvider. The - authenticationEntryPoint property must be - DigestProcessingFilterEntryPoint, so that - DigestProcessingFilter can obtain the correct - realmName and key for digest - calculations. - - Like BasicAuthenticationFilter, if - authentication is successful an Authentication - request token will be placed into the - SecurityContextHolder. If the authentication event - was successful, or authentication was not attempted because the HTTP - header did not contain a Digest Authentication request, the filter - chain will continue as normal. The only time the filter chain will be - interrupted is if authentication fails and the - AuthenticationEntryPoint is called, as discussed in - the previous paragraph. - - Digest Authentication's RFC offers a range of additional - features to further increase security. For example, the nonce can be - changed on every request. Despite this, Spring Security implementation - was designed to minimise the complexity of the implementation (and the - doubtless user agent incompatibilities that would emerge), and avoid - needing to store server-side state. You are invited to review RFC 2617 - if you wish to explore these features in more detail. As far as we are - aware, Spring Security's implementation does comply with the minimum - standards of this RFC. -
- \ No newline at end of file diff --git a/docs/manual/src/docbook/form-authentication.xml b/docs/manual/src/docbook/form-authentication.xml index 99e5edcc97..ed71e31d1e 100644 --- a/docs/manual/src/docbook/form-authentication.xml +++ b/docs/manual/src/docbook/form-authentication.xml @@ -63,7 +63,5 @@ If authentication fails, the configured AuthenticationFailureHandler will be invoked. - -
\ No newline at end of file diff --git a/docs/manual/src/docbook/secured-objects.xml b/docs/manual/src/docbook/secured-objects.xml index f7e2381ebe..b324050754 100644 --- a/docs/manual/src/docbook/secured-objects.xml +++ b/docs/manual/src/docbook/secured-objects.xml @@ -145,121 +145,4 @@ public void afterPropertiesSet() throws Exception { whatever means you think fit (eg new Person();) and they will have the security interceptor applied. -
- - FilterInvocation Security Interceptor - - To secure FilterInvocations, developers need to add a - FilterSecurityInterceptor to their filter chain. A typical - configuration example is provided below: - In the application context you will need to configure three beans: - - - - - - - - - - - - - - - - - - - -]]> - The ExceptionTranslationFilter provides the bridge between Java - exceptions and HTTP responses. It is solely concerned with maintaining the user interface. - This filter does not do any actual security enforcement. If an - AuthenticationException is detected, the filter will call the - AuthenticationEntryPoint to commence the authentication process (e.g. a user login). - The AuthenticationEntryPoint will be called if the user - requests a secure HTTP resource but they are not authenticated. The class handles presenting - the appropriate response to the user so that authentication can begin. Three concrete - implementations are provided with Spring Security: - LoginUrlAuthenticationEntryPoint for commencing a form-based - authentication, BasicProcessingFilterEntryPoint for commencing a HTTP Basic - authentication process, and CasProcessingFilterEntryPoint for commencing a - JA-SIG Central Authentication Service (CAS) login. The - LoginUrlAuthenticationEntryPoint and - CasProcessingFilterEntryPoint have optional properties related to forcing - the use of HTTPS, so please refer to the JavaDocs if you require this. - FilterSecurityInterceptor is responsible for handling the security - of HTTP resources. Like any other security interceptor, it requires a reference to an - AuthenticationManager and an - AccessDecisionManager, which are both discussed in separate - sections below. The FilterSecurityInterceptor is also configured with - configuration attributes that apply to different HTTP URL requests. A full discussion of - configuration attributes is provided in the High Level Design section of this document. - The FilterSecurityInterceptor can be configured with configuration - attributes in two ways. The first, which is shown above, is using the - <filter-security-metadata-source> namespace element. This is - similar to the <filter-chain-map> used to configure a - FilterChainProxy but the <intercept-url> - child elements only use the pattern and access - attributes. The second is by writing your own - SecurityMetadataSource, although this is beyond the scope of - this document. Irrespective of the approach used, the - SecurityMetadataSource is responsible for returning a - List<ConfigAttribute> containing all of the configuration - attributes associated with a single secure HTTP URL. - It should be noted that the - FilterSecurityInterceptor.setSecurityMetadataSource() method actually - expects an instance of FilterInvocationDefinitionSource. This - is a marker interface which subclasses SecurityMetadataSource. - It simply denotes the SecurityMetadataSource understands - FilterInvocations. In the interests of simplicity we'll continue to - refer to the FilterInvocationDefinitionSource as an - SecurityMetadataSource, as the distinction is of little - relevance to most users of the FilterSecurityInterceptor. - When using the namespace option to configure the interceptor, commas are used to delimit - the different configuration attributes that apply to each HTTP URL. Each configuration - attribute is assigned into its own SecurityConfig object. The - SecurityConfig object is discussed in the High Level Design section. The - SecurityMetadataSource created by the property editor, - FilterInvocationDefinitionSource, matches configuration - attributes against FilterInvocations based on expression evaluation of the - request URL. Two standard expression syntaxes are supported. The default is to treat all - expressions as Apache Ant paths and regular expressions are also supported for ore complex - cases. The path-type attribute is used to specify the type of pattern being - used. It is not possible to mix expression syntaxes within the same definition. For example, - the previous configuration using regular expressions instead of Ant paths would be written as - follows: - - - - - - - - - - -]]> - Irrespective of the type of expression syntax used, expressions are always evaluated in - the order they are defined. Thus it is important that more specific expressions are defined - higher in the list than less specific expressions. This is reflected in our example above, - where the more specific /secure/super/ pattern appears higher than the less - specific /secure/ pattern. If they were reversed, the - /secure/ pattern would always match and the - /secure/super/ pattern would never be evaluated. - As with other security interceptors, the validateConfigAttributes - property is observed. When set to true (the default), at startup time the - FilterSecurityInterceptor will evaluate if the provided configuration - attributes are valid. It does this by checking each configuration attribute can be processed - by either the AccessDecisionManager or the - RunAsManager. If neither of these can process a given configuration - attribute, an exception is thrown. -
diff --git a/docs/manual/src/docbook/security-filter-chain.xml b/docs/manual/src/docbook/security-filter-chain.xml new file mode 100644 index 0000000000..cc5e28e3bd --- /dev/null +++ b/docs/manual/src/docbook/security-filter-chain.xml @@ -0,0 +1,226 @@ + + + The Security Filter Chain + + Spring Security's web infrastructure is based entirely on standard servlet filters. It + doesn't use servlets or any other servlet-based frameworks (such as Spring MVC) internally, so + it has no strong links to any particular web technology. It deals in + HttpServletRequests and HttpServletResponses + and doesn't care whether the requests come from a browser, a web service client, an + HttpInvoker or an AJAX application. + Spring Security maintains a filter chain internally where each of the filters has a + particular responsibility and filters are added or removed from the configuration depending on + which services are required. The ordering of the filters is important as there are + dependencies between them. If you have been using namespace + configuration, then the filters are automatically configured for you and you don't + have to define any Spring beans explicitly but here may be times when you want full control + over the security filter chain, either because you are using features which aren't supported + in the namespace, or you are using your own customized versions of classes. +
+ <classname>DelegatingFilterProxy</classname> + When using servlet filters, you obviously need to declare them in your + web.xml, or they will be ignored by the servlet container. In Spring + Security, the filter classes are also Spring beans defined in the application context and + thus able to take advantage of Spring's rich dependency-injection facilities and lifecycle + interfaces. Spring's DelegatingFilterProxy provides the link between + web.xml and the application context. + When using DelegatingFilterProxy, you will see something like + this in the web.xml file: + myFilter + org.springframework.web.filter.DelegatingFilterProxy + + + + myFilter + /* + ]]> + Notice that the filter is actually a + DelegatingFilterProxy, and not the class that will actually implement + the logic of the filter. What DelegatingFilterProxy does is delegate + the Filter's methods through to a bean which is obtained from + the Spring application context. This enables the bean to benefit from the Spring web + application context lifecycle support and configuration flexibility. The bean must implement + javax.servlet.Filter and it must have the same name as that + in the filter-name element. Read the Javadoc for + DelegatingFilterProxy for more information +
+
+ <classname>FilterChainProxy</classname> + It should now be clear that you can declare each Spring Security filter bean that you + require in your application context file and add a corresponding + DelegatingFilterProxy entry to web.xml for + each filter, making sure that they are ordered correctly. This is a cumbersome approach and + clutters up the web.xml file quickly if we have a lot of filters. We + would prefer to just add a single entry to web.xml and deal entirely + with the application context file for managing our web security beans. This is where Spring + Secuiryt's FilterChainProxy comes in. It is wired using a + DelegatingFilterProxy, just like in the example above, but with the + filter-name set to the bean name filterChainProxy. The + filter chain is then declared in the application context with the same bean name. Here's an + example: + + + + + +]]> + The namespace element filter-chain-map is + used to set up the security filter chain(s) which are required within the application + Note that you'll need to include the security namespace in your application context + XML file in order to use this syntax. + . It maps a particular URL pattern to a chain of filters built up from the bean + names specified in the filters element. Both regular expressions and Ant + Paths are supported, and the most specific URIs appear first. At runtime the + FilterChainProxy will locate the first URI pattern that matches the + current web request and the list of filter beans specified by the filters + attribute will be applied to that request. The filters will be invoked in the order they are + defined, so you have complete control over the filter chain which is applied to a particular + URL. + You may have noticed we have declared two + SecurityContextPersistenceFilters in the filter chain + (ASC is short for allowSessionCreation, a property + of SecurityContextPersistenceFilter). As web services will never + present a jsessionid on future requests, creating + HttpSessions for such user agents would be wasteful. If you had a + high-volume application which required maximum scalability, we recommend you use the + approach shown above. For smaller applications, using a single + SecurityContextPersistenceFilter (with its default + allowSessionCreation as true) would likely be + sufficient. + In relation to lifecycle issues, the FilterChainProxy will always + delegate init(FilterConfig) and destroy() + methods through to the underlaying Filters if such methods + are called against FilterChainProxy itself. In this case, + FilterChainProxy guarantees to only initialize and destroy each + Filter bean once, no matter how many times it is declared in the filter + chain(s). You control the overall choice as to whether these methods are called or not via + the targetFilterLifecycle initialization parameter of + DelegatingFilterProxy. By default this property is + false and servlet container lifecycle invocations are not delegated + through DelegatingFilterProxy. + When we looked at how to set up web security using namespace configuration, we used a + DelegatingFilterProxy with the name + springSecurityFilterChain. You should now be able to see that this is the + name of the FilterChainProxy which is created by the namespace. +
+ Bypassing the Filter Chain + As with the namespace, you can use the attribute filters = "none" + as an alternative to supplying a filter bean list. This will omit the request pattern from + the security filter chain entirely. Note that anything matching this path will then have + no authentication or authorization services applied and will be freely accessible. If you + want to make use of the contents of the SecurityContext contents + during a request, then it must have passed through the security filter chain. Otherwise + the SecurityContextHolder will not have been populated and the + contents will be null. +
+
+
+ Filter Ordering + The order that filters are defined in the chain is very important. Irrespective of which + filters you are actually using, the order should be as follows: + + + ChannelProcessingFilter, because it might need to redirect + to a different protocol + + + ConcurrentSessionFilter, because it doesn't use any + SecurityContextHolder functionality but needs to update the + SessionRegistry to reflect ongoing requests from the + principal + + + SecurityContextPersistenceFilter, so a + SecurityContext can be set up in the + SecurityContextHolder at the beginning of a web request, and + any changes to the SecurityContext can be copied to the + HttpSession when the web request ends (ready for use with the + next web request) + + + Authentication processing mechanisms - + UsernamePasswordAuthenticationProcessingFilter, + CasProcessingFilter, + BasicProcessingFilter etc - so that the + SecurityContextHolder can be modified to contain a valid + Authentication request token + + + The SecurityContextHolderAwareRequestFilter, if you are using + it to install a Spring Security aware HttpServletRequestWrapper + into your servlet container + + + RememberMeProcessingFilter, so that if no earlier + authentication processing mechanism updated the + SecurityContextHolder, and the request presents a cookie that + enables remember-me services to take place, a suitable remembered + Authentication object will be put there + + + AnonymousProcessingFilter, so that if no earlier + authentication processing mechanism updated the + SecurityContextHolder, an anonymous + Authentication object will be put there + + + ExceptionTranslationFilter, to catch any Spring Security + exceptions so that either an HTTP error response can be returned or an appropriate + AuthenticationEntryPoint can be launched + + + FilterSecurityInterceptor, to protect web URIs and raise + exceptions when access is denied + + +
+
+ Use with other Filter-Based Frameworks + If you're using some other framework that is also filter-based, then you need to make + sure that the Spring Security filters come first. This enables the + SecurityContextHolder to be populated in time for use by the other + filters. Examples are the use of SiteMesh to decorate your web pages or a web framework like + Wicket which uses a filter to handle its requests. +
+ + diff --git a/docs/manual/src/docbook/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml index 69e8594907..d4f1ce85e9 100644 --- a/docs/manual/src/docbook/springsecurity.xml +++ b/docs/manual/src/docbook/springsecurity.xml @@ -97,7 +97,24 @@ Security. - + + + + Web Application Security + + Most Spring Security users will be using the framework in applications which make user + of HTTP and the Servlet API. In this part, we'll take a look at how Spring Security provides + authentication and access-control features for the web layer of an application. We'll look + behind the facade of the namespace and see which classes and interfaces are actually + assembled to provide web-layer security. In some situations it is necessary to use + traditional bean configuration to provide full control over the configuration, so we'll also + see how to configure these classes directly without the namespace. + + + + + + Authentication @@ -120,12 +137,7 @@ the project web site. . - - - - - @@ -145,24 +157,21 @@ - Advanced Topics - - - In this part we cover some of the more advanced features of the framework. - + + In this part we cover some of the more advanced features of the framework. - + - + - - + + diff --git a/docs/manual/src/docbook/technical-overview.xml b/docs/manual/src/docbook/technical-overview.xml index 5e7c4a8224..e3f393cbe8 100644 --- a/docs/manual/src/docbook/technical-overview.xml +++ b/docs/manual/src/docbook/technical-overview.xml @@ -108,8 +108,8 @@ if (principal instanceof UserDetails) { required. On successful authentication, UserDetails is used to build the Authentication object that is stored in the - SecurityContextHolder (more on this in below). The good news is that we provide a + SecurityContextHolder (more on this below). The good news is that we provide a number of UserDetailsService implementations, including one that uses an in-memory map (InMemoryDaoImpl) and another that uses JDBC (JdbcDaoImpl). Most users tend to write their own, @@ -321,33 +321,14 @@ Successfully authenticated. Security context contains: \ (or equivalent) that reads the third-party user information from a location, build a Spring Security-specific Authentication object, and put it onto the SecurityContextHolder. + + If you're wondering how the AuthenticationManager + manager is implemented in a real world example, we'll look at that in + -
- The <interfacename>AuthenticationManager</interfacename> - The AuthenticationManager is just an interface, so the - implementation can be anything we choose, but how does it work in practice. What if we need - to check multiple authentication databases? The default implementation in Spring Security is - called ProviderManager and rather than handling the authentication - request itself, it delegates to a list of configured - AuthenticationProviders, each of which is queried in turn to see if - it can perform the authentication. Each provider will either throw an exception or return a - fully populated Authentication object. Remember our good - friends, UserDetails and - UserDetailsService? If not, head back to the previous - section and refresh your memory. The most common approach to verifying an authentication - request is to load the corresponding UserDetails and check - the loaded password against the one that has been entered by the user. This is the approach - used by the DaoAuthenticationProvider, which is most commonly used to - wrap a UserDetailsService to implement an - AuthenticationProvider. The loaded - UserDetails object - and particularly the - GrantedAuthoritys it contains - will be used when building the fully - populated Authentication object which is returned from a - successful authentication and stored in the SecurityContext. -
-
+
Authentication in a Web Application Now let's explore the situation where you are using Spring Security in a web application (without web.xml security enabled). How is a user authenticated and the @@ -410,7 +391,7 @@ Successfully authenticated. Security context contains: \ AuthenticationEntryPoint (if the principal has not been authenticated and therefore we need to go commence step three).
-
+
AuthenticationEntryPoint The AuthenticationEntryPoint is responsible for step three in the above list. As you can imagine, each web application will have a default @@ -438,7 +419,7 @@ Successfully authenticated. Security context contains: \ rejected the request, the authentication mechanism will ask the user agent to retry (step two above).
-
+
Storing the <interfacename>SecurityContext</interfacename> between requests Depending on the type of application, there may need to be a strategy in place to store the security context between user operations. In a typical web application, a user logs in diff --git a/docs/manual/src/docbook/web-infrastructure.xml b/docs/manual/src/docbook/web-infrastructure.xml deleted file mode 100644 index 001230582e..0000000000 --- a/docs/manual/src/docbook/web-infrastructure.xml +++ /dev/null @@ -1,236 +0,0 @@ - - - Web Application Infrastructure - - Most Spring Security users will be using the framework in applications which make user of - the HTTP and the Servlet API. In this and the following chapters, we'll take a look at how - Spring Security provides authentication and access-control features for the web layer of an - application. We'll look behind the facade of the namespace and see which classes and interfaces - are actually assembled to provide web-layer security. In some situations it is necessary to use - traditional bean configuration to provide full control over the configuration, so we'll also see - how to configure these classes directly without the namespace. -
- Security Filter - Spring Security's web infrastructure is based entirely on standard servlet filters. It - doesn't use servlets or any other servlet-based frameworks (such as Spring MVC) internally, so - it has no strong links to any particular web technology. It deals in - HttpServletRequests and HttpServletResponses - and doesn't care whether the requests come from a browser, a web service client, an - HttpInvoker or an AJAX application. - Spring Security maintains a filter chain internally where each of the filters has a - particular responsibility and filters are added or removed from the configuration depending on - which services are required. The ordering of the filters is important as there are - dependencies between them. If you have been using namespace - configuration, then the filters are automatically configured for you and you don't - have to define any Spring beans explicitly but here may be times when you want full control - over the security filter chain, either because you are using features which aren't supported - in the namespace, or you are using your own customized versions of classes. -
- <classname>DelegatingFilterProxy</classname> - When using servlet filters, you obviously need to declare them in your - web.xml, or they will be ignored by the servlet container. In Spring - Security, the filter classes are also Spring beans defined in the application context and - thus able to take advantage of Spring's rich dependency-injection facilities and lifecycle - interfaces. Spring's DelegatingFilterProxy provides the link between - web.xml and the application context. - When using DelegatingFilterProxy, you will see something like - this in the web.xml file: - myFilter - org.springframework.web.filter.DelegatingFilterProxy - - - - myFilter - /* - ]]> - Notice that the filter is actually a - DelegatingFilterProxy, and not the class that will actually implement - the logic of the filter. What DelegatingFilterProxy does is delegate - the Filter's methods through to a bean which is obtained from - the Spring application context. This enables the bean to benefit from the Spring web - application context lifecycle support and configuration flexibility. The bean must implement - javax.servlet.Filter and it must have the same name as that - in the filter-name element. Read the Javadoc for - DelegatingFilterProxy for more information -
-
- <classname>FilterChainProxy</classname> - It should now be clear that you can declare each Spring Security filter bean that you - require in your application context file and add a corresponding - DelegatingFilterProxy entry to web.xml for - each filter, making sure that they are ordered correctly. This is a cumbersome approach and - clutters up the web.xml file quickly if we have a lot of filters. We - would prefer to just add a single entry to web.xml and deal entirely - with the application context file for managing our web security beans. This is where Spring - Secuiryt's FilterChainProxy comes in. It is wired using a - DelegatingFilterProxy, just like in the example above, but with the - filter-name set to the bean name filterChainProxy. The - filter chain is then declared in the application context with the same bean name. Here's an - example: - - - - - -]]> - The namespace element filter-chain-map is - used to set up the security filter chain(s) which are required within the application - Note that you'll need to include the security namespace in your application context - XML file in order to use this syntax. - . It maps a particular URL pattern to a chain of filters built up from the bean - names specified in the filters element. Both regular expressions and Ant - Paths are supported, and the most specific URIs appear first. At runtime the - FilterChainProxy will locate the first URI pattern that matches the - current web request and the list of filter beans specified by the filters - attribute will be applied to that request. The filters will be invoked in the order they are - defined, so you have complete control over the filter chain which is applied to a particular - URL. - You may have noticed we have declared two - SecurityContextPersistenceFilters in the filter chain - (ASC is short for allowSessionCreation, a property - of SecurityContextPersistenceFilter). As web services will never - present a jsessionid on future requests, creating - HttpSessions for such user agents would be wasteful. If you had a - high-volume application which required maximum scalability, we recommend you use the - approach shown above. For smaller applications, using a single - SecurityContextPersistenceFilter (with its default - allowSessionCreation as true) would likely be - sufficient. - In relation to lifecycle issues, the FilterChainProxy will always - delegate init(FilterConfig) and destroy() - methods through to the underlaying Filters if such methods - are called against FilterChainProxy itself. In this case, - FilterChainProxy guarantees to only initialize and destroy each - Filter bean once, no matter how many times it is declared in the filter - chain(s). You control the overall choice as to whether these methods are called or not via - the targetFilterLifecycle initialization parameter of - DelegatingFilterProxy. By default this property is - false and servlet container lifecycle invocations are not delegated - through DelegatingFilterProxy. - When we looked at how to set up web security using namespace configuration, we used a - DelegatingFilterProxy with the name - springSecurityFilterChain. You should now be able to see that this is the - name of the FilterChainProxy which is created by the namespace. -
- Bypassing the Filter Chain - As with the namespace, you can use the attribute filters = "none" - as an alternative to supplying a filter bean list. This will omit the request pattern from - the security filter chain entirely. Note that anything matching this path will then have - no authentication or authorization services applied and will be freely accessible. If you - want to make use of the contents of the SecurityContext contents - during a request, then it must have passed through the security filter chain. Otherwise - the SecurityContextHolder will not have been populated and the - contents will be null. -
-
-
- Filter Ordering - The order that filters are defined in the chain is very important. Irrespective of which - filters you are actually using, the order should be as follows: - - ChannelProcessingFilter, because it might need to redirect - to a different protocol - - - ConcurrentSessionFilter, because it doesn't use any - SecurityContextHolder functionality but needs to update the - SessionRegistry to reflect ongoing requests from the - principal - - - SecurityContextPersistenceFilter, so a - SecurityContext can be set up in the - SecurityContextHolder at the beginning of a web request, and - any changes to the SecurityContext can be copied to the - HttpSession when the web request ends (ready for use with the - next web request) - - - Authentication processing mechanisms - - UsernamePasswordAuthenticationProcessingFilter, - CasProcessingFilter, - BasicProcessingFilter etc - so that the - SecurityContextHolder can be modified to contain a valid - Authentication request token - - - The SecurityContextHolderAwareRequestFilter, if you are using - it to install a Spring Security aware HttpServletRequestWrapper - into your servlet container - - - RememberMeProcessingFilter, so that if no earlier - authentication processing mechanism updated the - SecurityContextHolder, and the request presents a cookie that - enables remember-me services to take place, a suitable remembered - Authentication object will be put there - - - AnonymousProcessingFilter, so that if no earlier - authentication processing mechanism updated the - SecurityContextHolder, an anonymous - Authentication object will be put there - - - ExceptionTranslationFilter, to catch any Spring Security - exceptions so that either an HTTP error response can be returned or an appropriate - AuthenticationEntryPoint can be launched - - - FilterSecurityInterceptor, to protect web URIs and raise - exceptions when access is denied - - -
-
- Use with other Filter-Based Frameworks - If you're using some other framework that is also filter-based, then you need to make - sure that the Spring Security filters come first. This enables the - SecurityContextHolder to be populated in time for use by the other - filters. Examples are the use of SiteMesh to decorate your web pages or a web framework like - Wicket which uses a filter to handle its requests. -
-
- -