0
# Web Integration
1

2
Web filters and entry points for processing CAS authentication flows, handling service ticket validation, and managing gateway authentication. These components integrate CAS authentication into the Spring Security web filter chain.
3

4
## Capabilities
5

6
### CAS Authentication Filter
7

8
Processes CAS service tickets from callback URLs and handles proxy granting ticket reception for proxy authentication scenarios.
9

10
```java { .api }
11
/**
12
 * Processes CAS service tickets and proxy authentication requests.
13
 * Must be configured in the Spring Security filter chain to handle CAS callbacks.
14
 */
15
public class CasAuthenticationFilter extends AbstractAuthenticationProcessingFilter {
16
    
17
    /**
18
     * Creates a CAS authentication filter with default settings.
19
     * Default filter processes URL pattern "/login/cas".
20
     */
21
    public CasAuthenticationFilter();
22
    
23
    /**
24
     * Attempts authentication by extracting and validating CAS service ticket.
25
     * @param request HTTP request containing CAS ticket parameter
26
     * @param response HTTP response for redirects
27
     * @return Authentication object if successful
28
     * @throws AuthenticationException if authentication fails
29
     * @throws IOException if I/O errors occur
30
     */
31
    public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response)
32
        throws AuthenticationException, IOException;
33
    
34
    /**
35
     * Determines if authentication is required for this request.
36
     * @param request the HTTP request
37
     * @param response the HTTP response
38
     * @return true if authentication should be attempted
39
     */
40
    protected boolean requiresAuthentication(HttpServletRequest request, HttpServletResponse response);
41
    
42
    /**
43
     * Extracts the CAS artifact (ticket) from the request.
44
     * @param request HTTP request containing ticket parameter
45
     * @return the CAS ticket or null if not present
46
     */
47
    protected String obtainArtifact(HttpServletRequest request);
48
    
49
    /**
50
     * Sets failure handler for proxy authentication failures.
51
     * @param proxyFailureHandler handler for proxy authentication failures
52
     */
53
    public void setProxyAuthenticationFailureHandler(AuthenticationFailureHandler proxyFailureHandler);
54
    
55
    /**
56
     * Sets failure handler for regular authentication failures.
57
     * @param failureHandler handler for authentication failures
58
     */
59
    public void setAuthenticationFailureHandler(AuthenticationFailureHandler failureHandler);
60
    
61
    /**
62
     * Sets request matcher for identifying proxy receptor requests.
63
     * @param proxyReceptorMatcher matcher for proxy receptor URLs
64
     */
65
    public void setProxyReceptorMatcher(RequestMatcher proxyReceptorMatcher);
66
    
67
    /**
68
     * Sets the proxy receptor URL for receiving proxy granting tickets.
69
     * @param proxyReceptorUrl URL pattern for proxy ticket reception
70
     */
71
    public void setProxyReceptorUrl(String proxyReceptorUrl);
72
    
73
    /**
74
     * Sets storage for proxy granting tickets.
75
     * @param proxyGrantingTicketStorage storage implementation for PGTs
76
     */
77
    public void setProxyGrantingTicketStorage(ProxyGrantingTicketStorage proxyGrantingTicketStorage);
78
    
79
    /**
80
     * Sets service properties for CAS integration.
81
     * @param serviceProperties CAS service configuration
82
     */
83
    public void setServiceProperties(ServiceProperties serviceProperties);
84
    
85
    /**
86
     * Sets security context repository for storing authentication.
87
     * @param securityContextRepository repository for security context persistence
88
     */
89
    public void setSecurityContextRepository(SecurityContextRepository securityContextRepository);
90
    
91
    /**
92
     * Sets security context holder strategy.
93
     * @param securityContextHolderStrategy strategy for managing security context
94
     */
95
    public void setSecurityContextHolderStrategy(SecurityContextHolderStrategy securityContextHolderStrategy);
96
    
97
    /**
98
     * Sets redirect strategy for handling redirects.
99
     * @param redirectStrategy strategy for performing redirects
100
     */
101
    public void setRedirectStrategy(RedirectStrategy redirectStrategy);
102
    
103
    /**
104
     * Sets request cache for saving original requests.
105
     * @param requestCache cache for storing original requests before authentication
106
     */
107
    public void setRequestCache(RequestCache requestCache);
108
}
109
```
110

111
**Usage Example:**
112

113
```java
114
@Bean
115
public CasAuthenticationFilter casAuthenticationFilter() throws Exception {
116
    CasAuthenticationFilter filter = new CasAuthenticationFilter();
117
    filter.setAuthenticationManager(authenticationManager());
118
    filter.setServiceProperties(serviceProperties());
119
    filter.setAuthenticationSuccessHandler(successHandler());
120
    filter.setAuthenticationFailureHandler(failureHandler());
121
    return filter;
122
}
123
```
124

125
### CAS Authentication Entry Point
126

127
Initiates CAS authentication by redirecting unauthenticated users to the CAS server login page.
128

129
```java { .api }
130
/**
131
 * Authentication entry point that redirects users to CAS server for authentication.
132
 * Invoked when authentication is required but user is not authenticated.
133
 */
134
public class CasAuthenticationEntryPoint implements AuthenticationEntryPoint, InitializingBean {
135
    
136
    /**
137
     * Commences authentication by redirecting to CAS login URL.
138
     * @param servletRequest the HTTP request
139
     * @param response the HTTP response
140
     * @param authenticationException exception that triggered authentication requirement
141
     * @throws IOException if I/O errors occur during redirect
142
     */
143
    public void commence(HttpServletRequest servletRequest, HttpServletResponse response,
144
                        AuthenticationException authenticationException) throws IOException;
145
    
146
    /**
147
     * Validates configuration after properties are set.
148
     * @throws IllegalArgumentException if required properties are missing
149
     */
150
    public void afterPropertiesSet() throws IllegalArgumentException;
151
    
152
    /**
153
     * Gets the CAS server login URL.
154
     * @return the login URL
155
     */
156
    public String getLoginUrl();
157
    
158
    /**
159
     * Gets the service properties configuration.
160
     * @return the service properties
161
     */
162
    public ServiceProperties getServiceProperties();
163
    
164
    /**
165
     * Sets the CAS server login URL.
166
     * @param loginUrl URL of CAS server login page (required)
167
     */
168
    public void setLoginUrl(String loginUrl);
169
    
170
    /**
171
     * Sets service properties for CAS integration.
172
     * @param serviceProperties CAS service configuration (required)
173
     */
174
    public void setServiceProperties(ServiceProperties serviceProperties);
175
    
176
    /**
177
     * Sets whether to encode service URL with session ID.
178
     * @param encodeServiceUrlWithSessionId true to encode session ID in service URL
179
     */
180
    public void setEncodeServiceUrlWithSessionId(boolean encodeServiceUrlWithSessionId);
181
    
182
    /**
183
     * Sets redirect strategy for performing redirects.
184
     * @param redirectStrategy strategy for handling redirects
185
     */
186
    public void setRedirectStrategy(RedirectStrategy redirectStrategy);
187
    
188
    /**
189
     * Creates service URL for CAS authentication request.
190
     * @param request the HTTP request
191
     * @param response the HTTP response
192
     * @return the service URL for CAS callback
193
     */
194
    protected String createServiceUrl(HttpServletRequest request, HttpServletResponse response);
195
    
196
    /**
197
     * Creates full redirect URL including service parameter.
198
     * @param serviceUrl the service URL for CAS callback
199
     * @return complete CAS login URL with service parameter
200
     */
201
    protected String createRedirectUrl(String serviceUrl);
202
    
203
    /**
204
     * Hook method called before redirect is performed.
205
     * @param request the HTTP request
206
     * @param response the HTTP response
207
     */
208
    protected void preCommence(HttpServletRequest request, HttpServletResponse response);
209
    
210
    /**
211
     * Gets the encode service URL with session ID setting.
212
     * @return true if service URL should include session ID
213
     */
214
    protected boolean getEncodeServiceUrlWithSessionId();
215
}
216
```
217

218
**Usage Example:**
219

220
```java
221
@Bean
222
public CasAuthenticationEntryPoint casAuthenticationEntryPoint() {
223
    CasAuthenticationEntryPoint entryPoint = new CasAuthenticationEntryPoint();
224
    entryPoint.setLoginUrl("https://cas.example.com/cas/login");
225
    entryPoint.setServiceProperties(serviceProperties());
226
    entryPoint.setEncodeServiceUrlWithSessionId(false);
227
    return entryPoint;
228
}
229
```
230

231
### Gateway Authentication Redirect Filter
232

233
Handles CAS gateway authentication by redirecting requests to CAS server with gateway=true parameter for optional SSO.
234

235
```java { .api }
236
/**
237
 * Filter that redirects requests to CAS server with gateway=true parameter.
238
 * Enables optional Single Sign-On where authentication is attempted but not required.
239
 */
240
public final class CasGatewayAuthenticationRedirectFilter extends GenericFilterBean {
241
    
242
    /** Request attribute key for gateway authentication marker */
243
    public static final String CAS_GATEWAY_AUTHENTICATION_ATTR = "CAS_GATEWAY_AUTHENTICATION";
244
    
245
    /**
246
     * Creates gateway redirect filter with CAS login URL and service properties.
247
     * @param casLoginUrl URL of CAS server login page
248
     * @param serviceProperties service configuration for CAS
249
     */
250
    public CasGatewayAuthenticationRedirectFilter(String casLoginUrl, ServiceProperties serviceProperties);
251
    
252
    /**
253
     * Processes request and performs gateway redirect if appropriate.
254
     * @param req the servlet request
255
     * @param res the servlet response
256
     * @param chain the filter chain
257
     * @throws IOException if I/O errors occur
258
     * @throws ServletException if servlet errors occur
259
     */
260
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
261
        throws IOException, ServletException;
262
    
263
    /**
264
     * Sets request matcher for determining when to perform gateway authentication.
265
     * @param requestMatcher matcher for gateway authentication requests
266
     */
267
    public void setRequestMatcher(RequestMatcher requestMatcher);
268
    
269
    /**
270
     * Sets request cache for storing original requests.
271
     * @param requestCache cache for saving requests before redirect
272
     */
273
    public void setRequestCache(RequestCache requestCache);
274
}
275
```
276

277
**Usage Example:**
278

279
```java
280
@Bean
281
public CasGatewayAuthenticationRedirectFilter gatewayFilter() {
282
    CasGatewayAuthenticationRedirectFilter filter = 
283
        new CasGatewayAuthenticationRedirectFilter(
284
            "https://cas.example.com/cas/login",
285
            serviceProperties()
286
        );
287
    filter.setRequestMatcher(new AntPathRequestMatcher("/protected/**"));
288
    return filter;
289
}
290
```
291

292
### Gateway Resolver Request Matcher
293

294
Request matcher that delegates to GatewayResolver to prevent infinite gateway authentication loops.
295

296
```java { .api }
297
/**
298
 * Request matcher that uses GatewayResolver to determine if gateway authentication
299
 * should be attempted, preventing infinite redirect loops.
300
 */
301
public final class CasGatewayResolverRequestMatcher implements RequestMatcher {
302
    
303
    /**
304
     * Creates gateway resolver request matcher with service properties.
305
     * @param serviceProperties service configuration for CAS
306
     */
307
    public CasGatewayResolverRequestMatcher(ServiceProperties serviceProperties);
308
    
309
    /**
310
     * Determines if the request matches gateway authentication criteria.
311
     * @param request the HTTP request to evaluate
312
     * @return true if gateway authentication should be attempted
313
     */
314
    public boolean matches(HttpServletRequest request);
315
    
316
    /**
317
     * Sets gateway storage resolver for tracking gateway attempts.
318
     * @param gatewayStorage resolver for managing gateway state
319
     */
320
    public void setGatewayStorage(GatewayResolver gatewayStorage);
321
}
322
```
323

324
### Service Authentication Details Source
325

326
Creates ServiceAuthenticationDetails objects for requests where service URL needs to be determined dynamically.
327

328
```java { .api }
329
/**
330
 * Authentication details source that creates ServiceAuthenticationDetails
331
 * for dynamic service URL determination during CAS authentication.
332
 */
333
public class ServiceAuthenticationDetailsSource 
334
    implements AuthenticationDetailsSource<HttpServletRequest, ServiceAuthenticationDetails> {
335
    
336
    /**
337
     * Creates details source with service properties.
338
     * @param serviceProperties base service configuration
339
     */
340
    public ServiceAuthenticationDetailsSource(ServiceProperties serviceProperties);
341
    
342
    /**
343
     * Creates details source with custom artifact parameter name.
344
     * @param serviceProperties base service configuration
345
     * @param artifactParameterName custom artifact parameter name
346
     */
347
    public ServiceAuthenticationDetailsSource(ServiceProperties serviceProperties, String artifactParameterName);
348
    
349
    /**
350
     * Builds authentication details from HTTP request.
351
     * @param context the HTTP request
352
     * @return ServiceAuthenticationDetails with dynamic service URL
353
     */
354
    public ServiceAuthenticationDetails buildDetails(HttpServletRequest context);
355
}
356
```
357

358
## Filter Chain Configuration
359

360
Example Spring Security configuration integrating CAS filters:
361

362
```java
363
@Configuration
364
@EnableWebSecurity
365
public class CasWebSecurityConfig {
366
    
367
    @Bean
368
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
369
        http
370
            .authorizeHttpRequests(authz -> authz
371
                .requestMatchers("/public/**").permitAll()
372
                .anyRequest().authenticated()
373
            )
374
            .exceptionHandling(exceptions -> exceptions
375
                .authenticationEntryPoint(casAuthenticationEntryPoint())
376
            )
377
            .addFilter(casAuthenticationFilter())
378
            .addFilterBefore(gatewayFilter(), CasAuthenticationFilter.class);
379
        
380
        return http.build();
381
    }
382
    
383
    @Bean
384
    public CasAuthenticationFilter casAuthenticationFilter() throws Exception {
385
        CasAuthenticationFilter filter = new CasAuthenticationFilter();
386
        filter.setAuthenticationManager(authenticationManager());
387
        filter.setServiceProperties(serviceProperties());
388
        filter.setAuthenticationDetailsSource(authenticationDetailsSource());
389
        return filter;
390
    }
391
    
392
    @Bean
393
    public ServiceAuthenticationDetailsSource authenticationDetailsSource() {
394
        return new ServiceAuthenticationDetailsSource(serviceProperties());
395
    }
396
}
397
```
398

399
## URL Patterns
400

401
- **Authentication Filter**: Default processes `/login/cas`
402
- **Proxy Receptor**: Typically `/login/cas/proxyreceptor`
403
- **Service URLs**: Must match patterns registered with CAS server
404
- **Gateway URLs**: Can be any protected resource pattern
405

406
## Integration Notes
407

408
- Configure authentication filter URL to match CAS service registry
409
- Set appropriate success/failure handlers for authentication outcomes
410
- Use gateway authentication for optional SSO scenarios
411
- Configure proxy authentication only if proxy tickets are needed
412
- Ensure service URLs are accessible by both browsers and CAS server