0
# Spring Security CAS
1

2
Spring Security CAS provides comprehensive integration with Apereo's Central Authentication Service (CAS) for Spring Security applications. This module enables Single Sign-On (SSO) authentication, allowing users to authenticate once with a CAS server and access multiple applications without re-entering credentials.
3

4
## Package Information
5

6
- **Package Name**: spring-security-cas
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add Maven dependency:
10

11
```xml
12
<dependency>
13
    <groupId>org.springframework.security</groupId>
14
    <artifactId>spring-security-cas</artifactId>
15
    <version>6.5.1</version>
16
</dependency>
17
```
18

19
For Gradle:
20

21
```gradle
22
implementation 'org.springframework.security:spring-security-cas:6.5.1'
23
```
24

25
## Core Imports
26

27
```java
28
import org.springframework.security.cas.authentication.CasAuthenticationProvider;
29
import org.springframework.security.cas.web.CasAuthenticationFilter;
30
import org.springframework.security.cas.web.CasAuthenticationEntryPoint;
31
import org.springframework.security.cas.ServiceProperties;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.springframework.security.cas.authentication.CasAuthenticationProvider;
38
import org.springframework.security.cas.web.CasAuthenticationFilter;
39
import org.springframework.security.cas.web.CasAuthenticationEntryPoint;
40
import org.springframework.security.cas.ServiceProperties;
41
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
42

43
@Configuration
44
@EnableWebSecurity
45
public class CasSecurityConfig {
46

47
    @Bean
48
    public ServiceProperties serviceProperties() {
49
        ServiceProperties serviceProperties = new ServiceProperties();
50
        serviceProperties.setService("http://localhost:8080/login/cas");
51
        serviceProperties.setSendRenew(false);
52
        return serviceProperties;
53
    }
54

55
    @Bean
56
    public CasAuthenticationEntryPoint casAuthenticationEntryPoint() {
57
        CasAuthenticationEntryPoint entryPoint = new CasAuthenticationEntryPoint();
58
        entryPoint.setLoginUrl("https://cas-server.example.com/cas/login");
59
        entryPoint.setServiceProperties(serviceProperties());
60
        return entryPoint;
61
    }
62

63
    @Bean
64
    public CasAuthenticationFilter casAuthenticationFilter() throws Exception {
65
        CasAuthenticationFilter filter = new CasAuthenticationFilter();
66
        filter.setAuthenticationManager(authenticationManager());
67
        filter.setServiceProperties(serviceProperties());
68
        return filter;
69
    }
70

71
    @Bean
72
    public CasAuthenticationProvider casAuthenticationProvider() {
73
        CasAuthenticationProvider provider = new CasAuthenticationProvider();
74
        provider.setServiceProperties(serviceProperties());
75
        provider.setTicketValidator(cas20ServiceTicketValidator());
76
        provider.setUserDetailsService(userDetailsService());
77
        provider.setKey("cas-authentication-provider");
78
        return provider;
79
    }
80
}
81
```
82

83
## Architecture
84

85
Spring Security CAS integration is built around several key components:
86

87
- **Authentication Framework**: `CasAuthenticationProvider` integrates with Spring Security's authentication architecture to validate CAS tickets and create authenticated principals
88
- **Web Filters**: `CasAuthenticationFilter` processes CAS service tickets while `CasAuthenticationEntryPoint` redirects unauthenticated users to CAS login
89
- **Service Configuration**: `ServiceProperties` and `SamlServiceProperties` define service URLs and CAS protocol parameters
90
- **Ticket Caching**: `StatelessTicketCache` implementations provide performance optimization for stateless authentication scenarios
91
- **User Details Integration**: Support for loading user details from CAS assertions via Spring Security's `UserDetailsService` framework
92
- **JSON Serialization**: Jackson module enables session serialization in distributed environments
93

94
## Capabilities
95

96
### Core Configuration
97

98
Service properties and SAML configuration for defining CAS service parameters, authentication behavior, and protocol-specific settings.
99

100
```java { .api }
101
public class ServiceProperties implements InitializingBean {
102
    public String getService();
103
    public void setService(String service);
104
    public boolean isSendRenew();
105
    public void setSendRenew(boolean sendRenew);
106
    public String getArtifactParameter();
107
    public void setArtifactParameter(String artifactParameter);
108
    public boolean isAuthenticateAllArtifacts();
109
    public void setAuthenticateAllArtifacts(boolean authenticateAllArtifacts);
110
}
111

112
public final class SamlServiceProperties extends ServiceProperties {
113
    public SamlServiceProperties();
114
}
115
```
116

117
[Configuration](./configuration.md)
118

119
### Authentication Provider and Tokens
120

121
CAS authentication provider and token implementations for integrating CAS ticket validation with Spring Security's authentication framework.
122

123
```java { .api }
124
public class CasAuthenticationProvider implements AuthenticationProvider, InitializingBean, MessageSourceAware {
125
    public Authentication authenticate(Authentication authentication) throws AuthenticationException;
126
    public boolean supports(Class<?> authentication);
127
    public void setServiceProperties(ServiceProperties serviceProperties);
128
    public void setTicketValidator(TicketValidator ticketValidator);
129
    public void setUserDetailsService(UserDetailsService userDetailsService);
130
    public void setKey(String key);
131
}
132

133
public class CasAuthenticationToken extends AbstractAuthenticationToken implements Serializable {
134
    public CasAuthenticationToken(String key, Object principal, Object credentials, 
135
                                  Collection<? extends GrantedAuthority> authorities, 
136
                                  UserDetails userDetails, Assertion assertion);
137
    public Assertion getAssertion();
138
    public UserDetails getUserDetails();
139
    public int getKeyHash();
140
}
141
```
142

143
[Authentication](./authentication.md)
144

145
### Web Integration
146

147
Web filters and entry points for processing CAS authentication flows, handling service ticket validation, and managing gateway authentication.
148

149
```java { .api }
150
public class CasAuthenticationFilter extends AbstractAuthenticationProcessingFilter {
151
    public CasAuthenticationFilter();
152
    public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response) 
153
        throws AuthenticationException, IOException;
154
    public void setServiceProperties(ServiceProperties serviceProperties);
155
    public void setProxyReceptorUrl(String proxyReceptorUrl);
156
}
157

158
public class CasAuthenticationEntryPoint implements AuthenticationEntryPoint, InitializingBean {
159
    public void commence(HttpServletRequest servletRequest, HttpServletResponse response, 
160
                        AuthenticationException authenticationException) throws IOException;
161
    public void setLoginUrl(String loginUrl);
162
    public void setServiceProperties(ServiceProperties serviceProperties);
163
}
164
```
165

166
[Web Integration](./web-integration.md)
167

168
### User Details Services
169

170
Specialized user details services for extracting user information and authorities from CAS assertions.
171

172
```java { .api }
173
public abstract class AbstractCasAssertionUserDetailsService 
174
    implements AuthenticationUserDetailsService<CasAssertionAuthenticationToken> {
175
    public final UserDetails loadUserDetails(CasAssertionAuthenticationToken token);
176
    protected abstract UserDetails loadUserDetails(Assertion assertion);
177
}
178

179
public final class GrantedAuthorityFromAssertionAttributesUserDetailsService 
180
    extends AbstractCasAssertionUserDetailsService {
181
    public GrantedAuthorityFromAssertionAttributesUserDetailsService(String[] attributes);
182
    public void setConvertToUpperCase(boolean convertToUpperCase);
183
}
184
```
185

186
[User Details](./user-details.md)
187

188
### Ticket Caching
189

190
Stateless ticket caching implementations for performance optimization in clustered and stateless authentication scenarios.
191

192
```java { .api }
193
public interface StatelessTicketCache {
194
    CasAuthenticationToken getByTicketId(String serviceTicket);
195
    void putTicketInCache(CasAuthenticationToken token);
196
    void removeTicketFromCache(CasAuthenticationToken token);
197
    void removeTicketFromCache(String serviceTicket);
198
}
199

200
public final class NullStatelessTicketCache implements StatelessTicketCache;
201
public class SpringCacheBasedTicketCache implements StatelessTicketCache {
202
    public SpringCacheBasedTicketCache(Cache cache);
203
}
204
```
205

206
[Ticket Caching](./ticket-caching.md)
207

208
### JSON Serialization
209

210
Jackson module for serializing CAS authentication tokens and related objects in distributed session scenarios.
211

212
```java { .api }
213
public class CasJackson2Module extends SimpleModule {
214
    public CasJackson2Module();
215
    public void setupModule(SetupContext context);
216
}
217
```
218

219
[JSON Serialization](./json-serialization.md)
220

221
## Common Exception Types
222

223
- `AuthenticationException` - Base exception for authentication failures
224
- `BadCredentialsException` - Invalid or expired CAS tickets
225
- `TicketValidationException` - CAS server ticket validation failures
226
- `IllegalArgumentException` - Configuration errors and invalid parameters
227

228
## Dependencies
229

230
This module requires:
231
- Spring Security Core (6.5.1+)
232
- Spring Framework (6.0+)
233
- CAS Client for Java (org.jasig.cas.client)
234
- Jackson Core (for JSON serialization support)
235

236
## Integration Notes
237

238
- Configure CAS server URL in `CasAuthenticationEntryPoint`
239
- Set service URL in `ServiceProperties` to match your application's callback URL
240
- Implement or configure `UserDetailsService` for loading user authorities
241
- Consider ticket caching for high-traffic stateless applications
242
- Use `CasGatewayAuthenticationRedirectFilter` for optional SSO scenarios