0
# Authentication
1
2
CAS authentication provider and token implementations for integrating CAS ticket validation with Spring Security's authentication framework. This module handles the core authentication logic, token management, and integration with CAS server ticket validation.
3
4
## Capabilities
5
6
### CAS Authentication Provider
7
8
Main authentication provider that validates CAS service tickets and creates authenticated Spring Security principals.
9
10
```java { .api }
11
/**
12
* Authenticates a CAS service ticket by validating it with the CAS server
13
* and creating a Spring Security authentication token with user details.
14
*/
15
public class CasAuthenticationProvider implements AuthenticationProvider, InitializingBean, MessageSourceAware {
16
17
/**
18
* Authenticates the provided authentication request.
19
* @param authentication the authentication request (must be CasServiceTicketAuthenticationToken)
20
* @return fully authenticated object including credentials
21
* @throws AuthenticationException if authentication fails
22
*/
23
public Authentication authenticate(Authentication authentication) throws AuthenticationException;
24
25
/**
26
* Indicates whether this provider supports the specified authentication class.
27
* @param authentication the authentication class to check
28
* @return true if supports CasServiceTicketAuthenticationToken
29
*/
30
public boolean supports(Class<?> authentication);
31
32
/**
33
* Validates configuration after properties are set.
34
* @throws IllegalArgumentException if required properties are missing
35
*/
36
public void afterPropertiesSet() throws IllegalArgumentException;
37
38
/**
39
* Sets the user details service for loading user information.
40
* @param userDetailsService service to load UserDetails by username
41
*/
42
public void setUserDetailsService(UserDetailsService userDetailsService);
43
44
/**
45
* Sets authentication user details service for CAS assertion-based loading.
46
* @param authenticationUserDetailsService service that loads from CAS assertions
47
*/
48
public void setAuthenticationUserDetailsService(
49
AuthenticationUserDetailsService<CasAssertionAuthenticationToken> authenticationUserDetailsService);
50
51
/**
52
* Sets user details checker for account validation.
53
* @param userDetailsChecker checker for locked/expired accounts
54
*/
55
public void setUserDetailsChecker(UserDetailsChecker userDetailsChecker);
56
57
/**
58
* Sets service properties for CAS integration.
59
* @param serviceProperties CAS service configuration (required)
60
*/
61
public void setServiceProperties(ServiceProperties serviceProperties);
62
63
/**
64
* Sets the unique key for this authentication provider.
65
* @param key unique identifier for this provider instance
66
*/
67
public void setKey(String key);
68
69
/**
70
* Sets the ticket cache for stateless authentication scenarios.
71
* @param statelessTicketCache cache implementation for storing validated tickets
72
*/
73
public void setStatelessTicketCache(StatelessTicketCache statelessTicketCache);
74
75
/**
76
* Sets the CAS ticket validator for validating service tickets.
77
* @param ticketValidator validator that communicates with CAS server (required)
78
*/
79
public void setTicketValidator(TicketValidator ticketValidator);
80
81
/**
82
* Sets authorities mapper for converting CAS authorities to Spring Security authorities.
83
* @param authoritiesMapper mapper for authority conversion
84
*/
85
public void setAuthoritiesMapper(GrantedAuthoritiesMapper authoritiesMapper);
86
87
/**
88
* Sets message source for internationalization of error messages.
89
* @param messageSource message source for error messages
90
*/
91
public void setMessageSource(MessageSource messageSource);
92
93
/**
94
* Gets the configured stateless ticket cache.
95
* @return the ticket cache instance
96
*/
97
public StatelessTicketCache getStatelessTicketCache();
98
}
99
```
100
101
**Usage Example:**
102
103
```java
104
@Bean
105
public CasAuthenticationProvider casAuthenticationProvider() {
106
CasAuthenticationProvider provider = new CasAuthenticationProvider();
107
provider.setServiceProperties(serviceProperties());
108
provider.setTicketValidator(cas20ServiceTicketValidator());
109
provider.setUserDetailsService(userDetailsService());
110
provider.setKey("cas-authentication-provider");
111
provider.setStatelessTicketCache(ticketCache());
112
return provider;
113
}
114
```
115
116
### CAS Authentication Token
117
118
Represents a successful CAS authentication containing the validated user principal, credentials, authorities, and CAS assertion.
119
120
```java { .api }
121
/**
122
* Authentication token representing a successful CAS authentication.
123
* Contains user details, authorities, and the original CAS assertion.
124
*/
125
public class CasAuthenticationToken extends AbstractAuthenticationToken implements Serializable {
126
127
/**
128
* Creates a CAS authentication token for a successfully authenticated user.
129
* @param key unique key identifying the authentication provider
130
* @param principal the authenticated principal (usually username)
131
* @param credentials the credentials (usually the validated ticket)
132
* @param authorities granted authorities for the user
133
* @param userDetails detailed user information
134
* @param assertion CAS assertion containing user attributes
135
*/
136
public CasAuthenticationToken(String key, Object principal, Object credentials,
137
Collection<? extends GrantedAuthority> authorities,
138
UserDetails userDetails, Assertion assertion);
139
140
/**
141
* Gets the credentials (usually the original CAS ticket).
142
* @return the credentials
143
*/
144
public Object getCredentials();
145
146
/**
147
* Gets the principal (usually the username).
148
* @return the principal
149
*/
150
public Object getPrincipal();
151
152
/**
153
* Gets the hash code of the authentication provider key.
154
* @return hash code of the provider key
155
*/
156
public int getKeyHash();
157
158
/**
159
* Gets the CAS assertion containing user attributes and authentication details.
160
* @return the CAS assertion
161
*/
162
public Assertion getAssertion();
163
164
/**
165
* Gets the user details loaded for this authentication.
166
* @return the user details
167
*/
168
public UserDetails getUserDetails();
169
170
/**
171
* Compares this token with another object for equality.
172
* @param obj object to compare
173
* @return true if equal
174
*/
175
public boolean equals(Object obj);
176
177
/**
178
* Returns hash code for this token.
179
* @return hash code
180
*/
181
public int hashCode();
182
183
/**
184
* Returns string representation of this token.
185
* @return string representation
186
*/
187
public String toString();
188
}
189
```
190
191
### CAS Assertion Authentication Token
192
193
Temporary authentication token used during the user details loading process from CAS assertions.
194
195
```java { .api }
196
/**
197
* Temporary authentication token representing a CAS assertion before user details are loaded.
198
* Used internally by authentication user details services.
199
*/
200
public final class CasAssertionAuthenticationToken extends AbstractAuthenticationToken {
201
202
/**
203
* Creates an assertion authentication token for loading user details.
204
* @param assertion the CAS assertion containing user information
205
* @param ticket the original CAS service ticket
206
*/
207
public CasAssertionAuthenticationToken(Assertion assertion, String ticket);
208
209
/**
210
* Gets the principal (CAS assertion principal).
211
* @return the assertion principal
212
*/
213
public Object getPrincipal();
214
215
/**
216
* Gets the credentials (original service ticket).
217
* @return the service ticket
218
*/
219
public Object getCredentials();
220
221
/**
222
* Gets the CAS assertion.
223
* @return the CAS assertion
224
*/
225
public Assertion getAssertion();
226
}
227
```
228
229
### Service Ticket Authentication Token
230
231
Authentication token representing CAS service tickets for both stateful and stateless authentication scenarios.
232
233
```java { .api }
234
/**
235
* Authentication token for CAS service tickets, supporting both stateful and stateless modes.
236
*/
237
public class CasServiceTicketAuthenticationToken extends AbstractAuthenticationToken {
238
239
/** Identifier for stateless CAS authentication */
240
public static final String CAS_STATELESS_IDENTIFIER = "_cas_stateless_";
241
242
/** Identifier for stateful CAS authentication */
243
public static final String CAS_STATEFUL_IDENTIFIER = "_cas_stateful_";
244
245
/**
246
* Creates a service ticket authentication token.
247
* @param identifier stateful or stateless identifier
248
* @param credentials the CAS service ticket
249
*/
250
public CasServiceTicketAuthenticationToken(String identifier, Object credentials);
251
252
/**
253
* Creates a service ticket authentication token with authorities.
254
* @param identifier stateful or stateless identifier
255
* @param credentials the CAS service ticket
256
* @param authorities granted authorities
257
*/
258
public CasServiceTicketAuthenticationToken(String identifier, Object credentials,
259
Collection<? extends GrantedAuthority> authorities);
260
261
/**
262
* Creates a stateful service ticket authentication token.
263
* @param credentials the CAS service ticket
264
* @return stateful authentication token
265
*/
266
public static CasServiceTicketAuthenticationToken stateful(Object credentials);
267
268
/**
269
* Creates a stateless service ticket authentication token.
270
* @param credentials the CAS service ticket
271
* @return stateless authentication token
272
*/
273
public static CasServiceTicketAuthenticationToken stateless(Object credentials);
274
275
/**
276
* Indicates if this token represents stateless authentication.
277
* @return true if stateless
278
*/
279
public boolean isStateless();
280
281
/**
282
* Gets the credentials (CAS service ticket).
283
* @return the service ticket
284
*/
285
public Object getCredentials();
286
287
/**
288
* Gets the principal (identifier).
289
* @return the identifier
290
*/
291
public Object getPrincipal();
292
293
/**
294
* Sets the authentication status.
295
* @param isAuthenticated true if authenticated
296
* @throws IllegalArgumentException if attempting to set authenticated to true
297
*/
298
public void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException;
299
300
/**
301
* Removes sensitive credential information.
302
*/
303
public void eraseCredentials();
304
}
305
```
306
307
### Service Authentication Details
308
309
Interface for providing service URL information when CAS tickets can be sent to multiple URLs.
310
311
```java { .api }
312
/**
313
* Interface for providing service URL information during authentication.
314
* Used when the service URL cannot be determined from configuration alone.
315
*/
316
public interface ServiceAuthenticationDetails extends Serializable {
317
318
/**
319
* Gets the service URL for CAS authentication.
320
* @return the service URL that CAS should redirect to
321
*/
322
String getServiceUrl();
323
}
324
```
325
326
## Authentication Flow
327
328
1. **Service Ticket Reception**: `CasAuthenticationFilter` receives CAS service ticket from callback
329
2. **Token Creation**: Creates `CasServiceTicketAuthenticationToken` with the ticket
330
3. **Provider Authentication**: `CasAuthenticationProvider` validates ticket with CAS server
331
4. **Assertion Processing**: CAS assertion is extracted from validation response
332
5. **User Details Loading**: User details are loaded via `UserDetailsService` or `AuthenticationUserDetailsService`
333
6. **Token Creation**: Final `CasAuthenticationToken` is created with user details and authorities
334
7. **Security Context**: Authentication is stored in Spring Security's `SecurityContext`
335
336
## Configuration Example
337
338
```java
339
@Bean
340
public AuthenticationManager authenticationManager() {
341
return new ProviderManager(Arrays.asList(casAuthenticationProvider()));
342
}
343
344
@Bean
345
public CasAuthenticationProvider casAuthenticationProvider() {
346
CasAuthenticationProvider provider = new CasAuthenticationProvider();
347
provider.setServiceProperties(serviceProperties());
348
provider.setTicketValidator(ticketValidator());
349
provider.setUserDetailsService(userDetailsService());
350
provider.setKey("cas-provider-key");
351
provider.setAuthoritiesMapper(authoritiesMapper());
352
return provider;
353
}
354
355
@Bean
356
public TicketValidator ticketValidator() {
357
Cas20ServiceTicketValidator validator = new Cas20ServiceTicketValidator("https://cas.example.com/cas");
358
validator.setAcceptAnyProxy(true);
359
return validator;
360
}
361
```
362
363
## Common Exceptions
364
365
- **BadCredentialsException**: Invalid or expired CAS ticket
366
- **TicketValidationException**: CAS server validation failure
367
- **AccountExpiredException**: User account is expired
368
- **LockedException**: User account is locked
369
- **DisabledException**: User account is disabled