diff --git a/docs/manual/src/docbook/appendix-db-schema.xml b/docs/manual/src/docbook/appendix-db-schema.xml index da381000ee..0420d9fa37 100644 --- a/docs/manual/src/docbook/appendix-db-schema.xml +++ b/docs/manual/src/docbook/appendix-db-schema.xml @@ -24,7 +24,7 @@ username varchar_ignorecase(50) not null, authority varchar_ignorecase(50) not null, constraint fk_authorities_users foreign key(username) references users(username)); - create unique index ix_auth_username on authorities (username,authority);; + create unique index ix_auth_username on authorities (username,authority);
Group Authorities @@ -121,8 +121,10 @@ create table acl_entry ( id bigint generated by default as identity(start with 100) not null primary key, acl_object_identity bigint not null,ace_order int not null,sid bigint not null, mask integer not null,granting boolean not null,audit_success boolean not null, - audit_failure boolean not null,constraint unique_uk_4 unique(acl_object_identity,ace_order), - constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), + audit_failure boolean not null, + constraint unique_uk_4 unique(acl_object_identity,ace_order), + constraint foreign_fk_4 foreign key(acl_object_identity) + references acl_object_identity(id), constraint foreign_fk_5 foreign key(sid) references acl_sid(id) ); @@ -148,9 +150,9 @@ create table acl_object_identity( owner_sid bigint, entries_inheriting boolean not null, constraint unique_uk_3 unique(object_id_class,object_id_identity), - constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id), - constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id), - constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id)); + constraint foreign_fk_1 foreign key(parent_object) references acl_object_identity(id), + constraint foreign_fk_2 foreign key(object_id_class) references acl_class(id), + constraint foreign_fk_3 foreign key(owner_sid) references acl_sid(id)); create table acl_entry( id bigserial primary key, @@ -162,7 +164,8 @@ create table acl_entry( audit_success boolean not null, audit_failure boolean not null, constraint unique_uk_4 unique(acl_object_identity,ace_order), - constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), + constraint foreign_fk_4 foreign key(acl_object_identity) + references acl_object_identity(id), constraint foreign_fk_5 foreign key(sid) references acl_sid(id)); diff --git a/docs/manual/src/docbook/authorization-common.xml b/docs/manual/src/docbook/authorization-common.xml index 9ee0b1d36e..b0e5aefaa6 100644 --- a/docs/manual/src/docbook/authorization-common.xml +++ b/docs/manual/src/docbook/authorization-common.xml @@ -70,7 +70,8 @@ AccessDecisionManager interface contains three methods: - void decide(Authentication authentication, Object secureObject, List<ConfigAttribute> config) throws AccessDeniedException; + void decide(Authentication authentication, Object secureObject, + List<ConfigAttribute> config) throws AccessDeniedException; boolean supports(ConfigAttribute attribute); boolean supports(Class clazz); @@ -106,11 +107,13 @@
Voting Decision Manager + + +
@@ -227,11 +230,8 @@ boolean supports(Class clazz);
After Invocation Implementation - - - - - + + @@ -319,7 +319,7 @@ boolean supports(Class clazz); follows: + class="org.springframework.security.acls.afterinvocation.AclEntryAfterInvocationCollectionFilteringProvider"> diff --git a/docs/manual/src/docbook/basic-authentication.xml b/docs/manual/src/docbook/basic-authentication.xml index a1776af877..225f91725d 100644 --- a/docs/manual/src/docbook/basic-authentication.xml +++ b/docs/manual/src/docbook/basic-authentication.xml @@ -27,17 +27,17 @@ BasicProcessingFilter and its required collaborator: - - <bean id="basicProcessingFilter" class="org.springframework.security.web.authentication.www.BasicProcessingFilter"> - <property name="authenticationManager"><ref bean="authenticationManager"/></property> - <property name="authenticationEntryPoint"><ref bean="authenticationEntryPoint"/></property> - </bean> - - <bean id="authenticationEntryPoint" - class="org.springframework.security.web.authentication.www.BasicProcessingFilterEntryPoint"> - <property name="realmName"><value>Name Of Your Realm</value></property> - </bean> - + + + + + + + +]]> The configured AuthenticationManager diff --git a/docs/manual/src/docbook/cas-auth-provider.xml b/docs/manual/src/docbook/cas-auth-provider.xml index 2bcc394dfe..6c43334998 100644 --- a/docs/manual/src/docbook/cas-auth-provider.xml +++ b/docs/manual/src/docbook/cas-auth-provider.xml @@ -274,8 +274,10 @@ to your application context. This represents your service: - + + ]]> @@ -294,7 +296,8 @@ - + @@ -335,7 +338,8 @@ Next you need to add a CasAuthenticationProvider and its collaborators: + diff --git a/docs/manual/src/docbook/channel-security.xml b/docs/manual/src/docbook/channel-security.xml index 198faed75d..096f4777b2 100644 --- a/docs/manual/src/docbook/channel-security.xml +++ b/docs/manual/src/docbook/channel-security.xml @@ -38,23 +38,28 @@ Configuration Channel security is supported by the security namespace by means of the requires-channel attribute on the <intercept-url> - element and this is the simplest (and recommended approach) + element and this is the simplest (and recommended approach). To confiure channel security explicitly, you would define the following the filter in your application context: + - + - - - + + + - + @@ -63,8 +68,10 @@ - -]]> + +]]> Like FilterSecurityInterceptor, Apache Ant style paths are also supported by the diff --git a/docs/manual/src/docbook/common-auth-services.xml b/docs/manual/src/docbook/common-auth-services.xml index 1deb413c69..1b5f1b2ff0 100644 --- a/docs/manual/src/docbook/common-auth-services.xml +++ b/docs/manual/src/docbook/common-auth-services.xml @@ -48,7 +48,17 @@ - + ]]> @@ -123,16 +133,17 @@ shipped with Spring Security, so let's look at how it's configured for the example we're using in this chapter: - <bean id="authenticationManager" - class="org.springframework.security.authentication.ProviderManager"> -<property name="providers"> -<list> - <ref local="daoAuthenticationProvider"/> - <ref local="anonymousAuthenticationProvider"/> - <ref local="rememberMeAuthenticationProvider"/> -</list> -</property> -</bean> + + + + + + + + +]]> It's probably worth mentioning at this point that your authentication mechanisms (which are usually filters) are also @@ -187,8 +198,8 @@ - + class="org.springframework.security.web.access.ExceptionTranslationFilter"> + @@ -196,10 +207,10 @@ - + - < value="false"/> + ]]> Notice that the ExceptionTranslationFilter @@ -288,17 +299,16 @@ use the user-service element from the security namespace: - - - + + + + ]]> This also suppots the use of an external properties file: - ]]> - + + ]]> The properties file should contain entries in the form username=password,grantedAuthority[,grantedAuthority][,enabled|disabled] @@ -363,7 +373,8 @@ authority VARCHAR(50) NOT NULL ); - ALTER TABLE authorities ADD CONSTRAINT fk_authorities_users foreign key (username) REFERENCES users(username); + ALTER TABLE authorities ADD CONSTRAINT fk_authorities_users \ + foreign key (username) REFERENCES users(username); @@ -394,10 +405,12 @@ To use concurrent session support, you'll need to add the following to web.xml: - -<listener> - <listener-class>org.springframework.security.web.session.HttpSessionEventPublisher</listener-class> -</listener> + + + org.springframework.security.web.session.HttpSessionEventPublisher + + ]]> @@ -424,7 +437,7 @@ @@ -432,11 +445,12 @@ - + - + ]]> diff --git a/docs/manual/src/docbook/dao-auth-provider.xml b/docs/manual/src/docbook/dao-auth-provider.xml index fa809ea9b6..46019d9995 100644 --- a/docs/manual/src/docbook/dao-auth-provider.xml +++ b/docs/manual/src/docbook/dao-auth-provider.xml @@ -85,7 +85,8 @@ - + ]]> diff --git a/docs/manual/src/docbook/digest-authentication.xml b/docs/manual/src/docbook/digest-authentication.xml index 81e4b039e4..fa80d9df49 100644 --- a/docs/manual/src/docbook/digest-authentication.xml +++ b/docs/manual/src/docbook/digest-authentication.xml @@ -91,15 +91,15 @@ + - + diff --git a/docs/manual/src/docbook/form-authentication.xml b/docs/manual/src/docbook/form-authentication.xml index 8ec16b1747..99e5edcc97 100644 --- a/docs/manual/src/docbook/form-authentication.xml +++ b/docs/manual/src/docbook/form-authentication.xml @@ -1,15 +1,17 @@ -Form Authentication Mechanism - + + Form Authentication Mechanism
Overview - HTTP Form Authentication involves using the UsernamePasswordAuthenticationProcessingFilter to process a login form. This is the most common way for an application to authenticate end - users. Form-based authentication is entirely compatible with the DAO + users. Form-based authentication is entirely compatible with the DAO, LDAP and JAAS authentication providers. + This is also the mechanism used by the <form-login> element from the namespace + and it's recommended that you use that unless you have specific customization requirements. +
@@ -21,38 +23,47 @@ /j_spring_security_check). You should add an UsernamePasswordAuthenticationProcessingFilter to your application context: + - - ]]> - - The configured AuthenticationManager - processes each authentication request. If authentication fails, the - browser will be redirected to the - authenticationFailureUrl. The - AuthenticationException will be placed into the - HttpSession attribute indicated by - AbstractAuthenticationProcessingFilter.SPRING_SECURITY_LAST_EXCEPTION_KEY, - enabling a reason to be provided to the user on the error page. + + The configured AuthenticationManager + processes each authentication request. The destination following a successful authentication + or an authentication failure is controlled by the AuthenticationSuccessHandler + and AuthenticationFailureHandler interfaces, respectively. + The filter has properties which allow you to set these + In versions prior to 3.0, the application flow at this point had evolved to a stage + was controlled by a mix of properties on this class and strategy plugins. The + decision was made for 3.0 to refactor the code to make these two strategies entirely responsible. + . + Some standard implementations are supplied for these such as + SimpleUrlAuthenticationSuccessHandler, + SavedRequestAwareAuthenticationSuccessHandler, + SimpleUrlAuthenticationFailureHandler and + ExceptionMappingAuthenticationFailureHandler. Have a look at the Javadoc + for these classes to see how they work. + If authentication is successful, the resulting Authentication object will be placed into the - SecurityContextHolder. + SecurityContextHolder. + The configured AuthenticationSuccessHandler will then be called to either redirect or forward + the user to the approprate destination. By default a SavedRequestAwareAuthenticationSuccessHandler + is used, which means that the user will be redirected to the original destination they requested before they were asked to + login. + + + The ExceptionTranslationFilter caches the original request a user makes. + When the user authenticates, the request handler makes use of this cached request to obtain the original + URL and redirect to it. The original request is then rebuilt and used as an alternative. + + + If authentication fails, the configured AuthenticationFailureHandler will be invoked. + - Once the SecurityContextHolder has been - updated, the browser will need to be redirected to the target URL which - is usually indicated by the HttpSession attribute stored under - AbstractAuthenticationProcessingFilter.SPRING_SECURITY_TARGET_URL_KEY. - This attribute is automatically set by the - ExceptionTranslationFilter when an - AuthenticationException occurs, so that after login - is completed the user can return to what they were originally trying to access. - 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/docs/manual/src/resources/images/ACLSecurity.gif b/docs/manual/src/docbook/images/ACLSecurity.gif similarity index 100% rename from docs/manual/src/resources/images/ACLSecurity.gif rename to docs/manual/src/docbook/images/ACLSecurity.gif diff --git a/docs/manual/src/resources/images/AccessDecisionVoting.gif b/docs/manual/src/docbook/images/AccessDecisionVoting.gif similarity index 100% rename from docs/manual/src/resources/images/AccessDecisionVoting.gif rename to docs/manual/src/docbook/images/AccessDecisionVoting.gif diff --git a/docs/manual/src/resources/images/AfterInvocation.gif b/docs/manual/src/docbook/images/AfterInvocation.gif similarity index 100% rename from docs/manual/src/resources/images/AfterInvocation.gif rename to docs/manual/src/docbook/images/AfterInvocation.gif diff --git a/docs/manual/src/resources/images/Authentication.gif b/docs/manual/src/docbook/images/Authentication.gif similarity index 100% rename from docs/manual/src/resources/images/Authentication.gif rename to docs/manual/src/docbook/images/Authentication.gif diff --git a/docs/manual/src/resources/images/BasicAclProvider.gif b/docs/manual/src/docbook/images/BasicAclProvider.gif similarity index 100% rename from docs/manual/src/resources/images/BasicAclProvider.gif rename to docs/manual/src/docbook/images/BasicAclProvider.gif diff --git a/docs/manual/src/resources/images/Context.gif b/docs/manual/src/docbook/images/Context.gif similarity index 100% rename from docs/manual/src/resources/images/Context.gif rename to docs/manual/src/docbook/images/Context.gif diff --git a/docs/manual/src/resources/images/Permissions.gif b/docs/manual/src/docbook/images/Permissions.gif similarity index 100% rename from docs/manual/src/resources/images/Permissions.gif rename to docs/manual/src/docbook/images/Permissions.gif diff --git a/docs/manual/src/resources/images/SecurityInterception.gif b/docs/manual/src/docbook/images/SecurityInterception.gif similarity index 100% rename from docs/manual/src/resources/images/SecurityInterception.gif rename to docs/manual/src/docbook/images/SecurityInterception.gif diff --git a/docs/manual/src/resources/images/logo.gif b/docs/manual/src/docbook/images/logo.gif similarity index 100% rename from docs/manual/src/resources/images/logo.gif rename to docs/manual/src/docbook/images/logo.gif diff --git a/docs/manual/src/resources/images/s2-banner-rhs.png b/docs/manual/src/docbook/images/s2-banner-rhs.png similarity index 100% rename from docs/manual/src/resources/images/s2-banner-rhs.png rename to docs/manual/src/docbook/images/s2-banner-rhs.png diff --git a/docs/manual/src/resources/images/s2_box_logo.png b/docs/manual/src/docbook/images/s2_box_logo.png similarity index 100% rename from docs/manual/src/resources/images/s2_box_logo.png rename to docs/manual/src/docbook/images/s2_box_logo.png diff --git a/docs/manual/src/docbook/images/security-interception.graffle b/docs/manual/src/docbook/images/security-interception.graffle new file mode 100644 index 0000000000..0b8e62b929 Binary files /dev/null and b/docs/manual/src/docbook/images/security-interception.graffle differ diff --git a/docs/manual/src/docbook/images/security-interception.png b/docs/manual/src/docbook/images/security-interception.png new file mode 100644 index 0000000000..0f5ec2b2cb Binary files /dev/null and b/docs/manual/src/docbook/images/security-interception.png differ diff --git a/docs/manual/src/resources/images/xdev-spring_logo.jpg b/docs/manual/src/docbook/images/xdev-spring_logo.jpg similarity index 100% rename from docs/manual/src/resources/images/xdev-spring_logo.jpg rename to docs/manual/src/docbook/images/xdev-spring_logo.jpg diff --git a/docs/manual/src/docbook/introduction.xml b/docs/manual/src/docbook/introduction.xml index c13981fb1e..9032c6d5d7 100644 --- a/docs/manual/src/docbook/introduction.xml +++ b/docs/manual/src/docbook/introduction.xml @@ -1,308 +1,225 @@ - - - -Introduction - - - What is Spring Security? - - Spring Security provides comprehensive security services for - J2EE-based enterprise software applications. There is a particular - emphasis on supporting projects built using The Spring Framework, - which is the leading J2EE solution for enterprise software - development. If you're not using Spring for developing enterprise - applications, we warmly encourage you to take a closer look at it. - Some familiarity with Spring - and in particular dependency injection - principles - will help you get up to speed with Spring Security more - easily. - - People use Spring Security for many reasons, but most are drawn - to the project after finding the security features of J2EE's Servlet - Specification or EJB Specification lack the depth required for typical - enterprise application scenarios. Whilst mentioning these 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 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. - - 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 - addition, Spring Security provides its own set of authentication - features. Specifically, Spring Security currently supports - authentication integration with all of these technologies: - - - - HTTP BASIC authentication headers (an IEFT RFC-based - standard) - - - - HTTP Digest authentication headers (an IEFT RFC-based - standard) - - - - HTTP X.509 client certificate exchange (an IEFT RFC-based - standard) - - - - LDAP (a very common approach to cross-platform - authentication needs, especially in large environments) - - - - Form-based authentication (for simple user interface - needs) - - - - OpenID authentication - - - - Computer Associates Siteminder - - - - JA-SIG Central Authentication Service (otherwise known as - CAS, which is a popular open source single sign on system) - - - - Transparent authentication context propagation for Remote - Method Invocation (RMI) and HttpInvoker (a Spring remoting - protocol) - - - - Automatic "remember-me" authentication (so you can tick a - box to avoid re-authentication for a predetermined period of - time) - - - - Anonymous authentication (allowing every call to - automatically assume a particular security identity) - - - - Run-as authentication (which is useful if one call should - proceed with a different security identity) - - - - Java Authentication and Authorization Service (JAAS) - - - - Container integration with JBoss, Jetty, Resin and Tomcat - (so you can still use Container Manager Authentication if - desired) - - - - Java Open Source Single Sign On (JOSSO) * - - - - OpenNMS Network Management Platform * - - - - AppFuse * - - - - AndroMDA * - - - - Mule ESB * - - - - Direct Web Request (DWR) * - - - - Grails * - - - - Tapestry * - - - - JTrac * - - - - Jasypt * - - - - Roller * - - - - Elastic Plath * - - - - Atlassian Crowd * - - - - Your own authentication systems (see below) - - - - (* Denotes provided by a third party; check our integration page - for links to the latest details) - - Many independent software vendors (ISVs) adopt Spring Security - because of this significant choice of flexible authentication models. - Doing so allows them to quickly integrate their solutions with - whatever their end clients need, without undertaking a lot of - engineering or requiring the client to change their environment. If - none of the above authentication mechanisms suit your needs, Spring - Security is an open platform and it is quite simple to write your own - authentication mechanism. Many corporate users of Spring Security need - to integrate with "legacy" systems that don't follow any particular - security standards, and Spring Security is happy to "play nicely" with - such systems. - - Sometimes the mere process of authentication isn't enough. - Sometimes you need to also 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. - - 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. - - - - History - - Spring Security began in late 2003 as "The Acegi Security System - for Spring". A question was posed on the Spring Developers' mailing - list asking whether there had been any consideration given to a - Spring-based security implementation. At the time the Spring community - was relatively small (especially by today's size!), and indeed Spring - itself had only existed as a SourceForge project from early 2003. The - response to the question was that it was a worthwhile area, although a - lack of time currently prevented its exploration. - - With that in mind, a simple security implementation was built - and not released. A few weeks later another member of the Spring - community inquired about security, and at the time this code was - offered to them. Several other requests followed, and by January 2004 - around twenty people were using the code. These pioneering users were - joined by others who suggested a SourceForge project was in order, - which was duly established in March 2004. - - In those early days, the project didn't have any of its own - authentication modules. Container Managed Security was relied upon for - the authentication process, with Acegi Security instead focusing on - authorization. This was suitable at first, but as more and more users - requested additional container support, the fundamental limitation of - container-specific authentication realm interfaces was experienced. - There was also a related issue of adding new JARs to the container's - classpath, which was a common source of end user confusion and - misconfiguration. - - Acegi Security-specific authentication services were - subsequently introduced. Around a year later, Acegi Security became an - official Spring Framework subproject. The 1.0.0 final release was - published in May 2006 - after more than two and a half years of active - use in numerous production software projects and many hundreds of - improvements and community contributions. - - Acegi Security became an official Spring Portfolio project - towards the end of 2007 and was rebranded as "Spring Security". - - Today Spring Security enjoys a strong and active open source - community. There are thousands of messages about Spring Security on - the support forums. There is an active core of developers work - who work on the code itself and an active community which also - regularly share patches and support their peers. - - - - Release Numbering - - It is useful to understand how Spring Security release numbers - work, as it will help you identify the effort (or lack thereof) - involved in migrating to future releases of the project. Officially, - we use the Apache Portable Runtime Project versioning guidelines, - which can be viewed at - http://apr.apache.org/versioning.html. We quote the - introduction contained on that page for your convenience: - - Versions are denoted using a standard triplet of - integers: MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions - are incompatible, large-scale upgrades of the API. MINOR versions - retain source and binary compatibility with older minor versions, and - changes in the PATCH level are perfectly compatible, forwards and - backwards. - - - - Getting the Source - - Since Spring Security is an Open Source project, we'd strongly encourage you to - check out the source code using subversion. This will give you full access to all the sample - applications and you can build the most up to date version of the project easily. - Having the source for a project is also a huge help in debugging. Exception stack traces are no - longer obscure black-box issues but you can get straight to the line that's causing the problem - and work out what's happening. The source is the ultimate documentation for a project and often - the simplest place to find out how something actually works. - - - To obtain the source for the project trunk, use the following subversion command: - - svn checkout http://acegisecurity.svn.sourceforge.net/svnroot/acegisecurity/spring-security/trunk/ + Introduction + + What is Spring Security? + Spring Security provides comprehensive security services for J2EE-based enterprise + software applications. There is a particular emphasis on supporting projects built using + The Spring Framework, which is the leading J2EE solution for enterprise software + development. If you're not using Spring for developing enterprise applications, we + warmly encourage you to take a closer look at it. Some familiarity with Spring - and in + particular dependency injection principles - will help you get up to speed with Spring + Security more easily. + People use Spring Security for many reasons, but most are drawn to the project after + finding the security features of J2EE's Servlet Specification or EJB Specification lack + the depth required for typical enterprise application scenarios. Whilst mentioning these + 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 + 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. + 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 + addition, Spring Security provides its own set of authentication features. Specifically, + Spring Security currently supports authentication integration with all of these + technologies: + + + HTTP BASIC authentication headers (an IEFT RFC-based standard) + + + HTTP Digest authentication headers (an IEFT RFC-based standard) + + + HTTP X.509 client certificate exchange (an IEFT RFC-based standard) + + + LDAP (a very common approach to cross-platform authentication needs, + especially in large environments) + + + Form-based authentication (for simple user interface needs) + + + OpenID authentication + + + Computer Associates Siteminder + + + JA-SIG Central Authentication Service (otherwise known as CAS, which is a + popular open source single sign on system) + + + Transparent authentication context propagation for Remote Method Invocation + (RMI) and HttpInvoker (a Spring remoting protocol) + + + Automatic "remember-me" authentication (so you can tick a box to avoid + re-authentication for a predetermined period of time) + + + Anonymous authentication (allowing every call to automatically assume a + particular security identity) + + + Run-as authentication (which is useful if one call should proceed with a + different security identity) + + + Java Authentication and Authorization Service (JAAS) + + + Container integration with JBoss, Jetty, Resin and Tomcat (so you can still + use Container Manager Authentication if desired) + + + Java Open Source Single Sign On (JOSSO) * + + + OpenNMS Network Management Platform * + + + AppFuse * + + + AndroMDA * + + + Mule ESB * + + + Direct Web Request (DWR) * + + + Grails * + + + Tapestry * + + + JTrac * + + + Jasypt * + + + Roller * + + + Elastic Path * + + + Atlassian Crowd * + + + Your own authentication systems (see below) + + + (* Denotes provided by a third party; check our integration page for + links to the latest details) + Many independent software vendors (ISVs) adopt Spring Security because of this + significant choice of flexible authentication models. Doing so allows them to quickly + integrate their solutions with whatever their end clients need, without undertaking a + lot of engineering or requiring the client to change their environment. If none of the + above authentication mechanisms suit your needs, Spring Security is an open platform and + it is quite simple to write your own authentication mechanism. Many corporate users of + Spring Security need to integrate with "legacy" systems that don't follow any particular + security standards, and Spring Security is happy to "play nicely" with such + systems. + Sometimes the mere process of authentication isn't enough. Sometimes you need to also + 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. + 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. + + + History + Spring Security began in late 2003 as "The Acegi Security System for Spring". A + question was posed on the Spring Developers' mailing list asking whether there had been + any consideration given to a Spring-based security implementation. At the time the + Spring community was relatively small (especially by today's size!), and indeed Spring + itself had only existed as a SourceForge project from early 2003. The response to the + question was that it was a worthwhile area, although a lack of time currently prevented + its exploration. + With that in mind, a simple security implementation was built and not released. A few + weeks later another member of the Spring community inquired about security, and at the + time this code was offered to them. Several other requests followed, and by January 2004 + around twenty people were using the code. These pioneering users were joined by others + who suggested a SourceForge project was in order, which was duly established in March + 2004. + In those early days, the project didn't have any of its own authentication modules. + Container Managed Security was relied upon for the authentication process, with Acegi + Security instead focusing on authorization. This was suitable at first, but as more and + more users requested additional container support, the fundamental limitation of + container-specific authentication realm interfaces was experienced. There was also a + related issue of adding new JARs to the container's classpath, which was a common source + of end user confusion and misconfiguration. + Acegi Security-specific authentication services were subsequently introduced. Around a + year later, Acegi Security became an official Spring Framework subproject. The 1.0.0 + final release was published in May 2006 - after more than two and a half years of active + use in numerous production software projects and many hundreds of improvements and + community contributions. + Acegi Security became an official Spring Portfolio project towards the end of 2007 and + was rebranded as "Spring Security". + Today Spring Security enjoys a strong and active open source community. There are + thousands of messages about Spring Security on the support forums. There is an active + core of developers work who work on the code itself and an active community which also + regularly share patches and support their peers. + + + Release Numbering + It is useful to understand how Spring Security release numbers work, as it will help + you identify the effort (or lack thereof) involved in migrating to future releases of + the project. Officially, we use the Apache Portable Runtime Project versioning + guidelines, which can be viewed at + http://apr.apache.org/versioning.html. We quote the introduction + contained on that page for your convenience: + Versions are denoted using a standard triplet of integers: MAJOR.MINOR.PATCH. + The basic intent is that MAJOR versions are incompatible, large-scale upgrades of + the API. MINOR versions retain source and binary compatibility with older minor + versions, and changes in the PATCH level are perfectly compatible, forwards and + backwards. + + + Getting the Source + Since Spring Security is an Open Source project, we'd strongly encourage you to check + out the source code using subversion. This will give you full access to all the sample + applications and you can build the most up to date version of the project easily. Having + the source for a project is also a huge help in debugging. Exception stack traces are no + longer obscure black-box issues but you can get straight to the line that's causing the + problem and work out what's happening. The source is the ultimate documentation for a + project and often the simplest place to find out how something actually works. + To obtain the source for the project trunk, use the following subversion command: + + svn checkout https://src.springframework.org/svn/spring-security/trunk/ - You can checkout specific versions from http://acegisecurity.svn.sourceforge.net/svnroot/acegisecurity/spring-security/tags/. - - - - - \ No newline at end of file + You can checkout specific versions from + https://src.springframework.org/svn/spring-security/tags/. + + + diff --git a/docs/manual/src/docbook/jaas-auth-provider.xml b/docs/manual/src/docbook/jaas-auth-provider.xml index 11062bda95..cd2a322dd1 100644 --- a/docs/manual/src/docbook/jaas-auth-provider.xml +++ b/docs/manual/src/docbook/jaas-auth-provider.xml @@ -32,14 +32,16 @@ JAASTest { above JAAS login configuration file: - - - - - - - + class="org.springframework.security.authentication.jaas.JaasAuthenticationProvider"> + + + + + + + diff --git a/docs/manual/src/docbook/ldap-auth-provider.xml b/docs/manual/src/docbook/ldap-auth-provider.xml index 60a1dad34d..62f5479edb 100644 --- a/docs/manual/src/docbook/ldap-auth-provider.xml +++ b/docs/manual/src/docbook/ldap-auth-provider.xml @@ -69,8 +69,8 @@ url attribute: - ]]> + +]]>
@@ -85,8 +85,8 @@ url attribute: - ]]> + + ]]> 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 @@ -96,7 +96,7 @@ 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 inconvenient to work all the time with an external server. It also insulates the @@ -113,7 +113,7 @@ This is the most common LDAP authentication scenario. + ]]> 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 @@ -121,7 +121,8 @@ 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 perform a search under the DN ou=people,dc=springframework,dc=org @@ -167,7 +168,8 @@ So if we used the following configuration + ]]> and authenticated successfully as user ben, the subsequent loading of authorities would perform a search @@ -195,9 +197,8 @@ using namespace configuration then you can skip this section and the next one. - The main LDAP provider class is - org.springframework.security.ldap.authentication.LdapAuthenticationProvider. - This bean doesn't actually do much itself but delegates the work to two other beans, an + The main LDAP provider class, LdapAuthenticationProvider, + doesn't actually do much itself but delegates the work to two other beans, an LdapAuthenticator and an LdapAuthoritiesPopulator @@ -260,8 +261,8 @@ BindAuthenticator - The class - org.springframework.security.ldap.authentication.BindAuthenticator + The class BindAuthenticator in the package + org.springframework.security.ldap.authentication implements the bind authentication strategy. It simply attempts to bind as the user.
@@ -269,8 +270,7 @@ PasswordComparisonAuthenticator - The class - org.springframework.security.ldap.authentication.PasswordComparisonAuthenticator + The class PasswordComparisonAuthenticator implements the password comparison authentication strategy.
@@ -350,22 +350,23 @@ - - - - - uid={0},ou=people - - - - - - - - - - + class="org.springframework.security.ldap.authentication.LdapAuthenticationProvider"> + + + + + uid={0},ou=people + + + + + + + + + + ]]> This would set up the provider to access an LDAP server with URL @@ -410,9 +411,10 @@ to and from LDAP context data: Only the first method is relevant for authentication. If you provide an implementation of this interface, you can diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index 316af575f2..19e6ebce6e 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -34,8 +34,10 @@ + xsi:schemaLocation="http://www.springframework.org/schema/beans + http://www.springframework.org/schema/beans/spring-beans-3.0.xsd + http://www.springframework.org/schema/security + http://www.springframework.org/schema/security/spring-security-3.0.xsd"> ... ]]> In many of the examples you will see (and in the sample) applications, we @@ -47,8 +49,10 @@ + xsi:schemaLocation="http://www.springframework.org/schema/beans + http://www.springframework.org/schema/beans/spring-beans-3.0.xsd + http://www.springframework.org/schema/security + http://www.springframework.org/schema/security/spring-security-3.0.xsd"> ... ]]> We'll assume this syntax is being used from now on in this chapter. @@ -109,8 +113,7 @@
<literal>web.xml</literal> Configuration The first thing you need to do is add the following filter declaration to your - web.xml file: - web.xml file: springSecurityFilterChain org.springframework.web.filter.DelegatingFilterProxy @@ -245,7 +248,8 @@ - + ]]> @@ -276,7 +280,8 @@ user-service-ref attribute: - + ]]> @@ -292,8 +297,10 @@ - - + + ]]> @@ -304,9 +311,9 @@ UserDetails object which is loaded by your UserDetailsService. For example, to use the username property, you would use - - + + + ]]> You can use a custom password encoder bean by using the ref attribute of password-encoder. This should contain the name of a bean in the application context which is an instance of Spring @@ -336,8 +343,7 @@ to an HTTPS URL. The available options are "http", "https" or "any". Using the value "any" means that either HTTP or HTTPS can be used. If your application uses non-standard ports for HTTP and/or HTTPS, you can specify a - list of port mappings as follows: - ... @@ -354,9 +360,11 @@ additions. First you need to add the following listener to your web.xml file to keep Spring Security updated about session lifecycle events: - org.springframework.security.web.session.HttpSessionEventPublisher - + + + org.springframework.security.web.session.HttpSessionEventPublisher + + ]]> Then add the following line to your application context: ... @@ -384,7 +392,8 @@ ]]> You should then register yourself with an OpenID provider (such as myopenid.com), and add the user information to your in-memory <user-service>: + ]]> You should be able to login using the myopenid.com site to authenticate.
@@ -566,9 +575,9 @@
Method Security - Spring Security 2.0 has improved support substantially for adding security to your - service layer methods. If you are using Java 5 or greater, then support for JSR-250 security - annotations is provided, as well as the framework's native @Secured + From version 2.0 onwards Spring Security has improved support substantially for adding security to your + service layer methods. It provides support for JSR-250 security + as well as the framework's native @Secured annotation. You can apply security to a single bean, using the intercept-methods element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts. @@ -607,7 +616,8 @@ you to apply security to many beans with only a simple declaration. Consider the following example: - + ]]> This will protect all methods on beans declared in the application @@ -691,7 +701,8 @@ you can then use this name elsewhere in your application context. - + ... diff --git a/docs/manual/src/docbook/preauth.xml b/docs/manual/src/docbook/preauth.xml index b795edb809..995a65997d 100644 --- a/docs/manual/src/docbook/preauth.xml +++ b/docs/manual/src/docbook/preauth.xml @@ -150,19 +150,19 @@ A typical configuration using this filter would look like this: + +class="org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider"> + class="org.springframework.security.userdetails.UserDetailsByNameServiceWrapper"> diff --git a/docs/manual/src/docbook/remember-me-authentication.xml b/docs/manual/src/docbook/remember-me-authentication.xml index 9dc62800c9..433054be43 100644 --- a/docs/manual/src/docbook/remember-me-authentication.xml +++ b/docs/manual/src/docbook/remember-me-authentication.xml @@ -29,14 +29,15 @@ In essence a cookie is sent to the browser upon successful interactive authentication, with the cookie being composed as follows: - base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key)) + base64(username + ":" + expirationTime + ":" + + md5Hex(username + ":" + expirationTime + ":" password + ":" + key)) - username: As identifiable to the UserDetailsService - password: That matches the one in the retrieved UserDetails - expirationTime: The date and time when the remember-me token expires, expressed in milliseconds - key: A private key to prevent modification of the remember-me token + username: As identifiable to the UserDetailsService + password: That matches the one in the retrieved UserDetails + expirationTime: The date and time when the remember-me token expires, + expressed in milliseconds + key: A private key to prevent modification of the remember-me token - As such the remember-me token is valid only for the period specified, and provided that the username, password and key does not change. Notably, this has a potential security issue in that a @@ -97,10 +98,11 @@ superclass. The hooks will invoke a concrete RememberMeServices at the appropriate times. The interface looks like this: - + Authentication autoLogin(HttpServletRequest request, HttpServletResponse response); void loginFail(HttpServletRequest request, HttpServletResponse response); - void loginSuccess(HttpServletRequest request, HttpServletResponse response, Authentication successfulAuthentication); + void loginSuccess(HttpServletRequest request, HttpServletResponse response, + Authentication successfulAuthentication); Please refer to the JavaDocs for a fuller discussion on what the methods do, although note at this stage that @@ -137,20 +139,21 @@ to have the cookie cleared automatically. The beans required in an application context to enable remember-me services are as follows: - + - + - + ]]> diff --git a/docs/manual/src/docbook/runas-auth-provider.xml b/docs/manual/src/docbook/runas-auth-provider.xml index a5148d0c0b..a66414084c 100644 --- a/docs/manual/src/docbook/runas-auth-provider.xml +++ b/docs/manual/src/docbook/runas-auth-provider.xml @@ -32,7 +32,8 @@ Configuration A RunAsManager interface is provided by Spring Security: - Authentication buildRunAs(Authentication authentication, Object object, List<ConfigAttribute> config); + Authentication buildRunAs(Authentication authentication, Object object, + List<ConfigAttribute> config); boolean supports(ConfigAttribute attribute); boolean supports(Class clazz); @@ -87,7 +88,8 @@ bean context with the same key: + diff --git a/docs/manual/src/docbook/secured-objects.xml b/docs/manual/src/docbook/secured-objects.xml index 453a96d178..7561af023b 100644 --- a/docs/manual/src/docbook/secured-objects.xml +++ b/docs/manual/src/docbook/secured-objects.xml @@ -76,7 +76,7 @@ + class="org.springframework.security.intercept.aspectj.AspectJSecurityInterceptor"> @@ -115,7 +115,7 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { private AspectJSecurityInterceptor securityInterceptor; pointcut domainObjectInstanceExecution(): target(PersistableEntity) - && execution(public * *(..)) && !within(DomainObjectInstanceSecurityAspect); + && execution(public * *(..)) && !within(DomainObjectInstanceSecurityAspect); Object around(): domainObjectInstanceExecution() { if (this.securityInterceptor == null) { @@ -162,8 +162,8 @@ public void afterPropertiesSet() throws Exception { + class="org.springframework.security.samples.aspectj.DomainObjectInstanceSecurityAspect" + factory-method="aspectOf"> ]]> @@ -187,12 +187,12 @@ public void afterPropertiesSet() throws Exception { + class="org.springframework.security.web.access.ExceptionTranslationFilter"> + class="org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint"> @@ -291,7 +291,7 @@ public void afterPropertiesSet() throws Exception { + class="org.springframework.security.intercept.web.FilterSecurityInterceptor"> diff --git a/docs/manual/src/docbook/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml index 53a8cf9449..1769affb7d 100644 --- a/docs/manual/src/docbook/springsecurity.xml +++ b/docs/manual/src/docbook/springsecurity.xml @@ -1,9 +1,15 @@ - Spring SecurityReference Documentation - Ben Alex, Luke Taylor - + Spring SecurityReference Documentation + + Ben Alex + + + Luke Taylor + + + Spring Security 3.0.0.M1 @@ -82,11 +88,13 @@ Overall Architecture - Like most software, Spring Security has certain central interfaces, classes and - conceptual abstractions that are commonly used throughout the framework. In this part of the - reference guide we will introduce Spring Security, before examining these central elements - that are necessary to successfully planning and executing a Spring Security - integration. + Once you are familiar with setting up and running some namespace-configuration based + applications, you may wish to develop more of an understanding of how the framework actually + works behind the namespace facade. Like most software, Spring Security has certain central + interfaces, classes and conceptual abstractions that are commonly used throughout the + framework. In this part of the reference guide we will look at some of these and see how + they work together to support authentication and access-control within Spring + Security. diff --git a/docs/manual/src/docbook/supporting-infrastructure.xml b/docs/manual/src/docbook/supporting-infrastructure.xml index 556424127d..8f640ef224 100644 --- a/docs/manual/src/docbook/supporting-infrastructure.xml +++ b/docs/manual/src/docbook/supporting-infrastructure.xml @@ -38,7 +38,8 @@ is shown below: + ]]> @@ -91,16 +92,16 @@ When using DelegatingFilterProxy, you will see something like this in the web.xml file: - - <filter> - <filter-name>myFilter</filter-name> - <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> - </filter> + + myFilter + org.springframework.web.filter.DelegatingFilterProxy + - <filter-mapping> - <filter-name>myFilter</filter-name> - <url-pattern>/*</url-pattern> - </filter-mapping> + + myFilter + /* + ]]> Notice that the filter is actually a DelegatingFilterProxy, @@ -152,10 +153,16 @@ - - + + ]]> @@ -335,8 +342,7 @@ in your JSP: <%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %> - - +
\ No newline at end of file diff --git a/docs/manual/src/docbook/technical-overview.xml b/docs/manual/src/docbook/technical-overview.xml index bbdd072275..af3a18e20e 100644 --- a/docs/manual/src/docbook/technical-overview.xml +++ b/docs/manual/src/docbook/technical-overview.xml @@ -2,586 +2,582 @@ Technical Overview -
Runtime Environment - - Spring Security 3.0 requires a Java 5.0 Runtime Environment or higher. - As Spring Security aims to operate in a self-contained manner, there is no need - to place any special configuration files into your Java Runtime - Environment. In particular, there is no need to configure a special - Java Authentication and Authorization Service (JAAS) policy file or - place Spring Security into common classpath locations. - - Similarly, if you are using an EJB Container or Servlet - Container there is no need to put any special configuration files - anywhere, nor include Spring Security in a server classloader. All the required - files will be contained within your application. - - This 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. + Spring Security 3.0 requires a Java 5.0 Runtime Environment or higher. As Spring Security + aims to operate in a self-contained manner, there is no need to place any special + configuration files into your Java Runtime Environment. In particular, there is no need to + configure a special Java Authentication and Authorization Service (JAAS) policy file or place + Spring Security into common classpath locations. + Similarly, if you are using an EJB Container or Servlet Container there is no need to put + any special configuration files anywhere, nor include Spring Security in a server classloader. + All the required files will be contained within your application. + This 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 + Core Components - - Let's explore some of the most important shared components in - Spring Security. Components are considered "shared" if they are - central to the framework and the framework cannot operate without - them. These Java types represent the building blocks of the remaining - system, so it's important to understand that they're there, even if - you don't need to directly interact with them. - - + In Spring Security 3.0, the contents of the spring-security-core jar + were stripped down to the bare minimum. It no longer contains any code related to + web-application security, LDAP or namespace configuration. We'll take a look here at some of + the Java types that you'll find in the core module. They represent the building blocks of the + the framework, so if you ever need to go beyond a simple namespace configuration then it's + important that you understand what they are, even if you don't actually need to directly + interact with them.
- - SecurityContextHolder, SecurityContext and Authentication Objects - - The most fundamental object is - SecurityContextHolder. This is where we store - details of the present security context of the application, which - includes details of the principal currently using the application. By - default the SecurityContextHolder uses a - ThreadLocal to store these details, which means - that the security context is always available to methods in the same - thread of execution, even if the security context is not explicitly - passed around as an argument to those methods. Using a - ThreadLocal in this way is quite safe if care is - taken to clear the thread after the present principal's request is - processed. Of course, Spring Security takes care of this for you - automatically so there is no need to worry about it. + SecurityContextHolder, SecurityContext and Authentication Objects + The most fundamental object is SecurityContextHolder. This is + where we store details of the present security context of the application, which includes + details of the principal currently using the application. By default the + SecurityContextHolder uses a ThreadLocal to + store these details, which means that the security context is always available to methods in + the same thread of execution, even if the security context is not explicitly passed around + as an argument to those methods. Using a ThreadLocal in this way is quite + safe if care is taken to clear the thread after the present principal's request is + processed. Of course, Spring Security takes care of this for you automatically so there is + no need to worry about it. + Some applications aren't entirely suitable for using a ThreadLocal, + because of the specific way they work with threads. For example, a Swing client might want + all threads in a Java Virtual Machine to use the same security context. For this situation + you would use the SecurityContextHolder.MODE_GLOBAL. Other applications + might want to have threads spawned by the secure thread also assume the same security + identity. This is achieved by using + SecurityContextHolder.MODE_INHERITABLETHREADLOCAL. You can change the + mode from the default SecurityContextHolder.MODE_THREADLOCAL in two ways. + The first is to set a system property. Alternatively, call a static method on + SecurityContextHolder. Most applications won't need to change from + the default, but if you do, take a look at the JavaDocs for + SecurityContextHolder to learn more. +
+ Obtaining information about the current user + Inside the SecurityContextHolder we store details of the + principal currently interacting with the application. Spring Security uses an + Authentication object to represent this information. You + won't normally need to create an Authentication object + yourself, but it is fairly common for users to query the + Authentication object. You can use the following code + block - from anywhere in your application - to obtain the name of the currently + authenticated user, for example: + +Object principal = SecurityContextHolder.getContext().getAuthentication().getPrincipal(); - Some applications aren't entirely suitable for using a - ThreadLocal, because of the specific way they work - with threads. For example, a Swing client might want all threads in a - Java Virtual Machine to use the same security context. For this - situation you would use the - SecurityContextHolder.MODE_GLOBAL. Other - applications might want to have threads spawned by the secure thread - also assume the same security identity. This is achieved by using - SecurityContextHolder.MODE_INHERITABLETHREADLOCAL. - You can change the mode from the default - SecurityContextHolder.MODE_THREADLOCAL in two ways. - The first is to set a system property. Alternatively, call a static - method on SecurityContextHolder. Most applications - won't need to change from the default, but if you do, take a look at - the JavaDocs for SecurityContextHolder to learn - more. - - Inside the SecurityContextHolder we store - details of the principal currently interacting with the application. - Spring Security uses an Authentication object to - represent this information. Whilst you won't normally need to create - an Authentication object yourself, it is fairly - common for users to query the Authentication - object. You can use the following code block - from anywhere in your - application - to obtain the name of the authenticated user, for example: - - -Object obj = SecurityContextHolder.getContext().getAuthentication().getPrincipal(); - -if (obj instanceof UserDetails) { - String username = ((UserDetails)obj).getUsername(); +if (principal instanceof UserDetails) { + String username = ((UserDetails)principal).getUsername(); } else { - String username = obj.toString(); + String username = principal.toString(); } - - The above code introduces a number of interesting relationships - and key objects. First, you will notice that there is an intermediate - object between SecurityContextHolder and - Authentication. The - SecurityContextHolder.getContext() method is - actually returning a SecurityContext. - - - + The object returned by the call to getContext() is an + instance of the SecurityContext interface. This is the + object that is kept in thread-local storage. Most authentication mechanisms withing Spring + Security return an instance of UserDetails as the principal + as we'll see below. +
-
The UserDetailsService - - Another item to note from the above code fragment is that you - can obtain a principal from the Authentication - object. The principal is just an Object. Most of - the time this can be cast into a UserDetails - object. UserDetails is a central interface in - Spring Security. It represents a principal, but in an extensible and - application-specific way. Think of UserDetails as - the adapter between your own user database and what Spring Security - needs inside the SecurityContextHolder. Being a - representation of something from your own user database, quite often - you will cast the UserDetails to the original - object that your application provided, so you can call - business-specific methods (like getEmail(), - getEmployeeNumber() and so on). - - By now you're probably wondering, so when do I provide a - UserDetails object? How do I do that? I thought you - said this thing was declarative and I didn't need to write any Java - code - what gives? The short answer is that there is a special - interface called UserDetailsService. The only - method on this interface accepts a String-based - username argument and returns a UserDetails. Most - authentication providers that ship with Spring Security delegate to a - UserDetailsService as part of the authentication - process. The UserDetailsService is used to build - the Authentication object that is stored in the - SecurityContextHolder. The good news is that we - provide a number of UserDetailsService - implementations, including one that uses an in-memory map and another - that uses JDBC. Most users tend to write their own, though, with such - implementations often simply sitting on top of an existing Data Access - Object (DAO) that represents their employees, customers, or other - users of the enterprise application. Remember the advantage that - whatever your UserDetailsService returns can always be obtained from - the SecurityContextHolder, as per the above code - fragment. + Another item to note from the above code fragment is that you can obtain a principal + from the Authentication object. The principal is just an + Object. Most of the time this can be cast into a + UserDetails object. + UserDetails is a central interface in Spring Security. It + represents a principal, but in an extensible and application-specific way. Think of + UserDetails as the adapter between your own user database + and what Spring Security needs inside the SecurityContextHolder. + Being a representation of something from your own user database, quite often you will cast + the UserDetails to the original object that your application + provided, so you can call business-specific methods (like getEmail(), + getEmployeeNumber() and so on). + By now you're probably wondering, so when do I provide a + UserDetails object? How do I do that? I thought you said + this thing was declarative and I didn't need to write any Java code - what gives? The short + answer is that there is a special interface called + UserDetailsService. The only method on this interface + accepts a String-based username argument and returns a + UserDetails. Most authentication providers that ship with + Spring Security delegate to a UserDetailsService as part of + the authentication process. The UserDetailsService is used to + build the Authentication object that is stored in the + SecurityContextHolder. The good news is that we provide a number of + UserDetailsService implementations, including one that uses + an in-memory map and another that uses JDBC. Most users tend to write their own, though, + with their implementations often simply sitting on top of an existing Data Access Object + (DAO) that represents their employees, customers, or other users of the enterprise + application. Remember the advantage that whatever your UserDetailsService returns can always + be obtained from the SecurityContextHolder, as per the above code + fragment.
- -
GrantedAuthority - - Besides the principal, another important method provided by - Authentication is - getAuthorities(). This method provides an array of - GrantedAuthority objects. A - GrantedAuthority is, not surprisingly, an authority - that is granted to the principal. Such authorities are usually - "roles", such as ROLE_ADMINISTRATOR or - ROLE_HR_SUPERVISOR. These roles are later on - configured for web authorization, method authorization and domain - object authorization. Other parts of Spring Security are capable of - interpreting these authorities, and expect them to be present. - GrantedAuthority objects are usually loaded by the - UserDetailsService. - - Usually the GrantedAuthority objects are - application-wide permissions. They are not specific to a given domain - object. Thus, you wouldn't likely have a - GrantedAuthority to represent a permission to - Employee object number 54, because if there are - thousands of such authorities you would quickly run out of memory (or, - at the very least, cause the application to take a long time to - authenticate a user). Of course, Spring Security is expressly designed - to handle this common requirement, but you'd instead use the project's - domain object security capabilities for this purpose. + Besides the principal, another important method provided by + Authentication is getAuthorities(). This + method provides an array of GrantedAuthority objects. A + GrantedAuthority is, not surprisingly, an authority that is + granted to the principal. Such authorities are usually "roles", such as + ROLE_ADMINISTRATOR or ROLE_HR_SUPERVISOR. These + roles are later on configured for web authorization, method authorization and domain object + authorization. Other parts of Spring Security are capable of interpreting these authorities, + and expect them to be present. GrantedAuthority objects are + usually loaded by the UserDetailsService. + Usually the GrantedAuthority objects are application-wide + permissions. They are not specific to a given domain object. Thus, you wouldn't likely have + a GrantedAuthority to represent a permission to + Employee object number 54, because if there are thousands of such + authorities you would quickly run out of memory (or, at the very least, cause the + application to take a long time to authenticate a user). Of course, Spring Security is + expressly designed to handle this common requirement, but you'd instead use the project's + domain object security capabilities for this purpose.
- -
- Storing the <interfacename>SecurityContext</interfacename> - Last but not least, depending on the type of application, there may need to be - a strategy in place to store the security context between user operations. - In a typical web application, for example, a user logs in once and is subsequently identified - by their session Id. The server caches the principal information for the duration session. - In Spring Security, the responsibility for storing the SecurityContext - between requests falls to the SecurityContextPersistenceFilter, which - by default stores the context as an HttpSession attribute between HTTP - requests. It restores the context to the SecurityContextHolder for each request - and, crucially, clears the SecurityContextHolder when the request completes. - You should never interact directly with the HttpSession for security purposes. - There is simply no justification for doing so - always use the SecurityContextHolder - instead. - - - Many other types of application (for example, a stateless RESTful web service) do not use HTTP sessions and - will re-authenticate on every request. However, it is still important that the - SecurityContextPersistenceFilter is included in the - chain to make sure that the SecurityContextHolder is cleared after each request, - even if - -
-
Summary - Just to recap, the major building blocks of Spring Security - are: + Just to recap, the major building blocks of Spring Security that we've seen so far + are: + + + SecurityContextHolder, to provide access to the + SecurityContext. + + + SecurityContext, to hold the + Authentication and possibly request-specific security + information. + + + Authentication, to represent the principal in a + Spring Security-specific manner. + + + GrantedAuthority, to reflect the application-wide + permissions granted to a principal. + + + UserDetails, to provide the necessary information to + build an Authentication object from your application's DAOs or other source source of + security data. + + + UserDetailsService, to create a + UserDetails when passed in a + String-based username (or certificate ID or the like). + + + Now that you've gained an understanding of these repeatedly-used components, let's take + a closer look at the process of authentication. +
+
+
+ + Authentication + + Spring Security can participate in many different authentication environments. While we + recommend people use Spring Security for authentication and not integrate with existing + Container Managed Authentication, it is nevertheless supported - as is integrating with your + own proprietary authentication system. +
+ What is authentication in Spring Security? + Let's consider a standard authentication scenario that everyone is familiar with. + + A user is prompted to log in with a username and password. + + + The system (successfully) verifies that the password is correct for the + username. + + + The context information for that user is obtained (their list of roles and so + on). + + + A security context is established for the user + + + The user proceeds, potentially to perform some operation which is potentially + protected by an access control mechanism which checks the required permissions for the + operation against the current security context information. + + The first three items constitute the authentication process so we'll take a + look at how these take place within Spring Security. + + The username and password are obtained and combined into an instance of + UsernamePasswordAuthenticationToken (an instance of the + Authentication interface, which we saw + earlier). + + + The token is passed to an instance of + AuthenticationManager for validation. + + + The AuthenticationManager returns a fully populated + Authentication instance on successful + authentication. + + + The security context is established by calling + SecurityContextHolder.getContext().setAuthentication(...), passing in + the returned authentication object. + + From that point on, the user is considered to be authenticated. Let's look at + some code as an + example.import org.springframework.security.authentication.*; +import org.springframework.security.core.*; +import org.springframework.security.core.authority.GrantedAuthorityImpl; +import org.springframework.security.core.context.SecurityContextHolder; - - - SecurityContextHolder, to provide any - type access to the SecurityContext. - +public class AuthenticationExample { + private static AuthenticationManager am = new SampleAuthenticationManager(); - - SecurityContext, to hold the - Authentication and possibly request-specific - security information. - + public static void main(String[] args) throws Exception { + BufferedReader in = new BufferedReader(new InputStreamReader(System.in)); - - SecurityContextPersistenceFilter, to - store the SecurityContext (typically in the - HttpSession) between web requests. - + while(true) { + System.out.println("Please enter your username:"); + String name = in.readLine(); + System.out.println("Please enter your password:"); + String password = in.readLine(); + try { + Authentication request = new UsernamePasswordAuthenticationToken(name, password); + Authentication result = am.authenticate(request); + SecurityContextHolder.getContext().setAuthentication(result); + break; + } catch(AuthenticationException e) { + System.out.println("Authentication failed: " + e.getMessage()); + } + } + System.out.println("Successfully authenticated. Security context contains: " + + SecurityContextHolder.getContext().getAuthentication()); + } +} - - Authentication, to represent the - principal in a Spring Security-specific manner. - +class SampleAuthenticationManager implements AuthenticationManager { + static final List<GrantedAuthority> AUTHORITIES = new ArrayList<GrantedAuthority>(); - - GrantedAuthority, to reflect the - application-wide permissions granted to a principal. - + static { + AUTHORITIES.add(new GrantedAuthorityImpl("ROLE_USER")); + } - - UserDetails, to provide the necessary - information to build an Authentication object from your - application's DAOs. - - - - UserDetailsService, to create a - UserDetails when passed in a - String-based username (or certificate ID or - alike). - - - - Now that you've gained an understanding of these repeatedly-used - components, let's take a closer look at the process of - authentication. + public Authentication authenticate(Authentication auth) throws AuthenticationException { + if (auth.getName().equals(auth.getCredentials())) { + return new UsernamePasswordAuthenticationToken(auth.getName(), + auth.getCredentials(), AUTHORITIES); + } + throw new BadCredentialsException("Bad Credentials"); + } +}Here + we have written a little program that asks the user to enter a username and password + and performs the above sequence. The AuthenticationManager which + we've implemented here will authenticate any user whose username and password are the same. + It assigns a single role to every user. The output from the above will be something + like: +Please enter your username: +bob +Please enter your password: +password +Authentication failed: Bad Credentials +Please enter your username: +bob +Please enter your password: +bob +Successfully authenticated. Security context contains: \ + org.springframework.security.authentication.UsernamePasswordAuthenticationToken@441d0230: \ + Principal: bob; Password: [PROTECTED]; \ + Authenticated: true; Details: null; \ + Granted Authorities: ROLE_USER + + Note that you don't normally need to write any code like this. The process will normally + occur internally, in a web authentication filter for example. We've just included the code + here to show that the question of what actually constitutes authentication in Spring Security + has quite a simple answer. A user is authenticated when the + SecurityContextHolder contains a fully populated + Authentiation object. +
+ Setting the SecurityContextHolder Contents Directly + In fact, Spring Security doesn't mind how you put the + Authentication object inside the + SecurityContextHolder. The only critical requirement is that the + SecurityContextHolder contains an + Authentication that represents a principal before the + AbstractSecurityInterceptor (which we'll see more about later) + needs to authorize a user operation. + You can (and many users do) write their own filters or MVC controllers to provide + interoperability with authentication systems that are not based on Spring Security. For + example, you might be using Container-Managed Authentication which makes the current user + available from a ThreadLocal or JNDI location. Or you might work for a company that has a + legacy proprietary authentication system, which is a corporate "standard" over which you + have little control. In situations like this it's quite easy to get Spring Security to + work, and still provide authorization capabilities. All you need to do is write a filter + (or equivalent) that reads the third-party user information from a location, build a + Spring Security-specific Authentication object, and put it + onto the SecurityContextHolder. +
+
+ The <interfacename>AuthenticationManager</interfacename> + The AuthenticationManager is just an interface, so the + implementation can be anything we choose, but how does it work in practice. What if we + need to check multiple authentication databases? The default implementation in Spring + Security is called ProviderManager and rather than handling the + authentication request itself, it delegates to a list of configured + AuthenticationProviders, each of which is queried in turn to see + if it can perform the authentication. Each provider will either throw an exception or + return a fully populated Authentication object. Remember + our good friends, UserDetails and + UserDetailsService? If not, head back to the previous + section and refresh your memory. Most AuthenticationProviders will + ask a UserDetailsService to provide a + UserDetails object. The resulting + UserDetails object - and particularly the + GrantedAuthoritys it contains - will be used when building the fully + populated Authentication object.
-
- -
- Authentication - - As mentioned in the beginning of this reference guide, Spring - Security can participate in many different authentication - environments. Whilst we recommend people use Spring Security for - authentication and not integrate with existing Container Managed - Authentication, it is nevertheless supported - as is integrating with - your own proprietary authentication system. Let's first explore - authentication from the perspective of Spring Security managing web - security entirely on its own, which is illustrative of the most - complex and most common situation. - - Consider a typical web application's authentication - process: - - - - You visit the home page, and click on a link. - - - - A request goes to the server, and the server decides that - you've asked for a protected resource. - - - - As you're not presently authenticated, the server sends back - a response indicating that you must authenticate. The response - will either be an HTTP response code, or a redirect to a - particular web page. - - - - Depending on the authentication mechanism, your browser will - either redirect to the specific web page so that you can fill out - the form, or the browser will somehow retrieve your identity (eg a - BASIC authentication dialogue box, a cookie, a X509 certificate - etc). - - - - The browser will send back a response to the server. This - will either be an HTTP POST containing the contents of the form - that you filled out, or an HTTP header containing your - authentication details. - - - - Next the server will decide whether or not the presented - credentials are valid. If they're valid, the next step will - happen. If they're invalid, usually your browser will be asked to - try again (so you return to step two above). - - - - The original request that you made to cause the - authentication process will be retried. Hopefully you've - authenticated with sufficient granted authorities to access the - protected resource. If you have sufficient access, the request - will be successful. Otherwise, you'll receive back an HTTP error - code 403, which means "forbidden". - - - - Spring Security has distinct classes responsible for most of the - steps described above. The main participants (in the order that they - are used) are the ExceptionTranslationFilter, an - AuthenticationEntryPoint, an authentication - mechanism, and an AuthenticationProvider. - -
- ExceptionTranslationFilter - ExceptionTranslationFilter is a Spring - Security filter that has responsibility for detecting any Spring - Security exceptions that are thrown. Such exceptions will generally be - thrown by an AbstractSecurityInterceptor, which is - the main provider of authorization services. We will discuss - AbstractSecurityInterceptor in the next section, - but for now we just need to know that it produces Java exceptions and - knows nothing about HTTP or how to go about authenticating a - principal. Instead the ExceptionTranslationFilter - offers this service, with specific responsibility for either returning - error code 403 (if the principal has been authenticated and therefore - simply lacks sufficient access - as per step seven above), or - launching an AuthenticationEntryPoint (if the - principal has not been authenticated and therefore we need to go - commence step three).
- -
- AuthenticationEntryPoint - The AuthenticationEntryPoint is responsible - for step three in the above list. As you can imagine, each web - application will have a default authentication strategy (well, this - can be configured like nearly everything else in Spring Security, but - let's keep it simple for now). Each major authentication system will - have its own AuthenticationEntryPoint - implementation, which takes actions such as described in step - three. - - After your browser decides to submit your authentication - credentials (either as an HTTP form post or HTTP header) there needs - to be something on the server that "collects" these authentication - details. By now we're at step six in the above list. In Spring - Security we have a special name for the function of collecting - authentication details from a user agent (usually a web browser), and - that name is "authentication mechanism". After the authentication - details are collected from the user agent, an - "Authentication request" object is built and then - presented to an - AuthenticationProvider. -
-
- AuthenticationProvider - The last player in the Spring Security authentication process is - an AuthenticationProvider. Quite simply, it is - responsible for taking an Authentication request - object and deciding whether or not it is valid. The provider will - either throw an exception or return a fully populated - Authentication object. Remember our good friends, - UserDetails and - UserDetailsService? If not, head back to the - previous section and refresh your memory. Most - AuthenticationProviders will ask a - UserDetailsService to provide a - UserDetails object. As mentioned earlier, most - application will provide their own - UserDetailsService, although some will be able to - use the JDBC or in-memory implementation that ships with Spring - Security. The resultant UserDetails object - and - particularly the GrantedAuthority[]s contained - within the UserDetails object - will be used when - building the fully populated Authentication - object. - After the authentication mechanism receives back the - fully-populated Authentication object, it will deem - the request valid, put the Authentication into the - SecurityContextHolder, and cause the original - request to be retried (step seven above). If, on the other hand, the - AuthenticationProvider rejected the request, the - authentication mechanism will ask the user agent to retry (step two - above). - -
- -
- Setting the SecurityContextHolder Contents Directly - Whilst this describes the typical authentication workflow, the - good news is that Spring Security doesn't mind how you put an - Authentication inside the - SecurityContextHolder. The only critical - requirement is that the SecurityContextHolder - contains an Authentication that represents a - principal before the AbstractSecurityInterceptor - needs to authorize a request. - - You can (and many users do) write their own filters or MVC - controllers to provide interoperability with authentication systems - that are not based on Spring Security. For example, you might be using - Container-Managed Authentication which makes the current user - available from a ThreadLocal or JNDI location. Or you might work for a - company that has a legacy proprietary authentication system, which is - a corporate "standard" over which you have little control. In such - situations it's quite easy to get Spring Security to work, and still - provide authorization capabilities. All you need to do is write a - filter (or equivalent) that reads the third-party user information - from a location, build a Spring Security-specific Authentication - object, and put it onto the SecurityContextHolder. It's quite easy to - do this, and it is a fully-supported integration approach. + Authentication in a Web Application + Now let's explore the situation where you are using Spring Security in a web + application (without web.xml security enabled). How is a user + authenticated and the security context established? + Consider a typical web application's authentication process: + + + You visit the home page, and click on a link. + + + A request goes to the server, and the server decides that you've asked for a + protected resource. + + + As you're not presently authenticated, the server sends back a response indicating + that you must authenticate. The response will either be an HTTP response code, or a + redirect to a particular web page. + + + Depending on the authentication mechanism, your browser will either redirect to the + specific web page so that you can fill out the form, or the browser will somehow + retrieve your identity (via a BASIC authentication dialogue box, a cookie, a X.509 + certificate etc.). + + + The browser will send back a response to the server. This will either be an HTTP + POST containing the contents of the form that you filled out, or an HTTP header + containing your authentication details. + + + Next the server will decide whether or not the presented credentials are valid. If + they're valid, the next step will happen. If they're invalid, usually your browser will + be asked to try again (so you return to step two above). + + + The original request that you made to cause the authentication process will be + retried. Hopefully you've authenticated with sufficient granted authorities to access + the protected resource. If you have sufficient access, the request will be successful. + Otherwise, you'll receive back an HTTP error code 403, which means "forbidden". + + + Spring Security has distinct classes responsible for most of the steps described above. + The main participants (in the order that they are used) are the + ExceptionTranslationFilter, an + AuthenticationEntryPoint and an authentication + mechanism, which is resposible for calling the + AuthenticationManager which we saw in the previous section. +
+ ExceptionTranslationFilter + ExceptionTranslationFilter is a Spring Security filter that has + responsibility for detecting any Spring Security exceptions that are thrown. Such + exceptions will generally be thrown by an + AbstractSecurityInterceptor, which is the main provider of + authorization services. We will discuss AbstractSecurityInterceptor + in the next section, but for now we just need to know that it produces Java exceptions and + knows nothing about HTTP or how to go about authenticating a principal. Instead the + ExceptionTranslationFilter offers this service, with specific + responsibility for either returning error code 403 (if the principal has been + authenticated and therefore simply lacks sufficient access - as per step seven above), or + launching an AuthenticationEntryPoint (if the principal has + not been authenticated and therefore we need to go commence step three). +
+
+ AuthenticationEntryPoint + The AuthenticationEntryPoint is responsible for step + three in the above list. As you can imagine, each web application will have a default + authentication strategy (well, this can be configured like nearly everything else in + Spring Security, but let's keep it simple for now). Each major authentication system will + have its own AuthenticationEntryPoint implementation, which + typically performs one of the actions described in step 3. +
+
+ Authentication Mechanism + Once your browser submits your authentication credentials (either as an HTTP form post + or HTTP header) there needs to be something on the server that collects + these authentication details. By now we're at step six in the above list. In Spring + Security we have a special name for the function of collecting authentication details from + a user agent (usually a web browser), referring to it as the authentication + mechanism. Examples are form-base login and Basic authentication. Once the + authentication details have been collected from the user agent, an + Authentication + request object is built and then presented to the + AuthenticationManager. + After the authentication mechanism receives back the fully-populated + Authentication object, it will deem the request valid, + put the Authentication into the + SecurityContextHolder, and cause the original request to be + retried (step seven above). If, on the other hand, the + AuthenticationManager rejected the request, the authentication + mechanism will ask the user agent to retry (step two above). +
+
+ Storing the <interfacename>SecurityContext</interfacename> between requests + Depending on the type of application, there may need to be a strategy in place to + store the security context between user operations. In a typical web application, a user + logs in once and is subsequently identified by their session Id. The server caches the + principal information for the duration session. In Spring Security, the responsibility for + storing the SecurityContext between requests falls to the + SecurityContextPersistenceFilter, which by default stores the + context as an HttpSession attribute between HTTP requests. It restores + the context to the SecurityContextHolder for each request and, + crucially, clears the SecurityContextHolder when the request + completes. You shouldn't interact directly with the HttpSession for + security purposes. There is simply no justification for doing so - always use the + SecurityContextHolder instead. + Many other types of application (for example, a stateless RESTful web service) do not + use HTTP sessions and will re-authenticate on every request. However, it is still + important that the SecurityContextPersistenceFilter is included in + the chain to make sure that the SecurityContextHolder is cleared + after each request. +
- -
- Secure Objects - - Spring Security uses the term "secure object" to refer to any - object that can have security (such as an authorization decision) applied to it. - The most common examples are method invocations and web requests. - - +
+ Access-Control (Authorization) in Spring Security + The main interface resposible for making access-control decisions in Spring Security is + the AccessDecisionMananger. It has a + decide method which takes an + Authentication object representing the principal requesting + access, a secure object (see below) and a list of security metadata attributes + which apply for the object (such as a list of roles which are required for access to be + granted).
Security and AOP Advice - If you're familiar with AOP, you'd be aware there are different - types of advice available: before, after, throws and around. An around - advice is very useful, because an advisor can elect whether or not to - proceed with a method invocation, whether or not to modify the - response, and whether or not to throw an exception. Spring Security - provides an around advice for method invocations as well as web - requests. We achieve an around advice for method invocations using Spring's - standard AOP support and we achieve an around advice for web requests using a - standard Filter. - - For those not familiar with AOP, the key point to understand is - that Spring Security can help you protect method invocations as well - as web requests. Most people are interested in securing method - invocations on their services layer. This is because the services - layer is where most business logic resides in current-generation J2EE - applications (for clarification, the author disapproves of this design - and instead advocates properly encapsulated domain objects together - with the DTO, assembly, facade and transparent persistence patterns, - but as use of anemic domain objects is the present mainstream approach, we'll - talk about it here). If you just need to secure method invocations to - the services layer, Spring's standard AOP (otherwise known as AOP Alliance) - will be adequate. If you need to secure domain objects directly, you - will likely find that AspectJ is worth considering. - - You can elect to perform method authorization using AspectJ or - Spring AOP, or you can elect to perform web request authorization - using filters. You can use zero, one, two or three of these approaches - together. The mainstream usage is to perform some web request - authorization, coupled with some Spring AOP method invocation - authorization on the services layer. + If you're familiar with AOP, you'd be aware there are different types of advice + available: before, after, throws and around. An around advice is very useful, because an + advisor can elect whether or not to proceed with a method invocation, whether or not to + modify the response, and whether or not to throw an exception. Spring Security provides an + around advice for method invocations as well as web requests. We achieve an around advice + for method invocations using Spring's standard AOP support and we achieve an around advice + for web requests using a standard Filter. + For those not familiar with AOP, the key point to understand is that Spring Security can + help you protect method invocations as well as web requests. Most people are interested in + securing method invocations on their services layer. This is because the services layer is + where most business logic resides in current-generation J2EE applications. If you just need + to secure method invocations in the services layer, Spring's standard AOP (otherwise known + as AOP Alliance) will be adequate. If you need to secure domain objects directly, you will + likely find that AspectJ is worth considering. + You can elect to perform method authorization using AspectJ or Spring AOP, or you can + elect to perform web request authorization using filters. You can use zero, one, two or + three of these approaches together. The mainstream usage pattern is to perform some web + request authorization, coupled with some Spring AOP method invocation authorization on the + services layer.
- -
- AbstractSecurityInterceptor - - Each secure object type supported by Spring Security has its own class, - which is a subclass of AbstractSecurityInterceptor. - Importantly, by the time the AbstractSecurityInterceptor is called, the - SecurityContextHolder will contain a valid - Authentication if the principal has been - authenticated. - - AbstractSecurityInterceptor provides a - consistent workflow for handling secure object requests, typically: - - - Look up the "configuration attributes" associated with the - present request - Submitting the secure object, current Authentication - and configuration attributes to the AccessDecisionManager for - an authorization decision - Optionally change the Authentication under which the invocation - takes place - Allow the secure object to proceed (assuming access was granted) - Call the AfterInvocationManager if configured, once the invocation - has returned. - - - -
- What are Configuration Attributes? - - A "configuration attribute" can be thought of as a String that has special meaning to the classes used by - AbstractSecurityInterceptor. They may be simple role names or have more complex meaning, depending on the - how sophisticated the AccessDecisionManager implementation is. - The AbstractSecurityInterceptor is configured with a SecurityMetadataSource which - it uses to look up the attributes for a secure object. Usually this configuration will be hidden from the user. Configuration - attributes will be entered as annotations on secured methods, or as access attributes on secured URLs (using the - namespace <intercept-url> syntax). - -
- -
- RunAsManager - Assuming AccessDecisionManager decides to - allow the request, the AbstractSecurityInterceptor - will normally just proceed with the request. Having said that, on rare - occasions users may want to replace the - Authentication inside the - SecurityContext with a different - Authentication, which is handled by the - AccessDecisionManager calling a - RunAsManager. This might be useful in reasonably - unusual situations, such as if a services layer method needs to call a - remote system and present a different identity. Because Spring - Security automatically propagates security identity from one server to - another (assuming you're using a properly-configured RMI or - HttpInvoker remoting protocol client), this may be useful. -
- -
- AfterInvocationManager - Following the secure object proceeding and then returning - - which may mean a method invocation completing or a filter chain - proceeding - the AbstractSecurityInterceptor gets - one final chance to handle the invocation. At this stage the - AbstractSecurityInterceptor is interested in - possibly modifying the return object. We might want this to happen - because an authorization decision couldn't be made "on the way in" to - a secure object invocation. Being highly pluggable, - AbstractSecurityInterceptor will pass control to an - AfterInvocationManager to actually modify the - object if needed. This class can even entirely replace the object, or - throw an exception, or not change it in any way. - - AbstractSecurityInterceptor and its related objects - are shown in . - -
- The key "secure object" model - - - - - - - - -
- -
- -
- Extending the Secure Object Model - Only developers contemplating an entirely new way of - intercepting and authorizing requests would need to use secure objects - directly. For example, it would be possible to build a new secure - object to secure calls to a messaging system. Anything that requires - security and also provides a way of intercepting a call (like the AOP - around advice semantics) is capable of being made into a secure - object. Having said that, most Spring applications will simply use the - three currently supported secure object types (AOP Alliance - MethodInvocation, AspectJ - JoinPoint and web request - FilterInvocation) with complete - transparency. +
+ Secure Objects and the <classname>AbstractSecurityInterceptor</classname> + So what is a secure object anyway? Spring Security + uses the term to refer to any object that can have security (such as an authorization + decision) applied to it. The most common examples are method invocations and web + requests. + Each supported secure object type has its own interceptor class, which is a subclass of + AbstractSecurityInterceptor. Importantly, by the time the + AbstractSecurityInterceptor is called, the + SecurityContextHolder will contain a valid + Authentication if the principal has been + authenticated. + AbstractSecurityInterceptor provides a consistent workflow for + handling secure object requests, typically: + + Look up the configuration attributes associated with the present + request + + + Submitting the secure object, current + Authentication and configuration attributes to the + AccessDecisionManager for an authorization + decision + + + Optionally change the Authentication under which + the invocation takes place + + + Allow the secure object invocation to proceed (assuming access was granted) + + + Call the AfterInvocationManager if configured, once + the invocation has returned. + + +
+ What are Configuration Attributes? + A configuration attribute can be thought of as a String that has + special meaning to the classes used by AbstractSecurityInterceptor. + They may be simple role names or have more complex meaning, depending on the how + sophisticated the AccessDecisionManager implementation is. + The AbstractSecurityInterceptor is configured with a + SecurityMetadataSource which it uses to look up the + attributes for a secure object. Usually this configuration will be hidden from the user. + Configuration attributes will be entered as annotations on secured methods, or as access + attributes on secured URLs (using the namespace <intercept-url> + syntax). +
+
+ RunAsManager + Assuming AccessDecisionManager decides to allow the + request, the AbstractSecurityInterceptor will normally just proceed + with the request. Having said that, on rare occasions users may want to replace the + Authentication inside the + SecurityContext with a different + Authentication, which is handled by the + AccessDecisionManager calling a + RunAsManager. This might be useful in reasonably unusual situations, + such as if a services layer method needs to call a remote system and present a different + identity. Because Spring Security automatically propagates security identity from one + server to another (assuming you're using a properly-configured RMI or HttpInvoker remoting + protocol client), this may be useful. +
+
+ AfterInvocationManager + Following the secure object proceeding and then returning - which may mean a method + invocation completing or a filter chain proceeding - the + AbstractSecurityInterceptor gets one final chance to handle the + invocation. At this stage the AbstractSecurityInterceptor is + interested in possibly modifying the return object. We might want this to happen because + an authorization decision couldn't be made on the way in to a secure object invocation. + Being highly pluggable, AbstractSecurityInterceptor will pass + control to an AfterInvocationManager to actually modify the object if + needed. This class can even entirely replace the object, or throw an exception, or not + change it in any way as it chooses. + AbstractSecurityInterceptor and its related objects are shown + in .
+ Security interceptors and the <quote>secure object</quote> model + + + + + +
+
+
+ Extending the Secure Object Model + Only developers contemplating an entirely new way of intercepting and authorizing + requests would need to use secure objects directly. For example, it would be possible to + build a new secure object to secure calls to a messaging system. Anything that requires + security and also provides a way of intercepting a call (like the AOP around advice + semantics) is capable of being made into a secure object. Having said that, most Spring + applications will simply use the three currently supported secure object types (AOP + Alliance MethodInvocation, AspectJ JoinPoint + and web request FilterInvocation) with complete + transparency. +
-
- \ No newline at end of file + diff --git a/docs/manual/src/resources/css/highlight.css b/docs/manual/src/resources/css/highlight.css new file mode 100644 index 0000000000..ffefef72de --- /dev/null +++ b/docs/manual/src/resources/css/highlight.css @@ -0,0 +1,35 @@ +/* + code highlight CSS resemblign the Eclipse IDE default color schema + @author Costin Leau +*/ + +.hl-keyword { + color: #7F0055; + font-weight: bold; +} + +.hl-comment { + color: #3F5F5F; + font-style: italic; +} + +.hl-multiline-comment { + color: #3F5FBF; + font-style: italic; +} + +.hl-tag { + color: #3F7F7F; +} + +.hl-attribute { + color: #7F007F; +} + +.hl-value { + color: #2A00FF; +} + +.hl-string { + color: #2A00FF; +} \ No newline at end of file diff --git a/docs/manual/src/resources/css/manual.css b/docs/manual/src/resources/css/manual.css new file mode 100644 index 0000000000..4314f6b328 --- /dev/null +++ b/docs/manual/src/resources/css/manual.css @@ -0,0 +1,59 @@ +@IMPORT url("highlight.css"); + +html { + padding: 0pt; + margin: 0pt; +} + +body { + margin-left: 10%; + margin-right: 10%; + font-family: Arial, Sans-serif; +} + +div { + margin: 0pt; +} + +p { + text-align: justify; +} + +hr { + border: 1px solid gray; + background: gray; +} + +h1,h2,h3,h4 { + color: #234623; + font-family: Arial, Sans-serif; +} + +pre { + line-height: 1.0; + color: black; +} + +pre.programlisting { + font-size: 10pt; + padding: 7pt 3pt; + border: 1pt solid black; + background: #eeeeee; + clear: both; +} + +div.table { + margin: 1em; + padding: 0.5em; + text-align: center; +} + +div.table table { + display: table; + width: 100%; +} + +div.table td { + padding-left: 7px; + padding-right: 7px; +} diff --git a/docs/manual/src/resources/images/i21-banner-rhs.jpg b/docs/manual/src/resources/images/i21-banner-rhs.jpg deleted file mode 100644 index 8b24a7736d..0000000000 Binary files a/docs/manual/src/resources/images/i21-banner-rhs.jpg and /dev/null differ diff --git a/docs/manual/src/resources/images/logo.psd b/docs/manual/src/resources/images/logo.psd deleted file mode 100644 index e02dca01d5..0000000000 Binary files a/docs/manual/src/resources/images/logo.psd and /dev/null differ diff --git a/docs/manual/src/xsl/html-custom.xsl b/docs/manual/src/xsl/html-custom.xsl new file mode 100644 index 0000000000..c23bd8a468 --- /dev/null +++ b/docs/manual/src/xsl/html-custom.xsl @@ -0,0 +1,142 @@ + + + + + + + + + + '5' + '1' + + + 1 + + + 1 + 0 + 1 + + + + images/ + .gif + + 120 + images/callouts/ + .gif + + + css/manual.css + text/css + book toc,title + + text-align: left + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Begin Google Analytics code + + + End Google Analytics code + + + + + Begin LoopFuse code + + + End LoopFuse code + + + \ No newline at end of file diff --git a/docs/manual/src/xsl/pdf-custom.xsl b/docs/manual/src/xsl/pdf-custom.xsl new file mode 100644 index 0000000000..c761e4500b --- /dev/null +++ b/docs/manual/src/xsl/pdf-custom.xsl @@ -0,0 +1,501 @@ + + + + + + + + + '1' + images/ + + + + + + + + + + + + + + + + + + + + -5em + -5em + + + + + + book toc,title + + + + + + + + + + + + + + + + + please define productname in your docbook file! + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + 0 + 0 + + + + false + + + 11 + 8 + + + 1.4 + + + + left + bold + + + pt + + + + + + + + + + + + + + + + 0.8em + 0.8em + 0.8em + + + pt + + 0.1em + 0.1em + 0.1em + + + 0.6em + 0.6em + 0.6em + + + pt + + 0.1em + 0.1em + 0.1em + + + 0.4em + 0.4em + 0.4em + + + pt + + 0.1em + 0.1em + 0.1em + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 4pt + 4pt + 4pt + 4pt + + + + 0.1pt + 0.1pt + + + + + + + + + + + + + + + + + + pt + + + + + 1em + 1em + 1em + 0.1em + 0.1em + 0.1em + + #444444 + solid + 0.1pt + 0.5em + 0.5em + 0.5em + 0.5em + 0.5em + 0.5em + + + + 1 + + #F0F0F0 + + + + 0.1em + 0.1em + 0.1em + 0.1em + 0.1em + 0.1em + + + + 0.5em + 0.5em + 0.5em + 0.1em + 0.1em + 0.1em + always + + + + + + normal + italic + + + pt + + false + 0.1em + 0.1em + 0.1em + + + + + + + + + + + figure after + example after + equation before + table before + procedure before + + + + 1 + + 0pt + + + 3 + + + + + + + + + + + + + + + + + + \ No newline at end of file