diff --git a/src/docbkx/anon-auth-provider.xml b/src/docbkx/anon-auth-provider.xml index 922c564ae6..3ae8adabac 100644 --- a/src/docbkx/anon-auth-provider.xml +++ b/src/docbkx/anon-auth-provider.xml @@ -1,12 +1,8 @@ - - +Anonymous Authentication - -Anonymous Authentication - - Overview +
Overview + Particularly in the case of web request URI security, sometimes it is more convenient to assign configuration attributes against every @@ -22,10 +18,10 @@ SecurityContextHolder always contains an Authentication object, and never null. - +
- - Configuration +
Configuration + Spring Security provides three classes that together provide an anonymous authentication feature. @@ -105,5 +101,5 @@ principals would always be deemed "authenticated" and never be given an opportunity to login via form, basic, digest or some other normal authentication mechanism - +
 \ No newline at end of file diff --git a/src/docbkx/authorization-common.xml b/src/docbkx/authorization-common.xml index 0ca5887f5e..f9331864c4 100644 --- a/src/docbkx/authorization-common.xml +++ b/src/docbkx/authorization-common.xml @@ -1,12 +1,8 @@ - - +Common Authorization Concepts + - - Common Authorization Concepts - - - Authorities +
Authorities + As briefly mentioned in the Authentication section, all Authentication implementations are required to @@ -53,10 +49,10 @@ AuthenticationProviders included with the security architecture use GrantedAuthorityImpl to populate the Authentication object. - +
- - Pre-Invocation Handling +
Pre-Invocation Handling + The AccessDecisionManager is called by the AbstractSecurityInterceptor and is responsible for @@ -100,9 +96,7 @@ public boolean supports(Class clazz); - + @@ -252,10 +246,10 @@ public boolean supports(Class clazz); TODO: Remove references to the old ACL package when it's deprecated, and have all references to the replacement package limited to the chapter describing the new ACL implementation. - +
- - After Invocation Handling +
After Invocation Handling + Whilst the AccessDecisionManager is called by the AbstractSecurityInterceptor before proceeding @@ -272,8 +266,7 @@ public boolean supports(Class clazz); - + @@ -314,8 +307,8 @@ public boolean supports(Class clazz); achieved through a ROLE_USER or ROLE_AUTHENTICATED configuration attribute - - ACL-Aware AfterInvocationProviders +
ACL-Aware AfterInvocationProviders + PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new ACL module. The new ACL module is a significant rewrite of the @@ -398,10 +391,10 @@ public boolean supports(Class clazz); The Contacts sample application demonstrates these two AfterInvocationProviders. - +
- - ACL-Aware AfterInvocationProviders (old ACL module) +
ACL-Aware AfterInvocationProviders (old ACL module) + PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new ACL module. The new ACL module is a significant rewrite of the @@ -478,11 +471,11 @@ public boolean supports(Class clazz); The Contacts sample application demonstrates these two AfterInvocationProviders. - - +
+
- - Authorization Tag Libraries +
Authorization Tag Libraries + AuthorizeTag is used to include content if the current principal holds certain @@ -569,5 +562,5 @@ public boolean supports(Class clazz); should be considered deprecated. For the sake of historical reference, works exactly the samae as AccessControlListTag. - +
\ No newline at end of file diff --git a/src/docbkx/basic-authentication.xml b/src/docbkx/basic-authentication.xml index 2ab368e29d..a45a4b886d 100644 --- a/src/docbkx/basic-authentication.xml +++ b/src/docbkx/basic-authentication.xml @@ -1,13 +1,8 @@ - - - +BASIC Authentication Mechanism - -BASIC Authentication Mechanism - - Overview +
Overview + Spring Security provides a BasicProcessingFilter which is capable of @@ -21,10 +16,10 @@ 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 +
Configuration + To implement HTTP Basic Authentication, it is necessary to define BasicProcessingFilter in the filter chain. @@ -61,5 +56,5 @@ 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/src/docbkx/cas-auth-provider.xml b/src/docbkx/cas-auth-provider.xml index 80a44d637d..e9c4f52a2e 100644 --- a/src/docbkx/cas-auth-provider.xml +++ b/src/docbkx/cas-auth-provider.xml @@ -1,12 +1,9 @@ - - +CAS Authentication + - - CAS Authentication - - - Overview +
+ Overview + JA-SIG produces an enterprise-wide single sign on system known as CAS. Unlike other initiatives, JA-SIG's Central Authentication @@ -24,10 +21,10 @@ file, you will still need the CAS Java Server Pages and web.xml to customise and deploy your CAS server. - +
- - How CAS Works +
How CAS Works + Whilst the CAS web site above contains two documents that detail the architecture of CAS, we present the general overview again here @@ -106,7 +103,7 @@ The basic interaction between a web browser, CAS server and n Spring Security-secured service is as follows: - + The web user is browsing the service's public pages. CAS or Spring Security is not involved. @@ -301,18 +298,18 @@ It's good that you're still here! It might sound involved, but you can relax as Spring Security classes hide much of the complexity. Let's now look at how this is configured - +
- - Optional CAS Server Setup +
Optional CAS Server Setup + Spring Security can even act as the backend which a CAS version 2.0 or 3.0 server utilises. The configuration approach is described below. Of course, if you have an existing CAS environment you might just like to use it instead. - - CAS Version 2.0 +
CAS Version 2.0 + As mentioned above, Spring Security includes a PasswordHandler that bridges your existing @@ -402,10 +399,10 @@ web container's documentation on setting up HTTPS, if you need some additional help or a test certificate you might like to check the samples/contacts/etc/ssl directory - +
- - CAS Version 3.0 +
CAS Version 3.0 + As mentioned above, Spring Security includes an AuthenticationHandler that bridges your existing @@ -493,11 +490,11 @@ additional help or a test certificate you might like to check the CAS documentation on setting up SSL: http://www.ja-sig.org/products/cas/server/ssl/index.html - - +
+
- - Configuration of CAS Client +
Configuration of CAS Client + The web application side of CAS is made easy due to Spring Security. It is assumed you already know the basics of using Spring @@ -508,11 +505,11 @@ to your application context. This represents your service: - - - false - ]]> + +<bean id="serviceProperties" class="org.springframework.security.ui.cas.ServiceProperties"> + <property name="service" value="https://localhost:8443/contacts-cas/j_spring_cas_security_check"/> + <property name="sendRenew"><value>false</value></property> +</bean> The service must equal a URL that will be @@ -526,38 +523,38 @@ The following beans should be configured to commence the CAS authentication process: - - - - - - + +<bean id="casProcessingFilter" class="org.springframework.security.ui.cas.CasProcessingFilter"> + <property name="authenticationManager" ref="authenticationManager"/> + <property name="authenticationFailureUrl" value="/casfailed.jsp"/> + <property name="defaultTargetUrl" value="/"/> + <property name="filterProcessesUrl" value="/j_spring_cas_security_check"/> +</bean> - - - +<bean id="exceptionTranslationFilter" class="org.springframework.security.ui.ExceptionTranslationFilter"> + <property name="authenticationEntryPoint" ref="casProcessingFilterEntryPoint"/> +</bean> - - - - - ]]> +<bean id="casProcessingFilterEntryPoint" + class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint"> + <property name="loginUrl" value="https://localhost:8443/cas/login"/> + <property name="serviceProperties" ref="serviceProperties"/> +</bean> + You will also need to add the CasProcessingFilter to web.xml: - - casProcessingFilter - org.springframework.web.filter.DelegatingFilterProxy - + +<filter> + <filter-name>casProcessingFilter</filter-name> + <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> +</filter> - - casProcessingFilter - /* - ]]> +<filter-mapping> + <filter-name>casProcessingFilter</filter-name> + <url-pattern>/*</url-pattern> +</filter-mapping> The CasProcessingFilter has very similar @@ -671,10 +668,10 @@ There is also a contacts-cas.war file in the sample applications directory. This sample application uses the above settings and can be deployed to see CAS in operation - +
- - Advanced Issues +
Advanced Issues + The CasAuthenticationProvider distinguishes between stateful and stateless clients. A stateful client is @@ -733,5 +730,5 @@ It is hoped you find CAS integration easy and useful with Spring Security classes. Welcome to enterprise-wide single sign on! - - +
+ \ No newline at end of file diff --git a/src/docbkx/channel-security.xml b/src/docbkx/channel-security.xml index 84099e11e1..c021ed77c5 100644 --- a/src/docbkx/channel-security.xml +++ b/src/docbkx/channel-security.xml @@ -1,14 +1,10 @@ - - - - - + -Channel Security +Channel Security - - Overview +
+ Overview + In addition to coordinating the authentication and authorization requirements of your application, Spring Security is also able to @@ -37,39 +33,39 @@ <welcome-file> points to an HTTPS location, and the application never directs the user to an HTTP location. Spring Security provides a solution to assist with the latter. - +
- - Configuration +
Configuration + To use chanel security, you should define the following the filter in your application context: - - - - - - - - - - - + + <bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter"> + <property name="channelDecisionManager" ref="channelDecisionManager"/> + <property name="filterInvocationDefinitionSource"> + <security:filter-invocation-definition-source path-type="regex"> + <security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/> + <security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/> + <security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/> + <security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/> + </security:filter-invocation-definition-source> + </property> + </bean> - - - - - - - - + <bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl"> + <property name="channelProcessors"> + <list> + <ref bean="secureChannelProcessor"/> + <ref bean="insecureChannelProcessor"/> + </list> + </property> + </bean> - - - ]]> + <bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/> + <bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/> + Like FilterSecurityInterceptor, Apache Ant @@ -126,10 +122,10 @@ REQUIRES_SECURE_CHANNEL, and that the AuthenticationProcessingFilterEntryPoint.forceHttps property is true. - +
- - Conclusion +
Conclusion + Once configured, using the channel security filter is very easy. Simply request pages without regard to the protocol (ie HTTP or HTTPS) @@ -161,5 +157,5 @@ AccessDecisionVoter will ultimately result in an AccessDeniedException (depending on the governing AccessDecisionManager). - +
 \ No newline at end of file diff --git a/src/docbkx/common-auth-services.xml b/src/docbkx/common-auth-services.xml index bb4cca3fde..e4c6caa5e8 100644 --- a/src/docbkx/common-auth-services.xml +++ b/src/docbkx/common-auth-services.xml @@ -1,12 +1,8 @@ - - +Common Authentication Services + - - Common Authentication Services - - - Mechanisms, Providers and Entry Points +
Mechanisms, Providers and Entry Points + If you're using Spring Security-provided authentication approaches, you'll usually need to configure a web filter, together @@ -23,17 +19,17 @@ this: - - filterChainProxy - org.springframework.web.filter.DelegatingFilterProxy - + + <filter> + <filter-name>filterChainProxy</filter-name> + <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> + </filter> - - filterChainProxy - /* - -]]> + <filter-mapping> + <filter-name>filterChainProxy</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping> + The above declarations will cause every web request to be passed through to the bean called filterChainProxy @@ -230,10 +226,10 @@ point to use for each authentication approach is discussed in the authentication approach-specific chapters of this reference guide. - +
- - UserDetails and Associated Types +
UserDetails and Associated Types + As mentioned in the first part of the reference guide, most authentication providers take advantage of the @@ -277,8 +273,8 @@ that, Spring Security does include a couple of useful base implementations, which we'll look at below. - - In-Memory Authentication +
In-Memory Authentication + Whilst it is easy to use create a custom UserDetailsService implementation that extracts @@ -329,10 +325,10 @@ useful for simple applications that have a larger number of users, or deployment-time configuration changes, but do not wish to use a full database for handling authentication details. - +
- - JDBC Authentication +
JDBC Authentication + Spring Security also includes a UserDetailsService that can obtain authentication @@ -376,11 +372,11 @@ UserDetailsService. The base implementation provided with Spring Security is intended for typical situations, and does not offer infinite configuration flexibility. - - +
+
- - Concurrent Session Handling +
Concurrent Session Handling + Spring Security is able to prevent a principal from concurrently authenticating to the same application more than a specified number of @@ -433,10 +429,10 @@ </bean> <bean id="sessionRegistry" class="org.springframework.security.concurrent.SessionRegistryImpl"/> - +
- - Authentication Tag Libraries +
Authentication Tag Libraries + AuthenticationTag is used to simply output a property of the current principal's @@ -453,5 +449,5 @@ UserDetails object, which is generally the case when using the typical DaoAuthenticationProvider. - - +
+ \ No newline at end of file diff --git a/src/docbkx/community.xml b/src/docbkx/community.xml index 39262a4764..8699b54302 100644 --- a/src/docbkx/community.xml +++ b/src/docbkx/community.xml @@ -1,12 +1,14 @@ - - + + + + Community Support - -Community Support - - Use JIRA for Issue Tracking +
+ Use JIRA for Issue Tracking + Spring Security uses JIRA to manage bug reports and enhancement requests. If you find a bug, please log a report using JIRA. Do not @@ -21,12 +23,11 @@ if you include corresponding unit tests. This is necessary to ensure project test coverage is adequately maintained. - You can access JIRA at . - + You can access JIRA at http://jira.springframework.org/browse/SEC. +
- - Becoming Involved +
Becoming Involved + We welcome you to become involved in Spring Security project. There are many ways of contributing, including reading the mailing @@ -38,21 +39,19 @@ Spring Security home page. This explains the path to become a committer, and the administration approaches we use within the project. - +
- - Further Information +
Further Information + Questions and comments on Spring Security are welcome. Please - use the Spring Community Forum web site at for all support + use the Spring Community Forum web site at http://forum.springframework.org for all support issues. Remember to use JIRA for bug reports, as explained above. Everyone is also welcome to join the Acegisecurity-developer mailing list and participate in design discussions. It's also a good way of finding out what's happening with regard to release timing, and the traffic volume is quite light. Finally, our project home page (where you can obtain the latest release of the project and convenient links - to Subversion, JIRA, mailing lists, forums etc) is at . - + to Subversion, JIRA, mailing lists, forums etc) is at http://acegisecurity.org. +
 \ No newline at end of file diff --git a/src/docbkx/container-adapters.xml b/src/docbkx/container-adapters.xml index 9ab5ed1945..f1cb4f762e 100644 --- a/src/docbkx/container-adapters.xml +++ b/src/docbkx/container-adapters.xml @@ -1,12 +1,9 @@ - - +Container Adapter Authentication + - - Container Adapter Authentication - - - Overview +
+ Overview + Very early versions of Spring Security exclusively used Container Adapters for interfacing authentication with end users. @@ -45,10 +42,10 @@ Spring Security currently supports Jetty, Catalina (Tomcat), JBoss and Resin. Additional container adapters can easily be written - +
- - Adapter Authentication Provider +
Adapter Authentication Provider + As is always the case, the container adapter generated Authentication object still needs to be @@ -103,10 +100,10 @@ DaoAuthenticationProvider, ensure you set its forcePrincipalAsString property to true. - +
- - Jetty +
Jetty + The following was tested with Jetty 4.2.18. @@ -172,10 +169,10 @@ <realm-name> as your jetty.xml (in the example above, "Spring Powered Realm"). - +
- - JBoss +
JBoss + The following was tested with JBoss 3.2.6. @@ -302,10 +299,10 @@ JBoss is a widely-used container adapter (mostly due to the need to support legacy EJBs), so please let us know if you have any difficulties. - +
- - Resin +
Resin + The following was tested with Resin 3.0.6. @@ -377,10 +374,10 @@ indicated in your web.xml does not matter with Resin, as the relevant authentication class is indicated by the <authenticator> setting - +
- - Tomcat +
Tomcat + The following was tested with Jakarta Tomcat 4.1.30 and 5.0.19. @@ -449,5 +446,5 @@ cd / $CATALINA_HOME/bin/startup.sh Finally, restart Tomcat. - +
\ No newline at end of file diff --git a/src/docbkx/dao-auth-provider.xml b/src/docbkx/dao-auth-provider.xml index 14d8f28fe4..aad6d85fdf 100644 --- a/src/docbkx/dao-auth-provider.xml +++ b/src/docbkx/dao-auth-provider.xml @@ -1,12 +1,8 @@ - - +DAO Authentication Provider - -DAO Authentication Provider - - Overview +
Overview + Spring Security includes a production-quality AuthenticationProvider implementation called @@ -22,10 +18,10 @@ presented, and the provider will actually evaluate the validity or otherwise of the password presented in an authentication request object. - +
- - Configuration +
Configuration + Aside from adding DaoAuthenticationProvider to your ProviderManager list (as discussed at the start of this part of the @@ -126,5 +122,5 @@ prior to Spring Security 0.6), you should set the DaoAuthenticationProvider.forcePrincipalAsString property to true in your application context - +
 \ No newline at end of file diff --git a/src/docbkx/digest-authentication.xml b/src/docbkx/digest-authentication.xml index 65d6b17aa2..4152068f36 100644 --- a/src/docbkx/digest-authentication.xml +++ b/src/docbkx/digest-authentication.xml @@ -1,12 +1,8 @@ - - - - - Digest Authentication +Digest Authentication - - Overview + +
Overview + Spring Security provides a DigestProcessingFilter which is capable of @@ -80,10 +76,10 @@ "nonce" token instead. In our testing, Spring Security implementation works reliably with FireFox and Internet Explorer, correctly handling nonce timeouts etc. - +
- - Configuration +
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 @@ -141,5 +137,5 @@ 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/src/docbkx/domain-acls-old.xml b/src/docbkx/domain-acls-old.xml index 6f80fa4e33..0f6d03f8d9 100644 --- a/src/docbkx/domain-acls-old.xml +++ b/src/docbkx/domain-acls-old.xml @@ -1,12 +1,9 @@ - - + + Domain Object Security (old ACL module) + - - Domain Object Security (old ACL module) - -
- Overview +
Overview + PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new ACL module. The new ACL module is a significant rewrite of the @@ -35,7 +32,7 @@ more interesting, your customers can allow other users to see their customer records, such as their "puppy preschool "mentor or president of their local "Pony Club". Using Spring Security as the foundation, - you have several approaches that can be used: + you have several approaches that can be used: Write your business methods to enforce the security. You could consult a collection within the @@ -95,8 +92,8 @@ about below.
-
- Basic ACL Package +
Basic ACL Package + Please note that our Basic ACL services are currently being refactored. We expect release 1.1.0 will contain this new code. @@ -112,8 +109,7 @@ - + @@ -171,8 +167,7 @@ public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authen - + @@ -463,8 +458,7 @@ END; - + diff --git a/src/docbkx/domain-acls.xml b/src/docbkx/domain-acls.xml index 46c3351e9f..a353e7ce2f 100644 --- a/src/docbkx/domain-acls.xml +++ b/src/docbkx/domain-acls.xml @@ -1,181 +1,179 @@ - - - - - -Domain Object Security - -
- Overview + - PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new - ACL module. The new ACL module is a significant rewrite of the - existing ACL module. The new module can be found under the - org.springframework.security.acls package, with the - old ACL module under - org.springframework.security.acl. We encourage - users to consider testing with the new ACL module and build - applications with it. The old ACL module should be considered - deprecated and may be removed from a future release. + Domain Object Security - Complex applications often will find the need to define access - permissions not simply at a web request or method invocation level. - Instead, security decisions need to comprise both who - (Authentication), where - (MethodInvocation) and what - (SomeDomainObject). In other words, authorization - decisions also need to consider the actual domain object instance - subject of a method invocation. - Imagine you're designing an application for a pet clinic. There - will be two main groups of users of your Spring-based application: - staff of the pet clinic, as well as the pet clinic's customers. The - staff will have access to all of the data, whilst your customers will - only be able to see their own customer records. To make it a little - more interesting, your customers can allow other users to see their - customer records, such as their "puppy preschool "mentor or president - of their local "Pony Club". Using Spring Security as the foundation, - you have several approaches that can be used: + +
Overview + + + PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new + ACL module. The new ACL module is a significant rewrite of the + existing ACL module. The new module can be found under the + org.springframework.security.acls package, with the + old ACL module under + org.springframework.security.acl. We encourage + users to consider testing with the new ACL module and build + applications with it. The old ACL module should be considered + deprecated and may be removed from a future release. + + Complex applications often will find the need to define access + permissions not simply at a web request or method invocation level. + Instead, security decisions need to comprise both who + (Authentication), where + (MethodInvocation) and what + (SomeDomainObject). In other words, authorization + decisions also need to consider the actual domain object instance + subject of a method invocation. + + Imagine you're designing an application for a pet clinic. There + will be two main groups of users of your Spring-based application: + staff of the pet clinic, as well as the pet clinic's customers. The + staff will have access to all of the data, whilst your customers will + only be able to see their own customer records. To make it a little + more interesting, your customers can allow other users to see their + customer records, such as their "puppy preschool "mentor or president + of their local "Pony Club". Using Spring Security as the foundation, + you have several approaches that can be used: + + Write your business methods to enforce the security. You + could consult a collection within the + Customer domain object instance to determine + which users have access. By using the + SecurityContextHolder.getContext().getAuthentication(), + you'll be able to access the Authentication + object. + + + + Write an AccessDecisionVoter to enforce + the security from the GrantedAuthority[]s + stored in the Authentication object. This + would mean your AuthenticationManager would + need to populate the Authentication with + custom GrantedAuthority[]s representing each + of the Customer domain object instances the + principal has access to. + + + + Write an AccessDecisionVoter to enforce + the security and open the target Customer + domain object directly. This would mean your voter needs access + to a DAO that allows it to retrieve the + Customer object. It would then access the + Customer object's collection of approved + users and make the appropriate decision. + + + + Each one of these approaches is perfectly legitimate. However, + the first couples your authorization checking to your business code. + The main problems with this include the enhanced difficulty of unit + testing and the fact it would be more difficult to reuse the + Customer authorization logic elsewhere. Obtaining + the GrantedAuthority[]s from the + Authentication object is also fine, but will not + scale to large numbers of Customers. If a user + might be able to access 5,000 Customers (unlikely + in this case, but imagine if it were a popular vet for a large Pony + Club!) the amount of memory consumed and time required to construct + the Authentication object would be undesirable. The + final method, opening the Customer directly from + external code, is probably the best of the three. It achieves + separation of concerns, and doesn't misuse memory or CPU cycles, but + it is still inefficient in that both the + AccessDecisionVoter and the eventual business + method itself will perform a call to the DAO responsible for + retrieving the Customer object. Two accesses per + method invocation is clearly undesirable. In addition, with every + approach listed you'll need to write your own access control list + (ACL) persistence and business logic from scratch. + + Fortunately, there is another alternative, which we'll talk + about below. +
+ +
Key Concepts + + + The org.springframework.security.acls package should be + consulted for its major interfaces. The key interfaces are: + + - Write your business methods to enforce the security. You - could consult a collection within the - Customer domain object instance to determine - which users have access. By using the - SecurityContextHolder.getContext().getAuthentication(), - you'll be able to access the Authentication - object. + Acl: Every domain object has one and only + one Acl object, which internally holds the + AccessControlEntrys as well as knows the owner + of the Acl. An Acl does not refer directly to + the domain object, but instead to an + ObjectIdentity. - Write an AccessDecisionVoter to enforce - the security from the GrantedAuthority[]s - stored in the Authentication object. This - would mean your AuthenticationManager would - need to populate the Authentication with - custom GrantedAuthority[]s representing each - of the Customer domain object instances the - principal has access to. + AccessControlEntry: An + Acl holds multiple AccessControlEntrys, which + are often abbreviated as ACEs in the framework. Each ACE refers to + a specific tuple of Permission, + Sid and Acl. An ACE can also + be granting or non-granting and contain audit settings. - Write an AccessDecisionVoter to enforce - the security and open the target Customer - domain object directly. This would mean your voter needs access - to a DAO that allows it to retrieve the - Customer object. It would then access the - Customer object's collection of approved - users and make the appropriate decision. + Permission: A permission represents an + immutable particular bit mask, and offers convenience functions + for bit masking and outputting information. - - - Each one of these approaches is perfectly legitimate. However, - the first couples your authorization checking to your business code. - The main problems with this include the enhanced difficulty of unit - testing and the fact it would be more difficult to reuse the - Customer authorization logic elsewhere. Obtaining - the GrantedAuthority[]s from the - Authentication object is also fine, but will not - scale to large numbers of Customers. If a user - might be able to access 5,000 Customers (unlikely - in this case, but imagine if it were a popular vet for a large Pony - Club!) the amount of memory consumed and time required to construct - the Authentication object would be undesirable. The - final method, opening the Customer directly from - external code, is probably the best of the three. It achieves - separation of concerns, and doesn't misuse memory or CPU cycles, but - it is still inefficient in that both the - AccessDecisionVoter and the eventual business - method itself will perform a call to the DAO responsible for - retrieving the Customer object. Two accesses per - method invocation is clearly undesirable. In addition, with every - approach listed you'll need to write your own access control list - (ACL) persistence and business logic from scratch. - - Fortunately, there is another alternative, which we'll talk - about below. -
- -
- Key Concepts - - The org.springframework.security.acls package should be - consulted for its major interfaces. The key interfaces are: - - - - Acl: Every domain object has one and only - one Acl object, which internally holds the - AccessControlEntrys as well as knows the owner - of the Acl. An Acl does not refer directly to - the domain object, but instead to an - ObjectIdentity. - + + + Sid: The ACL module needs to refer to + principals and GrantedAuthority[]s. A level of + indirection is provided by the Sid interface. + Common classes include PrincipalSid (to + represent the principal inside an + Authentication object) and + GrantedAuthoritySid. + + + + ObjectIdentity: Each domain object is + represented internally within the ACL module by an + ObjectIdentity. + + + + AclService: Retrieves the + Acl applicable for a given + ObjectIdentity. + + + + MutableAclService: Allows a modified + Acl to be presented for persistence. It is not + essential to use this interface if you do not wish. + + - - AccessControlEntry: An - Acl holds multiple AccessControlEntrys, which - are often abbreviated as ACEs in the framework. Each ACE refers to - a specific tuple of Permission, - Sid and Acl. An ACE can also - be granting or non-granting and contain audit settings. - + The ACL module was based on extensive feedback from the user + community following real-world use of the original ACL module. This + feedback resulted in a rearchitecture of the ACL module to offer + significantly enhanced performance (particularly in the area of + database retrieval), significantly better encapsulation, higher + cohesion, and enhanced customisation points. - - Permission: A permission represents an - immutable particular bit mask, and offers convenience functions - for bit masking and outputting information. - + The Contacts Sample that ships with Acegi Security 1.0.3 offers + a demonstration of the new ACL module. Converting Contacts from using + the old module to the new module was relatively simple, and users of + the old ACL module will likely find their applications can be modified + with relatively little work. - - Sid: The ACL module needs to refer to - principals and GrantedAuthority[]s. A level of - indirection is provided by the Sid interface. - Common classes include PrincipalSid (to - represent the principal inside an - Authentication object) and - GrantedAuthoritySid. - - - - ObjectIdentity: Each domain object is - represented internally within the ACL module by an - ObjectIdentity. - - - - AclService: Retrieves the - Acl applicable for a given - ObjectIdentity. - - - - MutableAclService: Allows a modified - Acl to be presented for persistence. It is not - essential to use this interface if you do not wish. - - - - The ACL module was based on extensive feedback from the user - community following real-world use of the original ACL module. This - feedback resulted in a rearchitecture of the ACL module to offer - significantly enhanced performance (particularly in the area of - database retrieval), significantly better encapsulation, higher - cohesion, and enhanced customisation points. - - The Contacts Sample that ships with Acegi Security 1.0.3 offers - a demonstration of the new ACL module. Converting Contacts from using - the old module to the new module was relatively simple, and users of - the old ACL module will likely find their applications can be modified - with relatively little work. - - We will document the new ACL module more fully with a subsequent - release. Please note that the new ACL module should be considered a - preview only (ie do not use in production without proper prior - testing), and there is a small chance there may be changes between - 1.0.3 and 1.1.0 when it will become final. Nevertheless, - compatibility-affecting changes are considered quite unlikely, - especially given the module is already based on several years of - feedback from users of the original ACL module. -
+ We will document the new ACL module more fully with a subsequent + release. Please note that the new ACL module should be considered a + preview only (ie do not use in production without proper prior + testing), and there is a small chance there may be changes between + 1.0.3 and 1.1.0 when it will become final. Nevertheless, + compatibility-affecting changes are considered quite unlikely, + especially given the module is already based on several years of + feedback from users of the original ACL module. +
\ No newline at end of file diff --git a/src/docbkx/form-authentication.xml b/src/docbkx/form-authentication.xml index 502ad2101a..c62e426b71 100644 --- a/src/docbkx/form-authentication.xml +++ b/src/docbkx/form-authentication.xml @@ -1,36 +1,33 @@ - - - - - Form Authentication Mechanism +Form Authentication Mechanism - - Overview + +
+ Overview + HTTP Form Authentication involves using the AuthenticationProcessingFilter to process a login form. This is the most common way that application authenticate end users. Form-based authentication is entirely compatible with the DAO and JAAS authentication providers. - +
- - Configuration +
Configuration + The login form simply contains j_username and j_password input fields, and posts to a URL that is monitored by the filter (by default j_spring_security_check). You should add an AuthenticationProcessingFilter to you application context: - - - - - - ]]> + + <bean id="authenticationProcessingFilter" + class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter"> + <property name="authenticationManager" ref="authenticationManager"/> + <property name="authenticationFailureUrl" value="/acegilogin.jsp?login_error=1"/> + <property name="defaultTargetUrl" value="/"/> + <property name="filterProcessesUrl" value="/j_spring_security_check"/> + </bean> The configured AuthenticationManager @@ -58,5 +55,5 @@ If for some reason the HttpSession does not indicate the target URL, the browser will be redirected to the defaultTargetUrl property. - +
\ No newline at end of file diff --git a/src/docbkx/introduction.xml b/src/docbkx/introduction.xml index 88a6ef4397..fd43c6dd1c 100644 --- a/src/docbkx/introduction.xml +++ b/src/docbkx/introduction.xml @@ -1,12 +1,12 @@ - - + Introduction - + What is Spring Security? Spring Security provides comprehensive security services for @@ -173,8 +173,8 @@ - (* Denotes provided by a third party; check our integration page + (* Denotes provided by a third party; check our integration page for links to the latest details) Many independent software vendors (ISVs) adopt Spring Security @@ -214,7 +214,7 @@ which we'll explore later in this reference guide. - + History Spring Security began in late 2003 as "The Acegi Security System @@ -261,7 +261,7 @@ peers. - + Release Numbering It is useful to understand how Spring Security release numbers diff --git a/src/docbkx/jaas-auth-provider.xml b/src/docbkx/jaas-auth-provider.xml index 932dc0088a..c7a8cb0009 100644 --- a/src/docbkx/jaas-auth-provider.xml +++ b/src/docbkx/jaas-auth-provider.xml @@ -1,12 +1,9 @@ - - - - Java Authentication and Authorization Service (JAAS) - Provider +Java Authentication and Authorization Service (JAAS) + Provider - - Overview + +
Overview + Spring Security provides a package able to delegate authentication requests to the Java Authentication and Authorization @@ -17,10 +14,10 @@ reference documentation available from Sun Microsystems. We expect you to have a basic understanding of JAAS and its login configuration file syntax in order to understand this section. - +
- - Configuration +
Configuration + The JaasAuthenticationProvider attempts to authenticate a user’s principal and credentials through JAAS. @@ -39,34 +36,34 @@ above JAAS login configuration file: - + &lt;bean id="jaasAuthenticationProvider" + class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&gt; + &lt;property name="loginConfig"&gt; + &lt;value&gt;/WEB-INF/login.conf&lt;/value&gt; + &lt;/property&gt; + &lt;property name="loginContextName"&gt; + &lt;value&gt;JAASTest&lt;/value&gt; + &lt;/property&gt; + &lt;property name="callbackHandlers"&gt; + &lt;list&gt; + &lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&gt; + &lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&gt; + &lt;/list&gt; + &lt;/property&gt; + &lt;property name="authorityGranters"&gt; + &lt;list&gt; + &lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&gt; + &lt;/list&gt; + &lt;/property&gt; +&lt;/bean&gt; The CallbackHandlers and AuthorityGranters are discussed below. - - JAAS CallbackHandler +
JAAS CallbackHandler + Most JAAS LoginModules require a callback of some sort. These callbacks are usually used to obtain the @@ -103,10 +100,10 @@ InternalCallbackHandlers, the callback is in-turn passed to the JaasAuthenticationCallbackHandlers being wrapped. - +
- - JAAS AuthorityGranter +
JAAS AuthorityGranter + JAAS works with principals. Even "roles" are represented as principals in JAAS. Spring Security, on the other hand, works with @@ -142,6 +139,6 @@ TestAuthorityGranter in the unit tests that demonstrates a simple AuthorityGranter implementation. - - +
+
\ No newline at end of file diff --git a/src/docbkx/ldap-auth-provider.xml b/src/docbkx/ldap-auth-provider.xml index a216db355a..5630ad7290 100644 --- a/src/docbkx/ldap-auth-provider.xml +++ b/src/docbkx/ldap-auth-provider.xml @@ -1,10 +1,7 @@ - - - - LDAP Authentication - - Overview +LDAP Authentication + +
Overview + LDAP is often used by organizations as a central repository for user information and as an authentication service. It can also be used to store the role information for application users. @@ -14,17 +11,16 @@ configured to handle a wide range of situations. You should be familiar with LDAP before trying to use it with Spring Security. The following link provides a good introduction to the concepts involved and a guide to - setting up a directory using the free LDAP server OpenLDAP: . Some familiarity with the JNDI APIs used + setting up a directory using the free LDAP server OpenLDAP: http://www.zytrax.com/books/ldap/. Some familiarity with the JNDI APIs used to access LDAP from Java may also be useful. We don't use any third-party LDAP libraries (Mozilla, JLDAP etc.) in the LDAP provider, but extensive use is made of Spring LDAP, so some familiarity with that project may be useful if you plan on adding your own customizations. - - - Using LDAP with Spring Security +
+
Using LDAP with Spring Security + LDAP authentication in Spring Security can be roughly divided into the following - stages. + stages. Obtaining the unique LDAP Distinguished Name, or DN, from the login name. This will often mean performing a search in the directory, @@ -45,57 +41,56 @@ We will look at some configuration scenarios below. For full information on available configuration options, please consult the security namespace schema (information from which should be available in your XML editor). - - - Configuring an LDAP Server +
+
Configuring an LDAP Server + The first thing you need to do is configure the server against which authentication should take place. This is done using the <ldap-server> element from the security namespace. This can be configured to point at an external LDAP server, - using the url attribute: - ]]> - - Using an Embedded Test Server + using the url attribute: + <ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" /> + +
Using an Embedded Test Server + The <ldap-server> element can also be used to create an embedded server, which can be very useful for testing and demonstrations. In this - case you use it without the url attribute: - ]]> Here we've specified that the root DIT of the directory should be + case you use it without the url attribute: + <ldap-server root="dc=springframework,dc=org"/> + Here we've specified that the root DIT of the directory should be dc=springframework,dc=org, which is the default. Used this way, the namespace parser will create an embedded Apache Directory server and scan the classpath for any LDIF files, which it will attempt to load into the server. You can customize this behaviour using the ldif attribute, which defines - an LDIF resource to be loaded: - ]]> This makes it a lot easier to get up and running with LDAP, since it can be + an LDIF resource to be loaded: + <ldap-server ldif="classpath:users.ldif" /> + This makes it a lot easier to get up and running with LDAP, since it can be inconvenient to work all the time with an external server. It also insulates the user from the complex bean configuration needed to wire up an Apache Directory server. Using plain Spring Beans the configuration would be much more cluttered. You must have the necessary Apache Directory dependency jars available for your - application to use. These can be obtained from the LDAP sample application. - - - Using Bind Authentication + application to use. These can be obtained from the LDAP sample application. +
+
Using Bind Authentication + This is the most common LDAP authentication scenario. - - ]]> This simple example would obtain the DN for the user by + + <ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/> + This simple example would obtain the DN for the user by substituting the user login name in the supplied pattern and attempting to bind as that user with the login password. This is OK if all your users are stored under a single node in the directory. If instead you wished to configure an LDAP search filter to locate the user, you could use the following: - - ]]> If used with the server definition above, this would + + <ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/> + If used with the server definition above, this would perform a search under the DN ou=people,dc=springframework,dc=org using the value of the user-search-filter attribute as a filter. Again the user login name is substituted for the parameter in the filter name. If user-search-base isn't supplied, the search will be performed from the root. - - - Loading Authorities +
+
Loading Authorities + How authorities are loaded from groups in the LDAP directory is controlled by the following attributes. @@ -109,27 +104,24 @@ group-search-filter. The filter which is used to - search for group membership. The default is uniqueMember={0}, corresponding to the groupOfUniqueMembers LDAP class. In this case, the + search for group membership. The default is uniqueMember={0}, corresponding to the groupOfUniqueMembers LDAP class. In this case, the substituted parameter is the full distinguished name of the user. The parameter {1} can be used if you want to filter on the login name. So if we used the following configuration - - ]]> and authenticated successfully as user ben, + + <ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" /> + and authenticated successfully as user ben, the subsequent loading of authorities would perform a search under the directory entry ou=groups,dc=springframework,dc=org, looking for entries - which contain the attribute uniqueMember with value uid=ben,ou=people,dc=springframework,dc=org. For more information on + which contain the attribute uniqueMember with value uid=ben,ou=people,dc=springframework,dc=org. For more information on loading authorities, see the Javadoc for the DefaultLdapAuthoritiesPopulator class. - - - - Implementation Classes +
+
+
Implementation Classes + The namespace configuration options we've used above are simple to use and much more concise than using Spring beans explicitly. There are situations when you may need to know how to configure Spring Security LDAP directly in your application context. You may @@ -146,8 +138,8 @@ LdapAuthoritiesPopulator which are responsible for authenticating the user and retrieving the user's set of GrantedAuthoritys respectively. - - LdapAuthenticator Implementations +
LdapAuthenticator Implementations + The authenticator is also responsible for retrieving any required user attributes. This is because the permissions on the attributes may depend on the type of authentication being used. For example, if binding as the user, it may be necessary @@ -166,8 +158,8 @@ value is never retrieved. - - Common Functionality +
Common Functionality + Before it is possible to authenticate a user (by either strategy), the distinguished name (DN) has to be obtained from the login name supplied to the application. This can be done either by simple pattern-matching (by setting the @@ -181,35 +173,34 @@ server for more information on this). For example, if you are using an LDAP server with the URL ldap://monkeymachine.co.uk/dc=springframework,dc=org, and have a pattern uid={0},ou=greatapes, then a login name of "gorilla" - will map to a DN uid=gorilla,ou=greatapes,dc=springframework,dc=org. Each configured + will map to a DN uid=gorilla,ou=greatapes,dc=springframework,dc=org. Each configured DN pattern will be tried in turn until a match is found. For information on using a search, see the section on search objects below. A combination of the two approaches can also be used - the patterns will be checked first and if no matching DN is found, the search will be used. - - - BindAuthenticator +
+
BindAuthenticator + The class org.springframework.security.providers.ldap.authenticator.BindAuthenticator implements the bind authentication strategy. It simply attempts to bind as the user. - - - PasswordComparisonAuthenticator +
+
PasswordComparisonAuthenticator + The class org.springframework.security.providers.ldap.authenticator.PasswordComparisonAuthenticator implements the password comparison authentication strategy. - - - Active Directory Authentication +
+
Active Directory Authentication + In addition to standard LDAP authentication (binding with a DN), Active Directory has its own non-standard syntax for user authentication. - - - - Connecting to the LDAP Server +
+
+
Connecting to the LDAP Server + The beans discussed above have to be able to connect to the server. They both have to be supplied with a SpringSecurityContextSource which is an extension of Spring LDAP's ContextSource. @@ -220,59 +211,54 @@ server (instead of binding anonymously). For more information read the Javadoc for this class and for Spring LDAP's AbstractContextSource. - - - LDAP Search Objects +
+
LDAP Search Objects + Often more a more complicated strategy than simple DN-matching is required to locate a user entry in the directory. This can be encapsulated in an LdapUserSearch instance which can be supplied to the authenticator implementations, for example, to allow them to locate a user. The supplied implementation is FilterBasedLdapUserSearch. - - <classname>FilterBasedLdapUserSearch</classname> +
<classname>FilterBasedLdapUserSearch</classname> + This bean uses an LDAP filter to match the user object in the directory. The process is explained in the Javadoc for the corresponding search method on the - JDK DirContext class. As explained there, the search filter can be - supplied with parameters. For this class, the only valid parameter is {0} which will be replaced with the user's login name. - - - - Spring Bean Configuration + JDK DirContext class. As explained there, the search filter can be + supplied with parameters. For this class, the only valid parameter is {0} which will be replaced with the user's login name. +
+
+
Spring Bean Configuration + A typical configuration, using some of the beans we've discussed here, might look like this: - - - - - + +<bean id="contextSource" + class="org.springframework.security.ldap.DefaultSpringSecurityContextSource"> + <constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/> + <property name="userDn" value="cn=manager,dc=springframework,dc=org"/> + <property name="password" value="password"/> +</bean> - - - - - uid={0},ou=people - - - - - - - - - - -]]> +<bean id="ldapAuthProvider" + class="org.springframework.security.providers.ldap.LdapAuthenticationProvider"> + <constructor-arg> + <bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator"> + <constructor-arg ref="contextSource"/> + <property name="userDnPatterns"><list><value>uid={0},ou=people</value></list></property> + </bean> + </constructor-arg> + <constructor-arg> + <bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator"> + <constructor-arg ref="contextSource"/> + <constructor-arg value="ou=groups"/> + <property name="groupRoleAttribute" value="ou"/> + </bean> + </constructor-arg> +</bean> + This would set up the provider to access an LDAP server with URL ldap://monkeymachine:389/dc=springframework,dc=org. - Authentication will be performed by attempting to bind with the DN uid=<user-login-name>,ou=people,dc=springframework,dc=org. After + Authentication will be performed by attempting to bind with the DN uid=<user-login-name>,ou=people,dc=springframework,dc=org. After successful authentication, roles will be assigned to the user by searching under the DN ou=groups,dc=springframework,dc=org with the default filter (member=<user's-DN>). The role name will be taken from the @@ -280,18 +266,18 @@ To configurae a user search object, which uses the filter (uid=<user-login-name>) for use instead of the DN-pattern (or in addition to it), you would configure the following bean - - - - - - ]]> + +<bean id="userSearch" + class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch"> + <constructor-arg index="0" value=""/> + <constructor-arg index="1" value="(uid={0})"/> + <constructor-arg index="2" ref="contextSource" /> + <property name="searchSubtree" value="true"/> +</bean> and use it by setting the authenticator's userSearch property. The authenticator would then call the search object to obtain the correct user's DN before attempting to bind as this user. - - +
+
- + \ No newline at end of file diff --git a/src/docbkx/remember-me-authentication.xml b/src/docbkx/remember-me-authentication.xml index 468ca1022f..faff0f012b 100644 --- a/src/docbkx/remember-me-authentication.xml +++ b/src/docbkx/remember-me-authentication.xml @@ -1,12 +1,9 @@ - - +Remember-Me Authentication - -Remember-Me Authentication - - Overview +
+ Overview + Remember-me authentication refers to web sites being able to remember the identity of a principal between sessions. This is @@ -16,10 +13,10 @@ that such operations can take place, along with providing a concrete implementation that uses hashing to preserve the security of cookie-based tokens. - +
- - Configuration +
Configuration + Remember-me authentication is not used with basic authentication, given it is often not used with @@ -117,5 +114,5 @@ a call to RememberMeProcessingFilter into your FilterChainProxy (typically immediately after your AuthenticationProcessingFilter) - +
 \ No newline at end of file diff --git a/src/docbkx/runas-auth-provider.xml b/src/docbkx/runas-auth-provider.xml index 2035460f4e..c0ca90f15c 100644 --- a/src/docbkx/runas-auth-provider.xml +++ b/src/docbkx/runas-auth-provider.xml @@ -1,12 +1,8 @@ - - - - - Run-As Authentication Replacement +Run-As Authentication Replacement - - Overview + +
Overview + The AbstractSecurityInterceptor is able to temporarily replace the Authentication object in @@ -30,10 +26,10 @@ remoting protocols based on the contents of the SecurityContextHolder, these run-as replacements are particularly useful when calling remote web services - +
- - Configuration +
Configuration + A RunAsManager interface is provided by Acegi Security: @@ -107,5 +103,5 @@ RunAsManagerImpl. The RunAsUserToken is immutable after creation for security reasons - +
\ No newline at end of file diff --git a/src/docbkx/samples.xml b/src/docbkx/samples.xml index 388a674bd8..6dafde8bb0 100644 --- a/src/docbkx/samples.xml +++ b/src/docbkx/samples.xml @@ -1,12 +1,11 @@ - - + + +Sample Applications - -Sample Applications - - Contacts +
+ Contacts + Included with Spring Security is a very simple application that can demonstrate the basic security facilities provided by the system @@ -22,7 +21,7 @@ spring-security-sample-contacts-cas.war is designed to work with a JA-SIG CAS server. If you're just wanting to see how the sample application works, please use - spring-security-sample-contacts-filter.war + spring-security-sample-contacts-filter.war as it does not require special configuration of your container. This is also the artifact included in official release ZIPs. @@ -82,7 +81,7 @@ MethodSecurityInterceptor is securing the business objects. If you're using or spring-security-sample-contacts-cas.war, the - spring-security-sample-contacts-filter.war + spring-security-sample-contacts-filter.war FilterSecurityInterceptor is also securing the HTTP requests. If using either of these WARs, be sure to try visiting http://localhost:8080/contacts/secure/super, which @@ -104,10 +103,10 @@ and the password to use. Note that you may need to edit client.properties to use a different target URL. - +
- - Tutorial Sample +
Tutorial Sample + Whilst the Contacts Sample is quite advanced in that it illustrates the more @@ -117,36 +116,33 @@ The compiled tutorial is included in the distribution ZIP file, ready to be deployed into your web container. Authentication is - handled by the DaoAuthenticationProvider, using the - in-memory + handled by the DaoAuthenticationProvider, using the + in-memory UserDetailsService that sources information from the users.properties file located in the WAR's - /WEB-INF directory. The form-based + /WEB-INF directory. The form-based authentication mechanism is used, with the commonly-used - remember-me + remember-me authentication provider used to automatically remember the login using cookies. In terms of authorization, to keep things simple we've - configured the tutorial to only perform some basic web filter - authorization. We've wired two common pre-invocation access decision voters, + configured the tutorial to only perform some basic web filter + authorization. We've wired two common pre-invocation access decision voters, being the RoleVoter and AuthenticatedVoter, such that ROLE_* configuration attributes and IS_AUTHENTICATED_* configuration attributes may be used. Of course, it's extremely easy to add in other providers, with most users probably starting with some services-layer security using - MethodSecurityInterceptor. + MethodSecurityInterceptor. We recommend you start with the tutorial sample, as the XML is - minimal and easy to follow. All of the needed filters are configured properly, and using + minimal and easy to follow. All of the needed filters are configured properly, and using best practise. Most importantly, you can easily this one XML file (and its corresponding web.xml entries) to your existing application. Only when this basic integration is achieved do we suggest you attempt adding in method authorization or domain object security. - +
 \ No newline at end of file diff --git a/src/docbkx/secured-objects.xml b/src/docbkx/secured-objects.xml index 9e7179e681..a6a92c0740 100644 --- a/src/docbkx/secured-objects.xml +++ b/src/docbkx/secured-objects.xml @@ -1,12 +1,8 @@ - - +Secure Object Implementations + - - Secure Object Implementations - - - AOP Alliance (MethodInvocation) Security Interceptor +
AOP Alliance (MethodInvocation) Security Interceptor + To secure MethodInvocations, developers simply add a properly configured @@ -215,10 +211,10 @@ public float getBalance(int id); </property> <property name="proxyTargetClass" value="true"/> </bean> - +
- - AspectJ (JoinPoint) Security Interceptor +
AspectJ (JoinPoint) Security Interceptor + The AspectJ security interceptor is very similar to the AOP Alliance security interceptor discussed in the previous section. @@ -338,10 +334,10 @@ if (this.securityInterceptor == null) your application, using whatever means you think fit (eg new Person();) and they will have the security interceptor applied. - +
- - FilterInvocation Security Interceptor +
FilterInvocation Security Interceptor + To secure FilterInvocations, developers need to add a FilterSecurityInterceptor to their filter chain. @@ -350,30 +346,30 @@ if (this.securityInterceptor == null) In the application context you will need to configure three beans: - - - + +<bean id="exceptionTranslationFilter" + class="org.springframework.security.ui.ExceptionTranslationFilter"> + <property name="authenticationEntryPoint"><ref local="authenticationEntryPoint"/></property> +</bean> - - /acegilogin.jsp - false - +<bean id="authenticationEntryPoint" + class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint"> + <property name="loginFormUrl"><value>/acegilogin.jsp</value></property> + <property name="forceHttps"><value>false</value></property> +</bean> - - - - - - - - - - - ]]> +<bean id="filterSecurityInterceptor" + class="org.springframework.security.intercept.web.FilterSecurityInterceptor"> + <property name="authenticationManager"><ref bean="authenticationManager"/></property> + <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property> + <property name="objectDefinitionSource"> + <property name="filterInvocationDefinitionSource"> + <security:filter-invocation-definition-source path-type="regex"> + <security:intercept-url pattern="\A/secure/super/.*\Z" access="ROLE_WE_DONT_HAVE"/> + <security:intercept-url pattern="\A/secure/.*\" access="ROLE_SUPERVISOR,ROLE_TELLER"/> + </security:filter-invocation-definition-source> + </property> +</bean> The ExceptionTranslationFilter provides the bridge between Java exceptions and HTTP responses. It is solely @@ -496,5 +492,5 @@ if (this.securityInterceptor == null) AccessDecisionManager or the RunAsManager. If neither of these can process a given configuration attribute, an exception is thrown. - +
\ No newline at end of file diff --git a/src/docbkx/siteminder-auth-provider.xml b/src/docbkx/siteminder-auth-provider.xml index 2a6ffab1f9..cd46eaef76 100644 --- a/src/docbkx/siteminder-auth-provider.xml +++ b/src/docbkx/siteminder-auth-provider.xml @@ -1,12 +1,8 @@ - - +Siteminder Authentication Mechanism - -Siteminder Authentication Mechanism - - Overview +
Overview + Siteminder is a commercial single sign on solution by Computer Associates. @@ -29,10 +25,10 @@ identifies the authenticated principal (please refer to your organization's "single sign-on" group for header details in your particular configuration). - +
- - Configuration +
Configuration + The first step in setting up Spring Security's Siteminder support is to define the authentication mechanism that will inspect @@ -80,5 +76,5 @@ support form-based authentication in your development environment (where Siteminder is typically not installed), specify the form's username parameter as well. Just don't do this in production! - +
 \ No newline at end of file diff --git a/src/docbkx/springsecurity.xml b/src/docbkx/springsecurity.xml index ae64efcb37..7298b1a2b5 100644 --- a/src/docbkx/springsecurity.xml +++ b/src/docbkx/springsecurity.xml @@ -1,25 +1,24 @@ - - - - Spring Security + + + + Spring Security + + Reference Documentation + + + Ben Alex + + + 2.0-SNAPSHOT + + + + - Reference Documentation - - 2.0-SNAPSHOT - - - - Ben - Alex - - - - - - - + Preface Spring Security provides a comprehensive security solution for @@ -76,13 +75,13 @@ basis. We hope that you find this reference guide useful, and we welcome - your feedback and suggestions. + your feedback and suggestions. - Finally, welcome to the Spring Security community. + Finally, welcome to the Spring Security community. - + Overall Architecture @@ -103,10 +102,9 @@ - - + Authentication @@ -122,8 +120,6 @@ - - @@ -147,7 +143,7 @@ - + Authorization @@ -175,7 +171,7 @@ - + Other Resources diff --git a/src/docbkx/supporting-infrastructure.xml b/src/docbkx/supporting-infrastructure.xml index 3d87ffd371..d2273fa1cd 100644 --- a/src/docbkx/supporting-infrastructure.xml +++ b/src/docbkx/supporting-infrastructure.xml @@ -1,17 +1,13 @@ - - - - - Supporting Infrastructure +Supporting Infrastructure + This chapter introduces some of the supplementary and supporting infrastructure used by Spring Security. If a capability is not directly related to security, yet included in the Spring Security project, we will discuss it in this chapter. - - Localization +
Localization + Spring Security supports localization of exception messages that end users are likely to see. If your application is designed for @@ -75,10 +71,10 @@ CookieLocaleResolver, FixedLocaleResolver, SessionLocaleResolver etc) - +
- - Filters +
Filters + Spring Security uses many filters, as referred to throughout the remainder of this reference guide. You have a choice in how these @@ -90,17 +86,17 @@ something like this in the web.xml file: - - myFilter - org.springframework.web.filter.DelegatingFilterProxy - + + <filter> + <filter-name>myFilter</filter-name> + <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> + </filter> - - myFilter - /* - - ]]> + <filter-mapping> + <filter-name>myFilter</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping> + Notice that the filter is actually a DelegatingFilterProxy, @@ -149,13 +145,13 @@ The filter chain is then declared in the application context, using code such as this: - - - - - - ]]> + +<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy"> + <sec:filter-chain-map path-type="ant"> + <sec:filter-chain pattern="/webServices/**" filters="httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/> + <sec:filter-chain pattern="/**" filters="httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor"/> + </sec:filter-chain-map> +</bean> You may notice similarities with the way FilterSecurityInterceptor is declared. Both regular @@ -228,7 +224,7 @@ using, the order of the <filter-mapping>s should be as follows: - + ChannelProcessingFilter, because it might need to redirect to a different protocol @@ -276,7 +272,7 @@ SecurityContextHolder, and the request presents a cookie that enables remember-me services to take place, a suitable remembered - Authentication object will + Authentication object will be put there @@ -312,5 +308,5 @@ before the SiteMesh filters are called. This enables the SecurityContextHolder to be populated in time for use by SiteMesh decorators - +
\ No newline at end of file diff --git a/src/docbkx/taglibs.xml b/src/docbkx/taglibs.xml index d1c68a08b4..b739e503c8 100644 --- a/src/docbkx/taglibs.xml +++ b/src/docbkx/taglibs.xml @@ -1,16 +1,17 @@ - - Tag Libraries + + Tag Libraries - - Overview + +
Overview + Spring Security comes bundled with several JSP tag libraries that eases JSP writing. The tag libraries provide a range of different services. - +
- - Configuration +
Configuration + All taglib classes are included in the core spring-security-xx.jar file, with the @@ -28,10 +29,10 @@ <taglib-uri>http://www.springframework.org/security/tags</taglib-uri> <taglib-location>/WEB-INF/security.tld</taglib-location> </taglib> - +
- - Usage +
Usage + Now that you've configured the tag libraries, refer to the individual reference guide sections for details on how to use them. @@ -40,5 +41,5 @@ <%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %> - +
\ No newline at end of file diff --git a/src/docbkx/technical-overview.xml b/src/docbkx/technical-overview.xml index 04b1664ae2..24996ce863 100644 --- a/src/docbkx/technical-overview.xml +++ b/src/docbkx/technical-overview.xml @@ -1,12 +1,8 @@ - - +Technical Overview + - - Technical Overview - - - Runtime Environment +
Runtime Environment + Spring Security is written to execute within a standard Java 1.4 Runtime Environment. It also supports Java 5.0, although the Java @@ -25,10 +21,10 @@ This above design offers maximum deployment time flexibility, as you can simply copy your target artifact (be it a JAR, WAR or EAR) from one system to another and it will immediately work. - +
- - Shared Components +
Shared Components + Let's explore some of the most important shared components in Spring Security. Components are considered "shared" if they are @@ -223,10 +219,10 @@ String username = obj.toString(); Now that you've gained an understanding of these repeatedly-used components, let's take a closer look at the process of authentication. - +
- - Authentication +
Authentication + As mentioned in the beginning of this reference guide, Spring Security can participate in many different authentication @@ -241,7 +237,7 @@ String username = obj.toString(); Consider a typical web application's authentication process: - + You visit the home page, and click on a link. @@ -385,10 +381,10 @@ String username = obj.toString(); from a location, build a Spring Security-specific Authentication object, and put it onto the SecurityContextHolder. It's quite easy to do this, and it is a fully-supported integration approach. - +
- - Secure Objects +
Secure Objects + If you're familiar with AOP, you'd be aware there are different types of advice available: before, after, throws and around. An around @@ -479,15 +475,11 @@ String username = obj.toString(); - + - + @@ -507,10 +499,10 @@ String username = obj.toString(); JoinPoint and web request FilterInterceptor) with complete transparency. - +
- - Conclusion +
Conclusion + Congratulations! You have enough of a high-level picture of Spring Security to embark on your project. We've explored the shared @@ -518,5 +510,5 @@ String username = obj.toString(); authorization concept of a "secure object". Everything that follows in this reference guide may or may not apply to your particular needs, and can be read in any order. - +
\ No newline at end of file diff --git a/src/docbkx/x509-auth-provider.xml b/src/docbkx/x509-auth-provider.xml index 2e72d34239..81067cc122 100644 --- a/src/docbkx/x509-auth-provider.xml +++ b/src/docbkx/x509-auth-provider.xml @@ -1,10 +1,7 @@ - - - - X.509 Authentication - - Overview +X.509 Authentication + +
Overview + The most common use of X.509 certificate authentication is in verifying the identity of a server when using SSL, most commonly when using HTTPS from a browser. The browser will automatically check that the certificate presented by a server has been issued (ie @@ -22,25 +19,22 @@ You should be familiar with using certificates and setting up client authentication for your servlet container before attempting to use it with Spring Security. Most of the work is in creating and installing suitable certificates and keys. For example, if - you're using Tomcat then read the instructions here . It's important that + you're using Tomcat then read the instructions here http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html. It's important that you get this working before trying it out with Spring Security - - - Adding X.509 Authentication to Your Web Application - Enabling X.509 client authentication is very straightforward. Just add the <x509/> element to your http security namespace configuration. +
+
Adding X.509 Authentication to Your Web Application + + Enabling X.509 client authentication is very straightforward. Just add the <x509/> element to your http security namespace configuration. + <http> ... - + <x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/> ... - ]]> + </http> The element has two optional attributes: subject-principal-regex. The regular expression used to extract a username from the certificate's subject name. The default value is - shown above. This is the username which will be passed to the UserDetailsService to load the authorities for the + shown above. This is the username which will be passed to the UserDetailsService to load the authorities for the user. @@ -59,9 +53,9 @@ security context. If no certificate is found, or no corresponding user could be found then the security context will remain empty. This means that you can easily use X.509 authentication with other options such as a form-based login. - - - Setting up SSL in Tomcat +
+
Setting up SSL in Tomcat + There are some pre-generated certificates in the samples/certificate directory in the Spring Security project. You can use these to enable SSL for testing if you don't want to generate your own. The file @@ -74,19 +68,19 @@ To run tomcat with SSL support, drop the server.jks file into the tomcat conf directory and add the following connector to the server.xml file - + <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true" clientAuth="true" sslProtocol="TLS" keystoreFile="${catalina.home}/conf/server.jks" keystoreType="JKS" keystorePass="password" truststoreFile="${catalina.home}/conf/server.jks" truststoreType="JKS" truststorePass="password" - /> ]]> + /> clientAuth can also be set to want if you still want SSL connections to succeed even if the client doesn't provide a certificate. Clients which don't present a certificate won't be able to access any objects secured by Spring Security unless you use a non-X.509 authentication mechanism, such as form authentication. - - +
+ \ No newline at end of file diff --git a/src/docbkx/xml-auth-provider.xml b/src/docbkx/xml-auth-provider.xml deleted file mode 100644 index 1760c99181..0000000000 --- a/src/docbkx/xml-auth-provider.xml +++ /dev/null @@ -1,148 +0,0 @@ - - - - -X509 Authentication - - - Overview - - The most common use of X509 certificate authentication is in - verifying the identity of a server when using SSL, most commonly when - using HTTPS from a browser. The browser will automatically check that - the certificate presented by a server has been issued (ie digitally - signed) by one of a list of trusted certificate authorities which it - maintains. - - You can also use SSL with mutual authentication; - the server will then request a valid certificate from the client as - part of the SSL handshake. The server will authenticate the client by - checking that it's certificate is signed by an acceptable authority. - If a valid certificate has been provided, it can be obtained through - the servlet API in an application. Spring Security X509 module - extracts the certificate using a filter and passes it to the - configured X509 authentication provider to allow any additional - application-specific checks to be applied. It also maps the - certificate to an application user and loads that user's set of - granted authorities for use with the standard Spring Security - infrastructure. - - You should be familiar with using certificates and setting up - client authentication for your servlet container before attempting to - use it with Spring Security. Most of the work is in creating and - installing suitable certificates and keys. For example, if you're - using Tomcat then read the instructions here . - It's important that you get this working before trying it out with - Spring Security - - - - Using X509 with Spring Security - - With X509 authentication, there is no explicit login procedure - so the implementation is relatively simple; there is no need to - redirect requests in order to interact with the user. As a result, - some of the classes behave slightly differently from their equivalents - in other packages. For example, the default entry point - class, which is normally responsible for starting the authentication - process, is only invoked if the certificate is rejected and it always - returns an error to the user. With a suitable bean configuration, the - normal sequence of events is as follows - - The X509ProcessingFilter extracts - the certificate from the request and uses it as the credentials - for an authentication request. The generated authentication - request is an X509AuthenticationToken. - The request is passed to the authentication manager. - - - - The X509AuthenticationProvider - receives the token. Its main concern is to obtain the user - information (in particular the user's granted authorities) that - matches the certificate. It delegates this responsibility to an - X509AuthoritiesPopulator. - - - - The populator's single method, - getUserDetails(X509Certificate - userCertificate) is invoked. Implementations should - return a UserDetails instance containing - the array of GrantedAuthority objects for - the user. This method can also choose to reject the certificate - (for example if it doesn't contain a matching user name). In - such cases it should throw a - BadCredentialsException. A - DAO-based implementation, - DaoX509AuthoritiesPopulator, is provided - which extracts the user's name from the subject common - name (CN) in the certificate. It also allows you to set - your own regular expression to match a different part of the - subject's distinguished name. A UserDetailsService is used to - load the user information. - - - - If everything has gone smoothly then there should be a - valid Authentication object in the secure - context and the invocation will procede as normal. If no - certificate was found, or the certificate was rejected, then the - ExceptionTranslationFilter will invoke - the X509ProcessingFilterEntryPoint which - returns a 403 error (forbidden) to the user. - - - - - - Configuration - - There is a version of the Contacts Sample Application which - uses X509. Copy the beans and filter setup from this as a starting - point for configuring your own application. A set of example - certificates is also included which you can use to configure your - server. These are - - user.p12: A PKCS12 format file - containing the client key and certificate. These should be - installed in your browser. It maps to a use in the - application. - - - - server.p12: The server certificate - and key for HTTPS connections. - - - - ca.jks: A Java keystore containing - the certificate for the authority which issued the user's - certificate. This will be used by the container to validate - client certificates. - - For JBoss 3.2.7 (with Tomcat 5.0), the SSL - configuration in the server.xml file looks like - this - <!-- SSL/TLS Connector configuration --> - <Connector port="8443" address="${jboss.bind.address}" - maxThreads="100" minSpareThreads="5" maxSpareThreads="15" - scheme="https" secure="true" - sslProtocol = "TLS" - clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12" - keystoreType="PKCS12" keystorePass="password" - truststoreFile="${jboss.server.home.dir}/conf/ca.jks" - truststoreType="JKS" truststorePass="password" - /> - - clientAuth can also be set to - want if you still want SSL connections to - succeed even if the client doesn't provide a certificate. Obviously - these clients won't be able to access any objects secured by Spring - Security (unless you use a non-X509 authentication mechanism, such as - BASIC authentication, to authenticate the user) - - \ No newline at end of file