diff --git a/src/docbkx/anon-auth-provider.xml b/src/docbkx/anon-auth-provider.xml index fdc334baa7..13a44740d0 100644 --- a/src/docbkx/anon-auth-provider.xml +++ b/src/docbkx/anon-auth-provider.xml @@ -40,17 +40,17 @@ filter and authentication provider appears as follows: - <bean id="anonymousProcessingFilter" - class="org.springframework.security.providers.anonymous.AnonymousProcessingFilter"> - <property name="key"><value>foobar</value></property> - <property name="userAttribute"><value>anonymousUser,ROLE_ANONYMOUS</value></property> - </bean> - - <bean id="anonymousAuthenticationProvider" - class="org.springframework.security.providers.anonymous.AnonymousAuthenticationProvider"> - <property name="key"><value>foobar</value></property> - </bean> - + + + + + + + +]]> The key is shared between the filter and diff --git a/src/docbkx/authorization-common.xml b/src/docbkx/authorization-common.xml index 79fc96259b..2aa13f70fe 100644 --- a/src/docbkx/authorization-common.xml +++ b/src/docbkx/authorization-common.xml @@ -2,7 +2,6 @@
Authorities - As briefly mentioned in the Authentication section, all Authentication implementations are required to @@ -15,11 +14,11 @@ decisions. GrantedAuthority is an interface with only - one method: - - public String getAuthority(); - - This method allows AccessDecisionManagers to + one method: + + String getAuthority(); + + This method allows AccessDecisionManagers to obtain a precise String representation of the GrantedAuthority. By returning a representation as a String, a GrantedAuthority can @@ -58,13 +57,13 @@ AbstractSecurityInterceptor and is responsible for making final access control decisions. The AccessDecisionManager interface contains three - methods: - - public void decide(Authentication authentication, Object object, ConfigAttributeDefinition config) throws AccessDeniedException; -public boolean supports(ConfigAttribute attribute); -public boolean supports(Class clazz); - - As can be seen from the first method, the + methods: + + void decide(Authentication authentication, Object object, ConfigAttributeDefinition config) throws AccessDeniedException; + boolean supports(ConfigAttribute attribute); + boolean supports(Class clazz); + + As can be seen from the first method, the AccessDecisionManager is passed via method parameters all information that is likely to be of value in assessing an authorization decision. In particular, passing the secure @@ -115,13 +114,13 @@ public boolean supports(Class clazz); assessment of the votes. The AccessDecisionVoter interface has three - methods: - - public int vote(Authentication authentication, Object object, ConfigAttributeDefinition config); -public boolean supports(ConfigAttribute attribute); -public boolean supports(Class clazz); - - Concrete implementations return an int, with + methods: + +int vote(Authentication authentication, Object object, ConfigAttributeDefinition config); +boolean supports(ConfigAttribute attribute); +boolean supports(Class clazz); + + Concrete implementations return an int, with possible values being reflected in the AccessDecisionVoter static fields ACCESS_ABSTAIN, ACCESS_DENIED @@ -176,34 +175,36 @@ public boolean supports(Class clazz); voter included with Spring Security. It integrates with Spring Security's AclManager (discussed later). This voter is designed to have multiple instances in the same application - context, such as: + context, such as: + + + + + + + + + + + + - <bean id="aclContactReadVoter" - class="org.springframework.security.vote.BasicAclEntryVoter"> -<property name="processConfigAttribute"><value>ACL_CONTACT_READ</value></property> -<property name="processDomainObjectClass"><value>sample.contact.Contact</value></property> -<property name="aclManager"><ref local="aclManager"/></property> -<property name="requirePermission"> -<list> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.READ"/> -</list> -</property> -</bean> - -<bean id="aclContactDeleteVoter" class="org.springframework.security.vote.BasicAclEntryVoter"> -<property name="processConfigAttribute"><value>ACL_CONTACT_DELETE</value></property> -<property name="processDomainObjectClass"><value>sample.contact.Contact</value></property> -<property name="aclManager"><ref local="aclManager"/></property> -<property name="requirePermission"> -<list> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.DELETE"/> -</list> -</property> -</bean> - - In the above example, you'd define + + + + + + + + + + + +]]> + In the above example, you'd define ACL_CONTACT_READ or ACL_CONTACT_DELETE against some methods on a MethodSecurityInterceptor or @@ -251,9 +252,8 @@ public boolean supports(Class clazz); to the chapter describing the new ACL implementation.
-
After Invocation Handling - - +
+ After Invocation Handling Whilst the AccessDecisionManager is called by the AbstractSecurityInterceptor before proceeding with the secure object invocation, some applications need a way of @@ -274,7 +274,6 @@ public boolean supports(Class clazz); - Figure 5: After Invocation Implementation @@ -341,22 +340,20 @@ public boolean supports(Class clazz); Contact is all that is available before the secure object is invoked. The AclAfterInvocationProvider delivers a solution, - and is configured as follows: - - <bean id="afterAclRead" - class="org.springframework.security.afterinvocation.AclEntryAfterInvocationProvider"> -<constructor-arg> -<ref bean="aclService"/> -</constructor-arg> -<constructor-arg> -<list> - <ref local="org.springframework.security.acls.domain.BasePermission.ADMINISTRATION"/> - <ref local="org.springframework.security.acls.domain.BasePermission.READ"/> -</list> -</constructor-arg> -</bean> - - In the above example, the Contact will be + and is configured as follows: + + + + + + + + + +]]> + In the above example, the Contact will be retrieved and passed to the AclEntryAfterInvocationProvider. The provider will thrown an AccessDeniedException if one of @@ -373,22 +370,20 @@ public boolean supports(Class clazz); elements for which a principal does not have access. It never thrown an AccessDeniedException - simply silently removes the offending elements. The provider is configured as - follows: - - <bean id="afterAclCollectionRead" - class="org.springframework.security.afterinvocation.AclEntryAfterInvocationCollectionFilteringProvider"> -<constructor-arg> -<ref bean="aclService"/> -</constructor-arg> -<constructor-arg> -<list> - <ref local="org.springframework.security.acls.domain.BasePermission.ADMINISTRATION"/> - <ref local="org.springframework.security.acls.domain.BasePermission.READ"/> -</list> -</constructor-arg> -</bean> - - As you can imagine, the returned Object + follows: + + + + + + + + + +]]> + As you can imagine, the returned Object must be a Collection or array for this provider to operate. It will remove any element if the AclManager indicates the @@ -427,16 +422,18 @@ public boolean supports(Class clazz); BasicAclAfterInvocationProvider delivers a solution, and is configured as follows: - <bean id="afterAclRead" - class="org.springframework.security.afterinvocation.BasicAclEntryAfterInvocationProvider"> -<property name="aclManager"><ref local="aclManager"/></property> -<property name="requirePermission"> -<list> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.READ"/> -</list> -</property> -</bean> + + + + + + + + + +]]> In the above example, the Contact will be retrieved and passed to the @@ -455,20 +452,20 @@ public boolean supports(Class clazz); elements for which a principal does not have access. It never thrown an AccessDeniedException - simply silently removes the offending elements. The provider is configured as - follows: - - <bean id="afterAclCollectionRead" - class="org.springframework.security.afterinvocation.BasicAclEntryAfterInvocationCollectionFilteringProvider"> -<property name="aclManager"><ref local="aclManager"/></property> -<property name="requirePermission"> -<list> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/> - <ref local="org.springframework.security.acl.basic.SimpleAclEntry.READ"/> -</list> -</property> -</bean> - - As you can imagine, the returned Object + follows: + + + + + + + + + +]]> + As you can imagine, the returned Object must be a Collection or array for this provider to operate. It will remove any element if the AclManager indicates the @@ -490,11 +487,14 @@ public boolean supports(Class clazz); The following JSP fragment illustrates how to use the AuthorizeTag: - <security:authorize ifAllGranted="ROLE_SUPERVISOR"> -<td> -<A HREF="del.htm?id=<c:out value="${contact.id}"/>">Del</A> -</td> -</security:authorize> + + + +">Del + + +]]> This tag would cause the tag's body to be output if the principal has been granted ROLE_SUPERVISOR. @@ -551,13 +551,13 @@ public boolean supports(Class clazz); object. The following JSP fragment illustrates how to use the - AccessControlListTag: - - <security:accesscontrollist domainObject="${contact}" hasPermission="8,16"> -<td><A HREF="<c:url value="del.htm"><c:param name="contactId" value="${contact.id}"/></c:url>">Del</A></td> -</security:accesscontrollist> - - This tag would cause the tag's body to be output if the + AccessControlListTag: + +">Del + +]]> + This tag would cause the tag's body to be output if the principal holds either permission 16 or permission 1 for the "contact" domain object. The numbers are actually integers that are used with BasePermission bit masking. Please refer to the ACL diff --git a/src/docbkx/cas-auth-provider.xml b/src/docbkx/cas-auth-provider.xml index e9c4f52a2e..eb39449e85 100644 --- a/src/docbkx/cas-auth-provider.xml +++ b/src/docbkx/cas-auth-provider.xml @@ -3,7 +3,6 @@
Overview - JA-SIG produces an enterprise-wide single sign on system known as CAS. Unlike other initiatives, JA-SIG's Central Authentication @@ -15,22 +14,17 @@ server. You can learn more about CAS at - http://www.ja-sig.org/products/cas/. You will need - to visit this URL to download the CAS Server files. Whilst Spring - Security includes two CAS libraries in the "-with-dependencies" ZIP - file, you will still need the CAS Java Server Pages and - web.xml to customise and deploy your CAS - server. + http://www.ja-sig.org/products/cas/. You will also need + to visit this site to download the CAS Server files.
-
How CAS Works - +
+ How CAS Works - Whilst the CAS web site above contains two documents that detail + Whilst the CAS web site contains documents that detail the architecture of CAS, we present the general overview again here - within the context of Spring Security. The following refers to both - CAS 2.0 (produced by Yale) and CAS 3.0 (produced by JA-SIG), being the - versions of CAS that Spring Security supports. + within the context of Spring Security. Spring Security 2.0 supports + CAS 3. At the time of writing, the CAS server was at version 3.2. Somewhere in your enterprise you will need to setup a CAS server. The CAS server is simply a standard WAR file, so there isn't @@ -38,69 +32,27 @@ you will customise the login and other single sign on pages displayed to users. - If you are deploying CAS 2.0, you will also need to specify in - the web.xml a PasswordHandler. The - PasswordHandler has a simple method that returns a - boolean as to whether a given username and password is valid. Your - PasswordHandler implementation will need to link - into some type of backend authentication repository, such as an LDAP - server or database. - - If you are already running an existing CAS 2.0 server instance, - you will have already established a - PasswordHandler. If you do not already have a - PasswordHandler, you might prefer to use Spring - Security's CasPasswordHandler class. This class - delegates through to the standard Spring Security - AuthenticationManager, enabling you to use a - security configuration you might already have in place. You do not - need to use the CasPasswordHandler class on your - CAS server if you do not wish. Spring Security will function as a CAS - client successfully irrespective of the - PasswordHandler you've chosen for your CAS - server. - - If you are deploying CAS 3.0, you will also need to specify an + When deploying a CAS 3.2 server, you will also need to specify an AuthenticationHandler in the - deployerConfigContext.xml included with CAS. The + deployerConfigContext.xml included with CAS. The AuthenticationHandler has a simple method that returns a boolean as to whether a given set of Credentials is valid. Your AuthenticationHandler implementation will need to link into some type of backend authentication repository, such as an LDAP server or database. CAS itself includes numerous AuthenticationHandlers out of the box to assist - with this. + with this. When you download and deploy the server war file, it is set up + to successfully authenticate users who enter a password matching their + username, which is sueful for testing. - If you are already running an existing CAS 3.0 server instance, - you will have already established an - AuthenticationHandler. If you do not already have - an AuthenticationHandler, you might prefer to use - Spring Security CasAuthenticationHandler class. - This class delegates through to the standard Spring Security - AuthenticationManager, enabling you to use a - security configuration you might already have in place. You do not - need to use the CasAuthenticationHandler class on - your CAS server if you do not wish. Spring Security will function as a - CAS client successfully irrespective of the - AuthenticationHandler you've chosen for your CAS - server. - - Apart from the CAS server itself, the other key player is of + Apart from the CAS server itself, the other key players are of course the secure web applications deployed throughout your enterprise. These web applications are known as "services". There are two types of services: standard services and proxy services. A proxy service is able to request resources from other services on behalf of the user. This will be explained more fully later. - Services can be developed in a large variety of languages, due - to CAS 2.0's very light XML-based protocol. The JA-SIG CAS home page - contains a clients archive which demonstrates CAS clients in Java, - Active Server Pages, Perl, Python and others. Naturally, Java support - is very strong given the CAS server is written in Java. You do not - need to use any of CAS' client classes in applications secured by - Spring Security. This is handled transparently for you. - - The basic interaction between a web browser, CAS server and n + The basic interaction between a web browser, CAS server and a Spring Security-secured service is as follows: diff --git a/src/docbkx/channel-security.xml b/src/docbkx/channel-security.xml index c021ed77c5..c1116b9143 100644 --- a/src/docbkx/channel-security.xml +++ b/src/docbkx/channel-security.xml @@ -1,11 +1,10 @@ - + Channel Security
Overview - In addition to coordinating the authentication and authorization requirements of your application, Spring Security is also able to ensure unauthenticated web requests have certain properties. These @@ -35,37 +34,38 @@ Security provides a solution to assist with the latter.
-
Configuration - - - To use chanel security, you should define the following the filter in your application +
+ 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) + To confiure channel security explicitly, you would define the following the filter in your application context: - <bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter"> - <property name="channelDecisionManager" ref="channelDecisionManager"/> - <property name="filterInvocationDefinitionSource"> - <security:filter-invocation-definition-source path-type="regex"> - <security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/> - <security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/> - <security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/> - <security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/> - </security:filter-invocation-definition-source> - </property> - </bean> - - <bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl"> - <property name="channelProcessors"> - <list> - <ref bean="secureChannelProcessor"/> - <ref bean="insecureChannelProcessor"/> - </list> - </property> - </bean> - - <bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/> - <bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/> - +<bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter"> + <property name="channelDecisionManager" ref="channelDecisionManager"/> + <property name="filterInvocationDefinitionSource"> + <security:filter-invocation-definition-source path-type="regex"> + <security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/> + <security:intercept-url pattern="\A/acegilogin.jsp.*\" access="REQUIRES_SECURE_CHANNEL"/> + <security:intercept-url pattern="\A/j_spring_security_check.*\Z" access="REQUIRES_SECURE_CHANNEL"/> + <security:intercept-url pattern="\A/.*\Z" access="REQUIRES_INSECURE_CHANNEL"/> + </security:filter-invocation-definition-source> + </property> + </bean> + +<bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl"> + <property name="channelProcessors"> + <list> + <ref bean="secureChannelProcessor"/> + <ref bean="insecureChannelProcessor"/> + </list> + </property> +</bean> + +<bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/> +<bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/> Like FilterSecurityInterceptor, Apache Ant @@ -124,9 +124,9 @@ property is true.
-
Conclusion - - +
+ Conclusion + Once configured, using the channel security filter is very easy. Simply request pages without regard to the protocol (ie HTTP or HTTPS) or port (eg 80, 8080, 443, 8443 etc). Obviously you'll still need a diff --git a/src/docbkx/common-auth-services.xml b/src/docbkx/common-auth-services.xml index f5a6c9156c..35fb988462 100644 --- a/src/docbkx/common-auth-services.xml +++ b/src/docbkx/common-auth-services.xml @@ -1,9 +1,10 @@ - + Common Authentication Services
- Mechanisms, Providers and Entry Points - + + Mechanisms, Providers and Entry Points + If you're using Spring Security-provided authentication approaches, you'll usually need to configure a web filter, together @@ -20,15 +21,15 @@ this: - filterChainProxy - org.springframework.web.filter.DelegatingFilterProxy - + + filterChainProxy + org.springframework.web.filter.DelegatingFilterProxy + - - filterChainProxy - /* - ]]> + + filterChainProxy + /* +]]> The above declarations will cause every web request to be passed @@ -184,21 +185,22 @@ header or HTTP redirect in order to start authentication. Continuing on with our earlier example: - <bean id="exceptionTranslationFilter" - class="org.springframework.security.ui.ExceptionTranslationFilter"> -<property name="authenticationEntryPoint"><ref local="authenticationProcessingFilterEntryPoint"/></property> -<property name="accessDeniedHandler"> -<bean class="org.springframework.security.ui.AccessDeniedHandlerImpl"> - <property name="errorPage" value="/accessDenied.jsp"/> -</bean> -</property> -</bean> + + + + + + + + -<bean id="authenticationProcessingFilterEntryPoint" - class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint"> -<property name="loginFormUrl"><value>/acegilogin.jsp</value></property> -<property name="forceHttps"><value>false</value></property> -</bean> + + + < value="false"/> +]]> Notice that the ExceptionTranslationFilter requires two collaborators. The first, @@ -270,9 +272,8 @@ that, Spring Security does include a couple of useful base implementations, which we'll look at below. -
In-Memory Authentication - - +
+ In-Memory Authentication Whilst it is easy to use create a custom UserDetailsService implementation that extracts information from a persistence engine of choice, many applications @@ -281,52 +282,34 @@ Security, when you don't really want to spend time configuring databases or writing UserDetailsService implementations. For this sort of situation, a simple option is to - configure the InMemoryDaoImpl - implementation: - - <bean id="inMemoryDaoImpl" - class="org.springframework.security.userdetails.memory.InMemoryDaoImpl"> -<property name="userMap"> -<value> - rod=koala,ROLE_TELLER,ROLE_SUPERVISOR - dianne=emu,ROLE_TELLER - scott=wombat,ROLE_TELLER - peter=opal,disabled,ROLE_TELLER -</value> -</property> -</bean> - - In the above example, the userMap property - contains each of the usernames, passwords, a list of granted - authorities and an optional enabled/disabled keyword. Commas are - used to delimit each token. The username must appear to the left of - the equals sign, and the password must be the first token to the - right of the equals sign. The enabled and - disabled keywords (case insensitive) may appear - in the second or any subsequent token. Any remaining tokens are - treated as granted authorities, which are created as - GrantedAuthorityImpl objects (this is just for - your reference - most applications don't need custom - GrantedAuthority implementations, so using the - default implementation in this manner is just fine). Note that if a - user has no password and/or no granted authorities, the user will - not be created in the in-memory authentication repository. - - InMemoryDaoImpl also offers a - setUserProperties(Properties) method, which - allows you to externalise the - java.util.Properties in another Spring configured - bean or an external properties file. You might like to use Spring's - PropertiesFactoryBean, which is useful for - loading such external properties files. This setter might prove - useful for simple applications that have a larger number of users, - or deployment-time configuration changes, but do not wish to use a - full database for handling authentication details. + use the user-service element from the security + namespace: + + + + + ]]> + + This also suppots the use of an external properties file: + + ]]> + + The properties file should contain entries in the form + + username=password,grantedAuthority[,grantedAuthority][,enabled|disabled] + + For example + + jimi=jimispassword,ROLE_USER,ROLE_ADMIN,enabled + bob=bobspassword,ROLE_USER,enabled + +
-
JDBC Authentication - - +
+ JDBC Authentication Spring Security also includes a UserDetailsService that can obtain authentication information from a JDBC data source. Internally Spring JDBC is used, @@ -338,16 +321,18 @@ JdbcDaoImpl, an example configuration is shown below: - <bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"> -<property name="driverClassName"><value>org.hsqldb.jdbcDriver</value></property> -<property name="url"><value>jdbc:hsqldb:hsql://localhost:9001</value></property> -<property name="username"><value>sa</value></property> -<property name="password"><value></value></property> -</bean> + + + + + + + -<bean id="jdbcDaoImpl" class="org.springframework.security.userdetails.jdbc.JdbcDaoImpl"> -<property name="dataSource"><ref bean="dataSource"/></property> -</bean> + + + ]]> You can use different relational database management systems by modifying the DriverManagerDataSource shown @@ -372,8 +357,8 @@
-
Concurrent Session Handling - +
+ Concurrent Session Handling Spring Security is able to prevent a principal from concurrently authenticating to the same application more than a specified number of @@ -411,40 +396,42 @@ ConcurrentSessionControllerImpl and refer to it from your ProviderManager bean: - <bean id="authenticationManager" - class="org.springframework.security.providers.ProviderManager"> -<property name="providers"> -<!-- your providers go here --> -</property> -<property name="sessionController"><ref bean="concurrentSessionController"/></property> -</bean> + + + + + + + -<bean id="concurrentSessionController" - class="org.springframework.security.concurrent.ConcurrentSessionControllerImpl"> -<property name="maximumSessions"><value>1</value></property> -<property name="sessionRegistry"><ref local="sessionRegistry"/></property> -</bean> - -<bean id="sessionRegistry" class="org.springframework.security.concurrent.SessionRegistryImpl"/> + + + + + + +]]>
-
Authentication Tag Libraries +
+ Authentication Tag Libraries - AuthenticationTag is used to simply output a - property of the current principal's - Authentication.getPrincipal() object to the web + property of the current Authentication object to the web page. The following JSP fragment illustrates how to use the AuthenticationTag: - <security:authentication operation="username"/> + <security:authentication property="principal.username"/> This tag would cause the principal's name to be output. Here we are assuming the Authentication.getPrincipal() is a UserDetails object, which is generally the case - when using the typical - DaoAuthenticationProvider. + when using one of Spring Security's stadard AuthenticationProvider + implementations.
\ No newline at end of file diff --git a/src/docbkx/dao-auth-provider.xml b/src/docbkx/dao-auth-provider.xml index aad6d85fdf..709bf85f7a 100644 --- a/src/docbkx/dao-auth-provider.xml +++ b/src/docbkx/dao-auth-provider.xml @@ -1,9 +1,10 @@ -DAO Authentication Provider + +DAO Authentication Provider + +
+ Overview -
Overview - - Spring Security includes a production-quality AuthenticationProvider implementation called DaoAuthenticationProvider. This authentication @@ -20,8 +21,8 @@ object.
-
Configuration - +
+ Configuration Aside from adding DaoAuthenticationProvider to your ProviderManager list (as discussed at the start of this part of the @@ -29,12 +30,15 @@ configured to present a UsernamePasswordAuthenticationToken, the configuration of the provider itself is rather simple: - <bean id="daoAuthenticationProvider" - class="org.springframework.security.providers.dao.DaoAuthenticationProvider"> - <property name="userDetailsService"><ref bean="inMemoryDaoImpl"/></property> - <property name="saltSource"><ref bean="saltSource"/></property> - <property name="passwordEncoder"><ref bean="passwordEncoder"/></property> - </bean> + + + + + + ]]> + The PasswordEncoder and SaltSource are optional. A @@ -65,31 +69,26 @@ A usable caching implementation is also provided, EhCacheBasedUserCache, which is configured as follows: + + + + + + + + - <bean id="daoAuthenticationProvider" - class="org.springframework.security.providers.dao.DaoAuthenticationProvider"> - <property name="userDetailsService"><ref bean="userDetailsService"/></property> - <property name="userCache"><ref bean="userCache"/></property> - </bean> - - <bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"> - <property name="configLocation"> - <value>classpath:/ehcache-failsafe.xml</value> - </property> - </bean> - - <bean id="userCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean"> - <property name="cacheManager"> - <ref local="cacheManager"/> - </property> - <property name="cacheName"> - <value>userCache</value> - </property> - </bean> - - <bean id="userCache" class="org.springframework.security.providers.dao.cache.EhCacheBasedUserCache"> - <property name="cache"><ref local="userCacheBackend"/></property> - </bean> + + + + + + + +]]> + All Spring Security EH-CACHE implementations (including EhCacheBasedUserCache) require an EH-CACHE diff --git a/src/docbkx/digest-authentication.xml b/src/docbkx/digest-authentication.xml index 4152068f36..029ee907c1 100644 --- a/src/docbkx/digest-authentication.xml +++ b/src/docbkx/digest-authentication.xml @@ -33,10 +33,11 @@ This is a value the server generates. Spring Security's nonce adopts the following format: - base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key)) + + base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key)) - expirationTime: The date and time when the nonce expires, expressed in milliseconds - key: A private key to prevent modification of the nonce token + expirationTime: The date and time when the nonce expires, expressed in milliseconds + key: A private key to prevent modification of the nonce token The DigestProcessingFilterEntryPoint has a @@ -89,18 +90,20 @@ collaborators: - <bean id="digestProcessingFilter" class="org.springframework.security.ui.digestauth.DigestProcessingFilter"> - <property name="userDetailsService"><ref local="jdbcDaoImpl"/></property> - <property name="authenticationEntryPoint"><ref local="digestProcessingFilterEntryPoint"/></property> - <property name="userCache"><ref local="userCache"/></property> - </bean> - - <bean id="digestProcessingFilterEntryPoint" - class="org.springframework.security.ui.digestauth.DigestProcessingFilterEntryPoint"> - <property name="realmName"><value>Contacts Realm via Digest Authentication</value></property> - <property name="key"><value>acegi</value></property> - <property name="nonceValiditySeconds"><value>10</value></property> - </bean> + + + + + + + + + + +]]> diff --git a/src/docbkx/form-authentication.xml b/src/docbkx/form-authentication.xml index c62e426b71..3fdf4b2974 100644 --- a/src/docbkx/form-authentication.xml +++ b/src/docbkx/form-authentication.xml @@ -20,14 +20,14 @@ monitored by the filter (by default j_spring_security_check). You should add an AuthenticationProcessingFilter to you application context: - - <bean id="authenticationProcessingFilter" - class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter"> - <property name="authenticationManager" ref="authenticationManager"/> - <property name="authenticationFailureUrl" value="/acegilogin.jsp?login_error=1"/> - <property name="defaultTargetUrl" value="/"/> - <property name="filterProcessesUrl" value="/j_spring_security_check"/> - </bean> + + + + + + ]]> The configured AuthenticationManager diff --git a/src/docbkx/jaas-auth-provider.xml b/src/docbkx/jaas-auth-provider.xml index 844948c62d..c5213744a6 100644 --- a/src/docbkx/jaas-auth-provider.xml +++ b/src/docbkx/jaas-auth-provider.xml @@ -21,19 +21,16 @@ Let’s assume we have a JAAS login configuration file, /WEB-INF/login.conf, with the following - contents: - - JAASTest { - sample.SampleLoginModule required; - }; - + contents: + +JAASTest { + sample.SampleLoginModule required; +}; Like all Spring Security beans, the JaasAuthenticationProvider is configured via the application context. The following definitions would correspond to the - above JAAS login configuration file: - - - @@ -50,8 +47,7 @@ -]]> - +]]> The CallbackHandlers and AuthorityGranters are discussed below. @@ -99,7 +95,6 @@
JAAS AuthorityGranter - JAAS works with principals. Even "roles" are represented as principals in JAAS. Spring Security, on the other hand, works with Authentication objects. Each diff --git a/src/docbkx/ldap-auth-provider.xml b/src/docbkx/ldap-auth-provider.xml index 76daa564e3..ebceeb80aa 100644 --- a/src/docbkx/ldap-auth-provider.xml +++ b/src/docbkx/ldap-auth-provider.xml @@ -69,7 +69,7 @@ url attribute: + ]]> @@ -85,7 +85,7 @@ url attribute: + ]]> Here we've specified that the root DIT of the directory should be @@ -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 @@ -112,8 +112,8 @@ 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,7 @@ 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 @@ -329,30 +329,31 @@ A typical configuration, using some of the beans we've discussed here, might look like this: - - - - - + + + - - - - uid={0},ou=people - - - - - - - - - + + + + + uid={0},ou=people + + + + + + + + + + ]]> This would set up the provider to access an LDAP server with URL @@ -370,14 +371,12 @@ (uid=<user-login-name>) for use instead of the DN-pattern (or in addition to it), you would configure the following bean - - - - - - + + + ]]> and use it by setting the authenticator's diff --git a/src/docbkx/namespace-config.xml b/src/docbkx/namespace-config.xml index 3ed561232d..0a1f91b4c7 100644 --- a/src/docbkx/namespace-config.xml +++ b/src/docbkx/namespace-config.xml @@ -141,15 +141,15 @@ /* ]]> - This provides a hook into the Spring Security web infrastructure. You can find more details + This provides a hook into the Spring Security web infrastructure. . You're then ready to start editing your application context file. Web security services are configured using the <http> element.
-
+
A Minimal <literal><http></literal>Configuration @@ -206,7 +206,7 @@ login page, but the namespace offers plenty of options to allow you to customize this kind of thing. -
+
What does <literal>auto-config</literal> Include? The auto-config attribute, as we have used it above, is just a @@ -281,13 +281,13 @@ Often your password data will be encoded using a hashing algorithm. This is supported by the <password-encoder> element. With SHA encoded passwords, the original authentication provider configuration would look like this: - - - - - - + + + + + + + ]]> @@ -296,9 +296,9 @@ Ideally you would want to use a randomly generated salt value for each user, but you can use any property of the 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 Security's PasswordEncoder @@ -306,5 +306,35 @@
+
+ Adding HTTP/HTTPS Channel Security + If your application supports both HTTP and HTTPS, and you require that particular URLs can only be accessed over HTTPS, then this is + directly supported using the requires-channel attribute on <intercept-url>: + + + + ... +]]> + + With this configuration in place, if a user attempts to access anything matching the "/secure/**" + pattern using HTTP, they will first be redirected 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: + + + ... + + + +]]> + + You can find a more in-depth discussion of channel security in . + +
\ No newline at end of file diff --git a/src/docbkx/remember-me-authentication.xml b/src/docbkx/remember-me-authentication.xml index faff0f012b..5aa21a7443 100644 --- a/src/docbkx/remember-me-authentication.xml +++ b/src/docbkx/remember-me-authentication.xml @@ -25,13 +25,13 @@ via hooks in the AbstractProcessingFilter superclass. The hooks will invoke a concrete RememberMeServices at the appropriate times. The - interface looks like this: - - public Authentication autoLogin(HttpServletRequest request, HttpServletResponse response); - public void loginFail(HttpServletRequest request, HttpServletResponse response); - public void loginSuccess(HttpServletRequest request, HttpServletResponse response, Authentication successfulAuthentication); - - Please refer to JavaDocs for a fuller discussion on what 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); + + Please refer to JavaDocs for a fuller discussion on what the methods do, although note at this stage AbstractProcessingFilter only calls the loginFail() and loginSuccess() @@ -53,12 +53,13 @@ the browser upon successful interactive authentication, with that cookie being composed as follows: - base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key)) - - username: As identifiable to TokenBasedRememberMeServices.getUserDetailsService() - password: That matches the relevant UserDetails retrieved from TokenBasedRememberMeServices.getUserDetailsService() - 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 + +base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key)) + +username: As identifiable to TokenBasedRememberMeServices.getUserDetailsService() +password: That matches the relevant UserDetails retrieved from TokenBasedRememberMeServices.getUserDetailsService() +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 @@ -90,21 +91,22 @@ remember-me services are as follows: - <bean id="rememberMeProcessingFilter" - class="org.springframework.security.ui.rememberme.RememberMeProcessingFilter"> - <property name="rememberMeServices"><ref local="rememberMeServices"/></property> - </bean> + + + - <bean id="rememberMeServices" class="org.springframework.security.ui.rememberme.TokenBasedRememberMeServices"> - <property name="userDetailsService"><ref local="jdbcDaoImpl"/></property> - <property name="key"><value>springRocks</value></property> - </bean> - - <bean id="rememberMeAuthenticationProvider" - class="org.springframework.security.providers.rememberme.RememberMeAuthenticationProvider"> - <property name="key"><value>springRocks</value></property> - </bean> + + + + + + + +]]> Don't forget to add your RememberMeServices implementation to your AuthenticationProcessingFilter.setRememberMeServices() diff --git a/src/docbkx/runas-auth-provider.xml b/src/docbkx/runas-auth-provider.xml index c0ca90f15c..ba1afc14e7 100644 --- a/src/docbkx/runas-auth-provider.xml +++ b/src/docbkx/runas-auth-provider.xml @@ -1,8 +1,8 @@ Run-As Authentication Replacement -
Overview - +
+ Overview The AbstractSecurityInterceptor is able to temporarily replace the Authentication object in @@ -28,15 +28,15 @@ are particularly useful when calling remote web services
-
Configuration - - - A RunAsManager interface is provided by Acegi - Security: - - public Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config); - public boolean supports(ConfigAttribute attribute); - public boolean supports(Class clazz); +
+ Configuration + A RunAsManager interface is provided by Spring Security: + + Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config); + boolean supports(ConfigAttribute attribute); + boolean supports(Class clazz); + + The first method returns the Authentication object that should replace the existing @@ -84,20 +84,17 @@ the hash of a key is stored in all generated tokens. The RunAsManagerImpl and RunAsImplAuthenticationProvider is created in the - bean context with the same key: - - - <bean id="runAsManager" class="org.springframework.security.runas.RunAsManagerImpl"> - <property name="key"><value>my_run_as_password</value></property> - </bean> - - <bean id="runAsAuthenticationProvider" - class="org.springframework.security.runas.RunAsImplAuthenticationProvider"> - <property name="key"><value>my_run_as_password</value></property> - </bean> - - - + bean context with the same key: + + + + + + + +]]> By using the same key, each RunAsUserToken can be validated it was created by an approved RunAsManagerImpl. The diff --git a/src/docbkx/springsecurity.xml b/src/docbkx/springsecurity.xml index 2480735610..c4b5293006 100644 --- a/src/docbkx/springsecurity.xml +++ b/src/docbkx/springsecurity.xml @@ -117,8 +117,7 @@ - - + @@ -193,8 +192,7 @@ In addition to this reference guide, a number of other resources - exist to help you learn how to use Spring Security. These resources are - discussed in this section. + exist to help you learn how to use Spring Security. diff --git a/src/docbkx/supporting-infrastructure.xml b/src/docbkx/supporting-infrastructure.xml index 44f4383fda..9877e6f28b 100644 --- a/src/docbkx/supporting-infrastructure.xml +++ b/src/docbkx/supporting-infrastructure.xml @@ -1,4 +1,6 @@ -Supporting Infrastructure + + + Supporting Infrastructure This chapter introduces some of the supplementary and supporting @@ -6,9 +8,8 @@ related to security, yet included in the Spring Security project, we will discuss it in this chapter. -
Localization - - +
+ Localization Spring Security supports localization of exception messages that end users are likely to see. If your application is designed for English users, you don't need to do anything as by default all @@ -36,9 +37,11 @@ inside your application context to refer to the messages. An example is shown below: - <bean id="messageSource" class="org.springframework.context.support.ReloadableResourceBundleMessageSource"> -<property name="basename"><value>org/acegisecurity/messages</value></property> -</bean> + + + +]]> The messages.properties is named in accordance with standard resource bundles and represents the default @@ -73,20 +76,22 @@ SessionLocaleResolver etc)
-
Filters - +
+ Filters Spring Security uses many filters, as referred to throughout the - remainder of this reference guide. You have a choice in how these - filters are added to your web application, in that you can use either - Spring's DelegatingFilterProxy or + remainder of this reference guide. If you are using namespace configuration, + then the you don't usually have to declare the filter beans explicitly. There may be times when you want full control + over the security filter chain, either because you are using features which aren't supported in the namespace, or you + are using your own customized versions of classes. + In this case, you have a choice in how these filters are added to your web application, in that you can use either + Spring's DelegatingFilterProxy or FilterChainProxy. We'll look at both below. 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> @@ -96,7 +101,6 @@ <filter-name>myFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> - Notice that the filter is actually a DelegatingFilterProxy, @@ -147,10 +151,12 @@ - - - - + + + + ]]> @@ -209,7 +215,9 @@ any servlet container lifecycle invocations are not delegated through to DelegatingFilterProxy. - You can also omit a URI pattern from the filter chain by using + In the same way that you can use the attribute filters = "none" + when using namespace configuration, + you can omit a URI pattern from the filter chain by using the token #NONE# on the right-hand side of the <URI Pattern> = <Filter Chain> expression. For example, using the example above, if you wanted to @@ -311,4 +319,44 @@ SecurityContextHolder to be populated in time for use by SiteMesh decorators
+ +
+ Tag Libraries + + Spring Security comes bundled with several JSP tag libraries which provide a range of different + services. + +
+ Configuration + All taglib classes are included in the core + spring-security-xx.jar file, with the + security.tld located in the JAR's + META-INF directory. This means for JSP 1.2+ web + containers you can simply include the JAR in the WAR's + WEB-INF/lib directory and it will be available. If + you're using a JSP 1.1 container, you'll need to declare the JSP + taglib in your web.xml file, and include + security.tld in the WEB-INF/lib + directory. The following fragment is added to + web.xml: + + http://www.springframework.org/security/tags + /WEB-INF/security.tld + +]]> +
+ +
+ Usage + Now that you've configured the tag libraries, refer to the + individual reference guide sections for details on how to use them. + Note that when using the tags, you should include the taglib reference + in your JSP: + + <%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %> + + +
+
\ No newline at end of file diff --git a/src/docbkx/taglibs.xml b/src/docbkx/taglibs.xml index b739e503c8..26040a7aa5 100644 --- a/src/docbkx/taglibs.xml +++ b/src/docbkx/taglibs.xml @@ -2,17 +2,15 @@ Tag Libraries -
Overview - - +
+ Overview Spring Security comes bundled with several JSP tag libraries that eases JSP writing. The tag libraries provide a range of different services.
-
Configuration - - +
+ Configuration All taglib classes are included in the core spring-security-xx.jar file, with the security.tld located in the JAR's @@ -25,15 +23,16 @@ directory. The following fragment is added to web.xml: - <taglib> - <taglib-uri>http://www.springframework.org/security/tags</taglib-uri> - <taglib-location>/WEB-INF/security.tld</taglib-location> - </taglib> + +<taglib> + <taglib-uri>http://www.springframework.org/security/tags</taglib-uri> + <taglib-location>/WEB-INF/security.tld</taglib-location> +</taglib> +
-
Usage - - +
+ Usage Now that you've configured the tag libraries, refer to the individual reference guide sections for details on how to use them. Note that when using the tags, you should include the taglib reference diff --git a/src/docbkx/technical-overview.xml b/src/docbkx/technical-overview.xml index 088aa3207f..fcb86e1764 100644 --- a/src/docbkx/technical-overview.xml +++ b/src/docbkx/technical-overview.xml @@ -23,8 +23,8 @@ from one system to another and it will immediately work.
-
Shared Components - +
+ Shared Components Let's explore some of the most important shared components in Spring Security. Components are considered "shared" if they are diff --git a/src/docbkx/x509-auth-provider.xml b/src/docbkx/x509-auth-provider.xml index 81067cc122..b494b5e7ab 100644 --- a/src/docbkx/x509-auth-provider.xml +++ b/src/docbkx/x509-auth-provider.xml @@ -25,11 +25,11 @@
Adding X.509 Authentication to Your Web Application Enabling X.509 client authentication is very straightforward. Just add the <x509/> element to your http security namespace configuration. - <http> - ... - <x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/> - ... - </http> +<http> + ... + <x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/> + ... +</http> The element has two optional attributes: subject-principal-regex. The regular expression used to @@ -69,13 +69,13 @@ tomcat conf directory and add the following connector to the server.xml file - <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true" - clientAuth="true" sslProtocol="TLS" - keystoreFile="${catalina.home}/conf/server.jks" - keystoreType="JKS" keystorePass="password" - truststoreFile="${catalina.home}/conf/server.jks" - truststoreType="JKS" truststorePass="password" - /> +<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true" + clientAuth="true" sslProtocol="TLS" + keystoreFile="${catalina.home}/conf/server.jks" + keystoreType="JKS" keystorePass="password" + truststoreFile="${catalina.home}/conf/server.jks" + truststoreType="JKS" truststorePass="password" +/> clientAuth can also be set to want if you still want SSL connections to succeed even if the client doesn't provide a certificate.