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.