From 9bece3bc9a3bccb50753273c4684dc0971e5ee4b Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Wed, 7 Oct 2009 19:48:32 +0000 Subject: [PATCH] Ref manual updates and correction --- docs/manual/src/docbook/introduction.xml | 53 +++++++------ docs/manual/src/docbook/namespace-config.xml | 79 +++++++++++++------- docs/manual/src/docbook/springsecurity.xml | 53 +++++++------ 3 files changed, 105 insertions(+), 80 deletions(-) diff --git a/docs/manual/src/docbook/introduction.xml b/docs/manual/src/docbook/introduction.xml index 9032c6d5d7..de33f1d3ec 100644 --- a/docs/manual/src/docbook/introduction.xml +++ b/docs/manual/src/docbook/introduction.xml @@ -17,16 +17,19 @@ standards, it's important to recognise that they are not portable at a WAR or EAR level. Therefore, if you switch server environments, it is typically a lot of work to reconfigure your application's security in the new target environment. Using Spring - Security overcomes these problems, and also brings you dozens of other useful, entirely + Security overcomes these problems, and also brings you dozens of other useful, customisable security features. - As you probably know, security comprises two major operations. The first is known as - "authentication", which is the process of establishing a principal is who they claim to - be. A "principal" generally means a user, device or some other system which can perform - an action in your application. "Authorization" refers to the process of deciding whether - a principal is allowed to perform an action in your application. To arrive at the point - where an authorization decision is needed, the identity of the principal has already - been established by the authentication process. These concepts are common, and not at - all specific to Spring Security. + As you probably know two major areas of application security are + authentication and authorization (or + access-control). These are the the two main areas that Spring + Security targets. Authentication is the process of establishing a + principal is who they claim to be (a principal generally means a user, + device or some other system which can perform an action in your application). + Authorization refers to the process of deciding whether a principal + is allowed to perform an action within your application. To arrive at the point where an + authorization decision is needed, the identity of the principal has already been + established by the authentication process. These concepts are common, and not at all + specific to Spring Security. At an authentication level, Spring Security supports a wide range of authentication models. Most of these authentication models are either provided by third parties, or are developed by relevant standards bodies such as the Internet Engineering Task Force. In @@ -54,7 +57,8 @@ OpenID authentication - Computer Associates Siteminder + Authentication based on pre-established request headers (such as Computer + Associates Siteminder) JA-SIG Central Authentication Service (otherwise known as CAS, which is a @@ -80,8 +84,11 @@ Java Authentication and Authorization Service (JAAS) - Container integration with JBoss, Jetty, Resin and Tomcat (so you can still - use Container Manager Authentication if desired) + JEE container autentication (so you can still use Container Managed + Authentication if desired) + + + Kerberos Java Open Source Single Sign On (JOSSO) * @@ -142,20 +149,18 @@ differentiate security based on the way a principal is interacting with your application. For example, you might want to ensure requests only arrive over HTTPS, in order to protect passwords from eavesdropping or end users from man-in-the-middle - attacks. Or, you might want to ensure that an actual human being is making the requests - and not some robot or other automated process. This is especially helpful to protect - password recovery processes from brute force attacks, or simply to make it harder for - people to duplicate your application's key content. To help you achieve these goals, - Spring Security fully supports automatic "channel security", together with JCaptcha - integration for human user detection. + attacks. This is especially helpful to protect password recovery processes from brute + force attacks, or simply to make it harder for people to duplicate your application's + key content. To help you achieve these goals, Spring Security fully supports automatic + "channel security", together with JCaptcha integration for human user detection. Irrespective of how authentication was undertaken, Spring Security provides a deep set of authorization capabilities. There are three main areas of interest in respect of - authorization, these being authorizing web requests, authorizing methods can be invoked, - and authorizing access to individual domain object instances. To help you understand the - differences, consider the authorization capabilities found in the Servlet Specification - web pattern security, EJB Container Managed Security and file system security - respectively. Spring Security provides deep capabilities in all of these important - areas, which we'll explore later in this reference guide. + authorization, these being authorizing web requests, authorizing whether methods can be + invoked, and authorizing access to individual domain object instances. To help you + understand the differences, consider the authorization capabilities found in the Servlet + Specification web pattern security, EJB Container Managed Security and file system + security respectively. Spring Security provides deep capabilities in all of these + important areas, which we'll explore later in this reference guide. History diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index dd2f2c003b..fdbdeb35b5 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -21,9 +21,9 @@ ]]> This is much simpler than wiring up the equivalent Apache Directory Server beans. The most common alternative configuration requirements are supported by attributes on the ldap-server element and the user is isolated from worrying about which - beans they need to be set on and what the bean property names are. You can - find out more about the use of the ldap-server element in the chapter - on LDAP.. Use of a good XML editor while + beans they need create and what the bean property names are. You can find out + more about the use of the ldap-server element in the chapter on LDAP.. Use of a good XML editor while editing the application context file should provide information on the attributes and elements that are available. We would recommend that you try out the SpringSource Tool Suite as it @@ -42,7 +42,7 @@ ]]> In many of the examples you will see (and in the sample) applications, we will often use "security" as the default namespace rather than "beans", which means we can - omit the prefix on all the security namespace elements, making the context easier to read. You + omit the prefix on all the security namespace elements, making the content easier to read. You may also want to do this if you have your application context divided up into separate files and have most of your security configuration in one of them. Your security application context file would then start like this authentication-manager element, which creates a ProviderManager and registers the authentication providers with it. You can find more detailed information on the beans that are created in - the namespace appendix. + the namespace appendix. It's worth + cross-checking this if you want to start understanding what the important classes in the + framework are and how they are used, particularly if you want to customise things + later. The configuration above defines two users, their passwords and their roles within the application (which will be used for access control). It is also possible to load user information from a standard properties file using the properties attribute on user-service. See the section on in-memory authentication for more - details. Using the <authentication-provider> element means that the - user information will be used by the authentication manager to process authentication - requests. + details on the file format. Using the <authentication-provider> + element means that the user information will be used by the authentication manager to + process authentication requests. You can have multiple + <authentication-provider> elements to define different + authentication sources and each will be consulted in turn. At this point you should be able to start up your application and you will be required - to log in to proceed. Try it out, or try experimenting with the "tutorial" sample - application that comes with the project. The above configuration actually adds quite a few - services to the application because we have used the auto-config + to log in to proceed. Try it out, or try experimenting with the tutorial + sample application that comes with the project. The above configuration actually adds quite + a few services to the application because we have used the auto-config attribute. For example, form-based login processing is automatically enabled.
What does <literal>auto-config</literal> Include? @@ -179,16 +184,15 @@ - ]]> - These other elements are responsible for setting up form-login, - basic authentication and logout handling services respectively In versions - prior to 3.0, this list also inluded remember-me functionality. This could cause some + ]]> These other elements are responsible for setting up form-login, basic + authentication and logout handling services respectively In versions prior + to 3.0, this list also included remember-me functionality. This could cause some confusing errors with some configurations and was removed in 3.0. In 3.0, the addition - of an AnonymousProcessingFilter was made part of the default + of an AnonymousProcessingFilter is part of the default <http> configuration, so the <anonymous - /> element is effectively added regardless of whether - auto-config is enabled. . They each have - attributes which can be used to alter their behaviour. + /> element is added regardless of whether auto-config + is enabled. . They each have attributes which can be used to alter + their behaviour.
Form and Basic Login Options @@ -196,22 +200,39 @@ in, since we made no mention of any HTML files or JSPs. In fact, since we didn't explicitly set a URL for the login page, Spring Security generates one automatically, based on the features that are enabled and using standard values for the URL which - processes the submitted login, the default target URL the user will be sent to and so on. - However, the namespace offers plenty of suppport to allow you to customize these options. - For example, if you want to supply your own login page, you could use: - + ]]> - Note that you could still use auto-config. The + Note that you can still use auto-config. The form-login element just overrides the default settings. Also note that we've added an extra intercept-url element to say that any - requests for the login page should be excluded from processing by the security filters. - Otherwise the request would be matched by the pattern /** and it - wouldn't be possible to access the login page itself! If you want to use basic - authentication instead of form login, then change the configuration to See the + chapter on anonymous authentication for more + details.. Otherwise the request would be matched by the pattern + /** and it wouldn't be possible to access the login page itself! This + is a common configuration error and will result in an infinite loop in the application. + Spring Security will emit a warning in the log if your login page appears to be secured. + It is also possible to have all requests matching a particular pattern bypass the security + filter chain completely: + + + + + + ]]> + Note that these requests will be completely oblivious to Spring + Security, so you will not be able to access information on the current user or call + secured methods during the request. + If you want to use basic authentication instead of form login, then change the + configuration to @@ -501,7 +522,7 @@ and remove any elements which create filters whose functionality you want to replace. Note that you can't replace filters which are created by the use of the <http> element itself - - HttpSessionContextIntegrationFilter, + SecurityContextPersistenceFilter, ExceptionTranslationFilter or FilterSecurityInterceptor. diff --git a/docs/manual/src/docbook/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml index f96a85f517..f6d930ad0d 100644 --- a/docs/manual/src/docbook/springsecurity.xml +++ b/docs/manual/src/docbook/springsecurity.xml @@ -1,14 +1,12 @@ - Spring SecurityReference Documentation - + Spring SecurityReference + Documentation Ben Alex - - + Luke Taylor - - + Spring Security 3.0.0.M2 @@ -49,15 +47,15 @@ custom requirements make application security interesting, challenging and rewarding. Please read , in its entirety to begin with. This will introduce you to the framework and the namespace-based configuration system with which you can - get up and running quite quickly. To get more of an understanding of an in-depth understaning - of how Spring Security works, and some of the classes you might need to use, you should then - read . The remaining parts of this guide are structured - in a more traditional reference style, designed to be read on an as-required basis. We'd also - recommend that you read up as much as possible on application security issues in general. - Spring Security is not a panacea which will solve all security issues. It is important that - the application is designed with security in mind from the start. Attempting to retrofit it is - not a good idea. In particular, if you are building a web application, you should be aware of - the many potential vulnerabilities such as cross-site scripting, request-forgery and + get up and running quite quickly. To get more of an understanding of how Spring Security + works, and some of the classes you might need to use, you should then read . The remaining parts of this guide are structured in a more + traditional reference style, designed to be read on an as-required basis. We'd also recommend + that you read up as much as possible on application security issues in general. Spring + Security is not a panacea which will solve all security issues. It is important that the + application is designed with security in mind from the start. Attempting to retrofit it is not + a good idea. In particular, if you are building a web application, you should be aware of the + many potential vulnerabilities such as cross-site scripting, request-forgery and session-hijacking which you should be taking into account from the start. The OWASP web site (http://www.owasp.org/) maintains a top ten list of web application vulnerabilities as well as a lot of useful reference information. @@ -70,12 +68,12 @@ Getting Started The later parts of this guide provide an in-depth discussion of the framework - architecture and implementation classes, an understanding of which is important if you need - to do any serious customization. In this part, we'll introduce Spring Security 3.0, give a - brief overview of the project's history and take a slightly gentler look at how to get - started using the framework. In particular, we'll look at namespace configuration which - provides a much simpler way of securing your application compared to the traditional Spring - bean approach where you had to wire up all the implementation classes individually. + architecture and implementation classes, which you need to understand if you want to do any + serious customization. In this part, we'll introduce Spring Security 3.0, give a brief + overview of the project's history and take a slightly gentler look at how to get started + using the framework. In particular, we'll look at namespace configuration which provides a + much simpler way of securing your application compared to the traditional Spring bean + approach where you have to wire up all the implementation classes individually. We'll also take a look at the sample applications that are available. It's worth trying to run these and experimenting with them a bit even before you read the later sections - you can dip back into them as your understanding of the framework increases. @@ -115,9 +113,9 @@ - + - +--> Authorization @@ -165,15 +163,16 @@ Essentially standalone features which do not have to follow on directly from earlier chapters --> - In this part we cover some of the more advanced and less-commonly used features of the framework. + In this part we cover some of the more advanced and less-commonly used features of the + framework. - + - +