Spring Security Reference

Authors

Ben Alex , Luke Taylor , Rob Winch , Gunnar Hillert

4.0.3.RELEASE

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.


Table of Contents

I. Preface
II. Getting Started
1. Introduction
1.1. What is Spring Security?
1.2. History
1.3. Release Numbering
1.4. Getting Spring Security
1.4.1. Usage with Maven
Maven Repositories
Spring Framework Bom
1.4.2. Gradle
Gradle Repositories
Using Spring 4.0.x and Gradle
1.4.3. Project Modules
Core - spring-security-core.jar
Remoting - spring-security-remoting.jar
Web - spring-security-web.jar
Config - spring-security-config.jar
LDAP - spring-security-ldap.jar
ACL - spring-security-acl.jar
CAS - spring-security-cas.jar
OpenID - spring-security-openid.jar
1.4.4. Checking out the Source
2. What’s new in Spring Security 4.0
2.1. Features
2.2. Migrating from 3.x to 4.x
3. Java Configuration
3.1. Hello Web Security Java Configuration
3.1.1. AbstractSecurityWebApplicationInitializer
3.1.2. AbstractSecurityWebApplicationInitializer without Existing Spring
3.1.3. AbstractSecurityWebApplicationInitializer with Spring MVC
3.2. HttpSecurity
3.3. Java Configuration and Form Login
3.4. Authorize Requests
3.5. Handling Logouts
3.5.1. LogoutHandler
3.5.2. LogoutSuccessHandler
3.5.3. Further Logout-Related References
3.6. Authentication
3.6.1. In Memory Authentication
3.6.2. JDBC Authentication
3.6.3. LDAP Authentication
3.7. Multiple HttpSecurity
3.8. Method Security
3.8.1. EnableGlobalMethodSecurity
3.8.2. GlobalMethodSecurityConfiguration
3.9. Post Processing Configured Objects
4. Security Namespace Configuration
4.1. Introduction
4.1.1. Design of the Namespace
4.2. Getting Started with Security Namespace Configuration
4.2.1. web.xml Configuration
4.2.2. A Minimal <http> Configuration
4.2.3. Form and Basic Login Options
Setting a Default Post-Login Destination
4.2.4. Logout Handling
4.2.5. Using other Authentication Providers
Adding a Password Encoder
4.3. Advanced Web Features
4.3.1. Remember-Me Authentication
4.3.2. Adding HTTP/HTTPS Channel Security
4.3.3. Session Management
Detecting Timeouts
Concurrent Session Control
Session Fixation Attack Protection
4.3.4. OpenID Support
Attribute Exchange
4.3.5. Response Headers
4.3.6. Adding in Your Own Filters
Setting a Custom AuthenticationEntryPoint
4.4. Method Security
4.4.1. The <global-method-security> Element
Adding Security Pointcuts using protect-pointcut
4.5. The Default AccessDecisionManager
4.5.1. Customizing the AccessDecisionManager
4.6. The Authentication Manager and the Namespace
5. Sample Applications
5.1. Tutorial Sample
5.2. Contacts
5.3. LDAP Sample
5.4. OpenID Sample
5.5. CAS Sample
5.6. JAAS Sample
5.7. Pre-Authentication Sample
6. Spring Security Community
6.1. Issue Tracking
6.2. Becoming Involved
6.3. Further Information
III. Architecture and Implementation
7. Technical Overview
7.1. Runtime Environment
7.2. Core Components
7.2.1. SecurityContextHolder, SecurityContext and Authentication Objects
Obtaining information about the current user
7.2.2. The UserDetailsService
7.2.3. GrantedAuthority
7.2.4. Summary
7.3. Authentication
7.3.1. What is authentication in Spring Security?
7.3.2. Setting the SecurityContextHolder Contents Directly
7.4. Authentication in a Web Application
7.4.1. ExceptionTranslationFilter
7.4.2. AuthenticationEntryPoint
7.4.3. Authentication Mechanism
7.4.4. Storing the SecurityContext between requests
7.5. Access-Control (Authorization) in Spring Security
7.5.1. Security and AOP Advice
7.5.2. Secure Objects and the AbstractSecurityInterceptor
What are Configuration Attributes?
RunAsManager
AfterInvocationManager
Extending the Secure Object Model
7.6. Localization
8. Core Services
8.1. The AuthenticationManager, ProviderManager and AuthenticationProvider
8.1.1. Erasing Credentials on Successful Authentication
8.1.2. DaoAuthenticationProvider
8.2. UserDetailsService Implementations
8.2.1. In-Memory Authentication
8.2.2. JdbcDaoImpl
Authority Groups
8.3. Password Encoding
8.3.1. What is a hash?
8.3.2. Adding Salt to a Hash
8.3.3. Hashing and Authentication
IV. Testing
9. Testing Method Security
9.1. Security Test Setup
9.2. @WithMockUser
9.3. @WithUserDetails
9.4. @WithSecurityContext
10. Spring MVC Test Integration
10.1. Setting Up MockMvc and Spring Security
10.2. SecurityMockMvcRequestPostProcessors
10.2.1. Testing with CSRF Protection
10.2.2. Running a Test as a User in Spring MVC Test
10.2.3. Running as a User in Spring MVC Test with RequestPostProcessor
Running as a User in Spring MVC Test with Annotations
10.2.4. Testing HTTP Basic Authentication
10.3. SecurityMockMvcRequestBuilders
10.3.1. Testing Form Based Authentication
10.3.2. Testing Logout
10.4. SecurityMockMvcResultMatchers
10.4.1. Unauthenticated Assertion
10.4.2. Authenticated Assertion
V. Web Application Security
11. The Security Filter Chain
11.1. DelegatingFilterProxy
11.2. FilterChainProxy
11.2.1. Bypassing the Filter Chain
11.3. Filter Ordering
11.4. Request Matching and HttpFirewall
11.5. Use with other Filter-Based Frameworks
11.6. Advanced Namespace Configuration
12. Core Security Filters
12.1. FilterSecurityInterceptor
12.2. ExceptionTranslationFilter
12.2.1. AuthenticationEntryPoint
12.2.2. AccessDeniedHandler
12.2.3. SavedRequest s and the RequestCache Interface
12.3. SecurityContextPersistenceFilter
12.3.1. SecurityContextRepository
12.4. UsernamePasswordAuthenticationFilter
12.4.1. Application Flow on Authentication Success and Failure
13. Servlet API integration
13.1. Servlet 2.5+ Integration
13.1.1. HttpServletRequest.getRemoteUser()
13.1.2. HttpServletRequest.getUserPrincipal()
13.1.3. HttpServletRequest.isUserInRole(String)
13.2. Servlet 3+ Integration
13.2.1. HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)
13.2.2. HttpServletRequest.login(String,String)
13.2.3. HttpServletRequest.logout()
13.2.4. AsyncContext.start(Runnable)
13.2.5. Async Servlet Support
13.3. Servlet 3.1+ Integration
13.3.1. HttpServletRequest#changeSessionId()
14. Basic and Digest Authentication
14.1. BasicAuthenticationFilter
14.1.1. Configuration
14.2. DigestAuthenticationFilter
14.2.1. Configuration
15. Remember-Me Authentication
15.1. Overview
15.2. Simple Hash-Based Token Approach
15.3. Persistent Token Approach
15.4. Remember-Me Interfaces and Implementations
15.4.1. TokenBasedRememberMeServices
15.4.2. PersistentTokenBasedRememberMeServices
16. Cross Site Request Forgery (CSRF)
16.1. CSRF Attacks
16.2. Synchronizer Token Pattern
16.3. When to use CSRF protection
16.3.1. CSRF protection and JSON
16.3.2. CSRF and Stateless Browser Applications
16.4. Using Spring Security CSRF Protection
16.4.1. Use proper HTTP verbs
16.4.2. Configure CSRF Protection
16.4.3. Include the CSRF Token
Form Submissions
Ajax and JSON Requests
16.5. CSRF Caveats
16.5.1. Timeouts
16.5.2. Logging In
16.5.3. Logging Out
16.5.4. Multipart (file upload)
Placing MultipartFilter before Spring Security
Include CSRF token in action
16.5.5. HiddenHttpMethodFilter
16.6. Overriding Defaults
17. Security HTTP Response Headers
17.1. Default Security Headers
17.1.1. Cache Control
17.1.2. Content Type Options
17.1.3. HTTP Strict Transport Security (HSTS)
17.1.4. X-Frame-Options
17.1.5. X-XSS-Protection
17.2. Custom Headers
17.2.1. Static Headers
17.2.2. Headers Writer
17.2.3. DelegatingRequestMatcherHeaderWriter
18. Session Management
18.1. SessionManagementFilter
18.2. SessionAuthenticationStrategy
18.3. Concurrency Control
18.3.1. Querying the SessionRegistry for currently authenticated users and their sessions
19. Anonymous Authentication
19.1. Overview
19.2. Configuration
19.3. AuthenticationTrustResolver
20. WebSocket Security
20.1. WebSocket Configuration
20.2. WebSocket Authentication
20.3. WebSocket Authorization
20.3.1. WebSocket Authorization Notes
WebSocket Authorization on Message Types
WebSocket Authorization on Destinations
20.3.2. Outbound Messages
20.4. Enforcing Same Origin Policy
20.4.1. Why Same Origin?
20.4.2. Spring WebSocket Allowed Origin
20.4.3. Adding CSRF to Stomp Headers
20.4.4. Disable CSRF within WebSockets
20.5. Working with SockJS
20.5.1. SockJS & frame-options
20.5.2. SockJS & Relaxing CSRF
VI. Authorization
21. Authorization Architecture
21.1. Authorities
21.2. Pre-Invocation Handling
21.2.1. The AccessDecisionManager
21.2.2. Voting-Based AccessDecisionManager Implementations
RoleVoter
AuthenticatedVoter
Custom Voters
21.3. After Invocation Handling
21.4. Hierarchical Roles
22. Secure Object Implementations
22.1. AOP Alliance (MethodInvocation) Security Interceptor
22.1.1. Explicit MethodSecurityInterceptor Configuration
22.2. AspectJ (JoinPoint) Security Interceptor
23. Expression-Based Access Control
23.1. Overview
23.1.1. Common Built-In Expressions
23.2. Web Security Expressions
23.3. Method Security Expressions
23.3.1. @Pre and @Post Annotations
Access Control using @PreAuthorize and @PostAuthorize
Filtering using @PreFilter and @PostFilter
23.3.2. Built-In Expressions
The PermissionEvaluator interface
VII. Additional Topics
24. Domain Object Security (ACLs)
24.1. Overview
24.2. Key Concepts
24.3. Getting Started
25. Pre-Authentication Scenarios
25.1. Pre-Authentication Framework Classes
25.1.1. AbstractPreAuthenticatedProcessingFilter
J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource
25.1.2. PreAuthenticatedAuthenticationProvider
25.1.3. Http403ForbiddenEntryPoint
25.2. Concrete Implementations
25.2.1. Request-Header Authentication (Siteminder)
Siteminder Example Configuration
25.2.2. Java EE Container Authentication
26. LDAP Authentication
26.1. Overview
26.2. Using LDAP with Spring Security
26.3. Configuring an LDAP Server
26.3.1. Using an Embedded Test Server
26.3.2. Using Bind Authentication
26.3.3. Loading Authorities
26.4. Implementation Classes
26.4.1. LdapAuthenticator Implementations
Common Functionality
BindAuthenticator
PasswordComparisonAuthenticator
26.4.2. Connecting to the LDAP Server
26.4.3. LDAP Search Objects
FilterBasedLdapUserSearch
26.4.4. LdapAuthoritiesPopulator
26.4.5. Spring Bean Configuration
26.4.6. LDAP Attributes and Customized UserDetails
26.5. Active Directory Authentication
26.5.1. ActiveDirectoryLdapAuthenticationProvider
Active Directory Error Codes
27. JSP Tag Libraries
27.1. Declaring the Taglib
27.2. The authorize Tag
27.2.1. Disabling Tag Authorization for Testing
27.3. The authentication Tag
27.4. The accesscontrollist Tag
27.5. The csrfInput Tag
27.6. The csrfMetaTags Tag
28. Java Authentication and Authorization Service (JAAS) Provider
28.1. Overview
28.2. AbstractJaasAuthenticationProvider
28.2.1. JAAS CallbackHandler
28.2.2. JAAS AuthorityGranter
28.3. DefaultJaasAuthenticationProvider
28.3.1. InMemoryConfiguration
28.3.2. DefaultJaasAuthenticationProvider Example Configuration
28.4. JaasAuthenticationProvider
28.5. Running as a Subject
29. CAS Authentication
29.1. Overview
29.2. How CAS Works
29.2.1. Spring Security and CAS Interaction Sequence
29.3. Configuration of CAS Client
29.3.1. Service Ticket Authentication
29.3.2. Single Logout
29.3.3. Authenticating to a Stateless Service with CAS
Configuring CAS to Obtain Proxy Granting Tickets
Calling a Stateless Service Using a Proxy Ticket
29.3.4. Proxy Ticket Authentication
30. X.509 Authentication
30.1. Overview
30.2. Adding X.509 Authentication to Your Web Application
30.3. Setting up SSL in Tomcat
31. Run-As Authentication Replacement
31.1. Overview
31.2. Configuration
32. Spring Security Crypto Module
32.1. Introduction
32.2. Encryptors
32.2.1. BytesEncryptor
32.2.2. TextEncryptor
32.3. Key Generators
32.3.1. BytesKeyGenerator
32.3.2. StringKeyGenerator
32.4. Password Encoding
33. Concurrency Support
33.1. DelegatingSecurityContextRunnable
33.2. DelegatingSecurityContextExecutor
33.3. Spring Security Concurrency Classes
34. Spring MVC Integration
34.1. @EnableWebMvcSecurity
34.2. @AuthenticationPrincipal
34.3. Spring MVC Async Integration
34.4. Spring MVC and CSRF Integration
34.4.1. Automatic Token Inclusion
34.4.2. Resolving the CsrfToken
VIII. Spring Data Integration
35. Spring Data & Spring Security Configuration
36. Security Expressions within @Query
IX. Appendix
37. Security Database Schema
37.1. User Schema
37.1.1. Group Authorities
37.2. Persistent Login (Remember-Me) Schema
37.3. ACL Schema
37.3.1. HyperSQL
37.3.2. PostgreSQL
37.3.3. MySQL and MariaDB
37.3.4. Microsoft SQL Server
37.3.5. Oracle Database
38. The Security Namespace
38.1. Web Application Security
38.1.1. <debug>
38.1.2. <http>
<http> Attributes
Child Elements of <http>
38.1.3. <access-denied-handler>
Parent Elements of <access-denied-handler>
<access-denied-handler> Attributes
38.1.4. <headers>
<headers> Attributes
Parent Elements of <headers>
Child Elements of <headers>
38.1.5. <cache-control>
<cache-control> Attributes
Parent Elements of <cache-control>
38.1.6. <hsts>
<hsts> Attributes
Parent Elements of <hsts>
38.1.7. <frame-options>
<frame-options> Attributes
Parent Elements of <frame-options>
38.1.8. <xss-protection>
<xss-protection> Attributes
Parent Elements of <xss-protection>
38.1.9. <content-type-options>
<content-type-options> Attributes
Parent Elements of <content-type-options>
38.1.10. <header>
<header-attributes> Attributes
Parent Elements of <header>
38.1.11. <anonymous>
Parent Elements of <anonymous>
<anonymous> Attributes
38.1.12. <csrf>
Parent Elements of <csrf>
<csrf> Attributes
38.1.13. <custom-filter>
Parent Elements of <custom-filter>
<custom-filter> Attributes
38.1.14. <expression-handler>
Parent Elements of <expression-handler>
<expression-handler> Attributes
38.1.15. <form-login>
Parent Elements of <form-login>
<form-login> Attributes
38.1.16. <http-basic>
Parent Elements of <http-basic>
<http-basic> Attributes
38.1.17. <http-firewall> Element
<http-firewall> Attributes
38.1.18. <intercept-url>
Parent Elements of <intercept-url>
<intercept-url> Attributes
38.1.19. <jee>
Parent Elements of <jee>
<jee> Attributes
38.1.20. <logout>
Parent Elements of <logout>
<logout> Attributes
38.1.21. <openid-login>
Parent Elements of <openid-login>
<openid-login> Attributes
Child Elements of <openid-login>
38.1.22. <attribute-exchange>
Parent Elements of <attribute-exchange>
<attribute-exchange> Attributes
Child Elements of <attribute-exchange>
38.1.23. <openid-attribute>
Parent Elements of <openid-attribute>
<openid-attribute> Attributes
38.1.24. <port-mappings>
Parent Elements of <port-mappings>
Child Elements of <port-mappings>
38.1.25. <port-mapping>
Parent Elements of <port-mapping>
<port-mapping> Attributes
38.1.26. <remember-me>
Parent Elements of <remember-me>
<remember-me> Attributes
38.1.27. <request-cache> Element
Parent Elements of <request-cache>
<request-cache> Attributes
38.1.28. <session-management>
Parent Elements of <session-management>
<session-management> Attributes
Child Elements of <session-management>
38.1.29. <concurrency-control>
Parent Elements of <concurrency-control>
<concurrency-control> Attributes
38.1.30. <x509>
Parent Elements of <x509>
<x509> Attributes
38.1.31. <filter-chain-map>
<filter-chain-map> Attributes
Child Elements of <filter-chain-map>
38.1.32. <filter-chain>
Parent Elements of <filter-chain>
<filter-chain> Attributes
38.1.33. <filter-security-metadata-source>
<filter-security-metadata-source> Attributes
Child Elements of <filter-security-metadata-source>
38.2. WebSocket Security
38.2.1. <websocket-message-broker>
<websocket-message-broker> Attributes
Child Elements of <websocket-message-broker>
38.2.2. <intercept-message>
Parent Elements of <intercept-message>
<intercept-message> Attributes
38.3. Authentication Services
38.3.1. <authentication-manager>
<authentication-manager> Attributes
Child Elements of <authentication-manager>
38.3.2. <authentication-provider>
Parent Elements of <authentication-provider>
<authentication-provider> Attributes
Child Elements of <authentication-provider>
38.3.3. <jdbc-user-service>
<jdbc-user-service> Attributes
38.3.4. <password-encoder>
Parent Elements of <password-encoder>
<password-encoder> Attributes
Child Elements of <password-encoder>
38.3.5. <salt-source>
Parent Elements of <salt-source>
<salt-source> Attributes
38.3.6. <user-service>
<user-service> Attributes
Child Elements of <user-service>
38.3.7. <user>
Parent Elements of <user>
<user> Attributes
38.4. Method Security
38.4.1. <global-method-security>
<global-method-security> Attributes
Child Elements of <global-method-security>
38.4.2. <after-invocation-provider>
Parent Elements of <after-invocation-provider>
<after-invocation-provider> Attributes
38.4.3. <pre-post-annotation-handling>
Parent Elements of <pre-post-annotation-handling>
Child Elements of <pre-post-annotation-handling>
38.4.4. <invocation-attribute-factory>
Parent Elements of <invocation-attribute-factory>
<invocation-attribute-factory> Attributes
38.4.5. <post-invocation-advice>
Parent Elements of <post-invocation-advice>
<post-invocation-advice> Attributes
38.4.6. <pre-invocation-advice>
Parent Elements of <pre-invocation-advice>
<pre-invocation-advice> Attributes
38.4.7. Securing Methods using
Parent Elements of <protect-pointcut>
<protect-pointcut> Attributes
38.4.8. <intercept-methods>
<intercept-methods> Attributes
Child Elements of <intercept-methods>
38.4.9. <method-security-metadata-source>
<method-security-metadata-source> Attributes
Child Elements of <method-security-metadata-source>
38.4.10. <protect>
Parent Elements of <protect>
<protect> Attributes
38.5. LDAP Namespace Options
38.5.1. Defining the LDAP Server using the
<ldap-server> Attributes
38.5.2. <ldap-authentication-provider>
Parent Elements of <ldap-authentication-provider>
<ldap-authentication-provider> Attributes
Child Elements of <ldap-authentication-provider>
38.5.3. <password-compare>
Parent Elements of <password-compare>
<password-compare> Attributes
Child Elements of <password-compare>
38.5.4. <ldap-user-service>
<ldap-user-service> Attributes
39. Spring Security Dependencies
39.1. spring-security-core
39.2. spring-security-remoting
39.3. spring-security-web
39.4. spring-security-ldap
39.5. spring-security-config
39.6. spring-security-acl
39.7. spring-security-cas
39.8. spring-security-openid
39.9. spring-security-taglibs