0
# CAS Server Core Authentication API
1
2
The CAS Server Core Authentication API module provides the foundational components for authentication processing within the CAS (Central Authentication Service) server. This module defines the core interfaces, abstract classes, and implementations for handling authentication requests, managing credentials, applying authentication policies, and resolving principals.
3
4
## Package Information
5
6
**Maven Coordinates:**
7
```xml
8
<dependency>
9
<groupId>org.apereo.cas</groupId>
10
<artifactId>cas-server-core-authentication-api</artifactId>
11
<version>${cas.version}</version>
12
</dependency>
13
```
14
15
**Java Version:** Java 11+
16
**Framework:** Spring Framework
17
**Base Package:** `org.apereo.cas.authentication`
18
19
## Core Imports
20
21
```java { .api }
22
// Core authentication management
23
import org.apereo.cas.authentication.Authentication;
24
import org.apereo.cas.authentication.AuthenticationBuilder;
25
import org.apereo.cas.authentication.AuthenticationHandler;
26
import org.apereo.cas.authentication.AuthenticationManager;
27
import org.apereo.cas.authentication.AuthenticationResult;
28
import org.apereo.cas.authentication.AuthenticationTransaction;
29
import org.apereo.cas.authentication.Credential;
30
import org.apereo.cas.authentication.Principal;
31
32
// Authentication builders and factories
33
import org.apereo.cas.authentication.DefaultAuthentication;
34
import org.apereo.cas.authentication.DefaultAuthenticationBuilder;
35
import org.apereo.cas.authentication.DefaultAuthenticationManager;
36
import org.apereo.cas.authentication.DefaultAuthenticationTransaction;
37
38
// Core utilities
39
import org.apereo.cas.authentication.CoreAuthenticationUtils;
40
import org.apereo.cas.authentication.AuthenticationHolder;
41
42
// Principal management
43
import org.apereo.cas.authentication.principal.DefaultPrincipalFactory;
44
import org.apereo.cas.authentication.principal.PrincipalFactory;
45
import org.apereo.cas.authentication.principal.PrincipalElectionStrategy;
46
import org.apereo.cas.authentication.principal.SimplePrincipal;
47
48
// Common credentials
49
import org.apereo.cas.authentication.credential.UsernamePasswordCredential;
50
import org.apereo.cas.authentication.credential.RememberMeUsernamePasswordCredential;
51
import org.apereo.cas.authentication.credential.OneTimePasswordCredential;
52
import org.apereo.cas.authentication.credential.BasicIdentifiableCredential;
53
```
54
55
## Basic Usage
56
57
### Creating and Managing Authentication
58
59
```java { .api }
60
// Create authentication manager
61
AuthenticationManager authenticationManager = new DefaultAuthenticationManager(
62
authenticationEventExecutionPlan,
63
authenticationHandlerResolvers,
64
authenticationTransactionFactory
65
);
66
67
// Create authentication transaction
68
AuthenticationTransaction transaction = DefaultAuthenticationTransaction.of(credential);
69
70
// Perform authentication
71
AuthenticationResult result = authenticationManager.authenticate(transaction);
72
Authentication authentication = result.getAuthentication();
73
```
74
75
### Working with Credentials
76
77
```java { .api }
78
// Username/password authentication
79
UsernamePasswordCredential credential = new UsernamePasswordCredential("username", "password");
80
81
// Remember-me authentication
82
RememberMeUsernamePasswordCredential rememberMeCredential =
83
new RememberMeUsernamePasswordCredential("username", "password", true);
84
85
// One-time password
86
OneTimePasswordCredential otpCredential = new OneTimePasswordCredential("user", "123456");
87
88
// Validate credentials
89
ValidationContext context = new ValidationContext();
90
boolean isValid = credential.validate(context);
91
```
92
93
### Principal Management
94
95
```java { .api }
96
// Create principal factory
97
PrincipalFactory principalFactory = new DefaultPrincipalFactory();
98
99
// Create principal with attributes
100
Map<String, Object> attributes = Map.of(
101
"email", "user@example.com",
102
"role", "admin"
103
);
104
Principal principal = principalFactory.createPrincipal("username", attributes);
105
106
// Principal election strategy
107
PrincipalElectionStrategy electionStrategy = new DefaultPrincipalElectionStrategy();
108
Principal elected = electionStrategy.electPrincipal(authentications);
109
```
110
111
### Authentication Context Management
112
113
```java { .api }
114
// Store authentication in thread-local context
115
AuthenticationHolder.setCurrentAuthentication(authentication);
116
117
// Retrieve current authentication
118
Authentication current = AuthenticationHolder.getCurrentAuthentication();
119
120
// Clear authentication context
121
AuthenticationHolder.clear();
122
```
123
124
## Architecture
125
126
The CAS authentication API is organized around several core concepts:
127
128
### Authentication Flow
129
1. **Credential Submission** - Users provide credentials through various means
130
2. **Authentication Handler Processing** - Handlers validate credentials against data sources
131
3. **Principal Resolution** - User principals are resolved and populated with attributes
132
4. **Policy Enforcement** - Authentication policies are applied to determine success
133
5. **Result Creation** - Authentication results are constructed and returned
134
135
### Key Components
136
137
#### Authentication Manager
138
Central component that orchestrates the authentication process, managing handlers, policies, and transaction flow.
139
140
#### Authentication Handlers
141
Components responsible for validating specific credential types against authentication sources (LDAP, database, etc.).
142
143
#### Principal Resolvers
144
Components that resolve user principals and populate them with attributes from various sources.
145
146
#### Authentication Policies
147
Components that determine whether authentication requirements are satisfied based on configured rules.
148
149
#### Credential Types
150
Various credential implementations supporting different authentication methods and protocols.
151
152
## Capabilities
153
154
### Authentication Handlers
155
Comprehensive support for various authentication methods and data sources.
156
157
```java { .api }
158
// Abstract base handler
159
public abstract class AbstractAuthenticationHandler implements AuthenticationHandler {
160
protected AbstractAuthenticationHandler(String name, ServicesManager servicesManager,
161
PrincipalFactory principalFactory, Integer order) { }
162
163
public abstract boolean supports(Credential credential);
164
public abstract AuthenticationHandlerExecutionResult authenticate(Credential credential)
165
throws GeneralSecurityException, PreventedException;
166
}
167
168
// Username/password handler
169
public class AcceptUsersAuthenticationHandler extends AbstractUsernamePasswordAuthenticationHandler {
170
public AcceptUsersAuthenticationHandler(Map<String, String> users) { }
171
}
172
```
173
174
[Authentication Handlers →](./authentication-handlers.md)
175
176
### Principal Resolution
177
Flexible principal resolution and attribute management system.
178
179
```java { .api }
180
// Principal factory
181
public interface PrincipalFactory {
182
Principal createPrincipal(String id);
183
Principal createPrincipal(String id, Map<String, Object> attributes);
184
}
185
186
// Principal election strategy
187
public interface PrincipalElectionStrategy {
188
Principal electPrincipal(Collection<Authentication> authentications);
189
}
190
191
// Attribute merging
192
public interface AttributeMerger {
193
Map<String, List<Object>> mergeAttributes(Map<String, List<Object>> toModify,
194
Map<String, List<Object>> toMerge);
195
}
196
```
197
198
[Principal Resolution →](./principal-resolution.md)
199
200
### Authentication Policies
201
Configurable policies for authentication requirements and validation.
202
203
```java { .api }
204
// Base authentication policy
205
public abstract class BaseAuthenticationPolicy implements AuthenticationPolicy {
206
public abstract AuthenticationPolicyExecutionResult execute(AuthenticationTransaction transaction)
207
throws Exception;
208
}
209
210
// Policy implementations
211
public class AllAuthenticationHandlersSucceededAuthenticationPolicy extends BaseAuthenticationPolicy { }
212
public class AtLeastOneCredentialValidatedAuthenticationPolicy extends BaseAuthenticationPolicy { }
213
public class RequiredAuthenticationHandlerAuthenticationPolicy extends BaseAuthenticationPolicy { }
214
```
215
216
[Authentication Policies →](./authentication-policies.md)
217
218
### Credential Handling
219
Support for various credential types and validation mechanisms.
220
221
```java { .api }
222
// Base credential class
223
public abstract class AbstractCredential implements Credential {
224
public abstract String getId();
225
public boolean isValid() { return true; }
226
public void validate(ValidationContext context) throws Exception { }
227
}
228
229
// Credential implementations
230
public class UsernamePasswordCredential extends AbstractCredential { }
231
public class OneTimePasswordCredential extends AbstractCredential { }
232
public class OneTimeTokenCredential extends AbstractCredential { }
233
public class HttpBasedServiceCredential extends AbstractCredential { }
234
```
235
236
[Credential Handling →](./credential-handling.md)
237
238
### Password Policies
239
Comprehensive password policy support and enforcement.
240
241
```java { .api }
242
// Password policy handling strategy
243
public interface AuthenticationPasswordPolicyHandlingStrategy {
244
List<MessageDescriptor> handle(Principal principal, PasswordPolicyContext passwordPolicyConfiguration)
245
throws Exception;
246
}
247
248
// Password policy context
249
public class PasswordPolicyContext {
250
public PasswordPolicyContext(PasswordPolicy passwordPolicy) { }
251
public PasswordPolicy getPasswordPolicy() { }
252
}
253
```
254
255
[Password Policies →](./password-policies.md)
256
257
### Adaptive Authentication
258
Risk-based authentication and adaptive security measures.
259
260
```java { .api }
261
// Adaptive authentication policy
262
public interface AdaptiveAuthenticationPolicy {
263
boolean isAuthenticationRequestAllowed(RequestContext requestContext,
264
String userAgent,
265
GeoLocationRequest location);
266
}
267
268
// IP address intelligence
269
public interface IPAddressIntelligenceService {
270
IPAddressIntelligenceResponse examine(RequestContext requestContext, String clientIpAddress);
271
}
272
```
273
274
[Adaptive Authentication →](./adaptive-authentication.md)
275
276
### Core Utilities
277
278
```java { .api }
279
// Authentication utilities
280
public class CoreAuthenticationUtils {
281
public static Map<String, Object> convertAttributeValuesToObjects(Map<String, ?> attributes);
282
public static AttributeMerger getAttributeMerger(PrincipalAttributesCoreProperties.MergingStrategyTypes mergingPolicy);
283
public static boolean isRememberMeAuthentication(Authentication authentication);
284
public static Predicate<Credential> newCredentialSelectionPredicate(String selectionCriteria);
285
public static List<AuthenticationPolicy> newAuthenticationPolicy(AuthenticationPolicyProperties policyProps);
286
}
287
288
// SSL context management
289
public interface CasSSLContext {
290
SSLContext getSslContext();
291
TrustManager[] getTrustManagers();
292
KeyManager[] getKeyManagers();
293
HostnameVerifier getHostnameVerifier();
294
295
static CasSSLContext system() { }
296
static CasSSLContext disabled() { }
297
}
298
```
299
300
### Exception Handling
301
302
The API provides comprehensive exception handling for authentication failures:
303
304
```java { .api }
305
// Account-related exceptions
306
public class AccountDisabledException extends AccountException { }
307
public class AccountPasswordMustChangeException extends AccountException { }
308
public class InvalidLoginLocationException extends AccountException { }
309
public class InvalidLoginTimeException extends AccountException { }
310
311
// Principal-related exceptions
312
public class MixedPrincipalException extends Exception { }
313
public class UniquePrincipalRequiredException extends Exception { }
314
public class UnresolvedPrincipalException extends Exception { }
315
316
// Policy exceptions
317
public class UnsatisfiedAuthenticationPolicyException extends AbstractTicketException { }
318
```
319
320
This API provides a complete foundation for implementing authentication workflows in CAS server deployments, with extensive configuration options and extensibility points for custom requirements.