0
# CAS Surrogate Authentication API
1

2
A comprehensive API for implementing surrogate authentication functionality in the Apereo CAS (Central Authentication Service) ecosystem. This library provides the core interfaces, data classes, and service access strategies needed to enable authorized users to impersonate other users for administrative and support purposes.
3

4
## Package Information
5

6
- **Package Name**: org.apereo.cas:cas-server-support-surrogate-api
7
- **Language**: Java
8
- **Build System**: Gradle
9
- **Installation**: Include as dependency in CAS module or application
10

11
## Core Imports
12

13
```java
14
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationService;
15
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationRequest;
16
import org.apereo.cas.authentication.surrogate.SurrogateCredentialTrait;
17
import org.apereo.cas.authentication.surrogate.SurrogateCredentialParser;
18
import org.apereo.cas.services.SurrogateRegisteredServiceAccessStrategy;
19
import org.apereo.cas.services.BaseSurrogateRegisteredServiceAccessStrategy;
20
import org.apereo.cas.services.GroovySurrogateRegisteredServiceAccessStrategy;
21
import org.apereo.cas.authentication.AuthenticationBuilder;
22
import org.apereo.cas.authentication.principal.Principal;
23
import org.apereo.cas.authentication.principal.Service;
24
import org.apereo.cas.authentication.MutableCredential;
25
import org.slf4j.Logger;
26
import org.slf4j.LoggerFactory;
27
```
28

29
## Basic Usage
30

31
```java
32
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationService;
33
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationRequest;
34
import org.apereo.cas.authentication.principal.Principal;
35
import org.apereo.cas.authentication.principal.Service;
36

37
import java.util.Collection;
38
import java.util.Optional;
39

40
// Implement surrogate authentication service
41
public class CustomSurrogateAuthenticationService implements SurrogateAuthenticationService {
42
    
43
    @Override
44
    public Collection<String> getImpersonationAccounts(String username, Optional<? extends Service> service) throws Throwable {
45
        // Return list of accounts this user can impersonate
46
        return java.util.Arrays.asList("user1", "user2", "admin");
47
    }
48

49
    @Override
50
    public boolean canImpersonate(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable {
51
        // Check if principal can impersonate the surrogate user
52
        Collection<String> accounts = getImpersonationAccounts(principal.getId(), service);
53
        return accounts.contains(surrogate) || isWildcardedAccount(accounts, service);
54
    }
55
}
56

57
// Create surrogate authentication request
58
SurrogateAuthenticationRequest request = SurrogateAuthenticationRequest.builder()
59
    .credential(mutableCredential)
60
    .username("admin")
61
    .surrogateUsername("targetUser")
62
    .selectable(true)
63
    .build();
64

65
// Check if request has surrogate username
66
if (request.hasSurrogateUsername()) {
67
    // Process surrogate authentication
68
}
69
```
70

71
## Architecture
72

73
The surrogate authentication API follows a layered architecture:
74

75
- **Service Layer**: `SurrogateAuthenticationService` defines core impersonation logic
76
- **Request Layer**: `SurrogateAuthenticationRequest` and parsing components handle authentication flow
77
- **Access Control Layer**: Service access strategies control surrogate authentication at service level
78
- **Credential Layer**: Traits and parsers integrate with CAS credential handling framework
79

80
This design enables flexible backend integration (LDAP, JDBC, REST APIs) and fine-grained access control through CAS's service management framework.
81

82
## Capabilities
83

84
### Core Authentication Service
85

86
Primary interface for surrogate authentication operations including permission checking, account enumeration, and wildcard support for super-administrators.
87

88
```java { .api }
89
@FunctionalInterface
90
public interface SurrogateAuthenticationService {
91
    /**
92
     * Logger instance.
93
     */
94
    Logger LOGGER = LoggerFactory.getLogger(SurrogateAuthenticationService.class);
95
    
96
    /**
97
     * An authorized account may be tagged as a wildcard, meaning
98
     * that the account has special permissions to impersonate anyone.
99
     */
100
    String WILDCARD_ACCOUNT = "*";
101

102
    /**
103
     * Default bean name.
104
     */
105
    String BEAN_NAME = "surrogateAuthenticationService";
106

107
    /**
108
     * Surrogate username attribute in the authentication payload.
109
     */
110
    String AUTHENTICATION_ATTR_SURROGATE_USER = "surrogateUser";
111
    
112
    /**
113
     * Original credential attribute in the authentication payload.
114
     */
115
    String AUTHENTICATION_ATTR_SURROGATE_PRINCIPAL = "surrogatePrincipal";
116
    
117
    /**
118
     * Indicates that surrogate authn is enabled and activated.
119
     */
120
    String AUTHENTICATION_ATTR_SURROGATE_ENABLED = "surrogateEnabled";
121

122
    Collection<String> getImpersonationAccounts(String username, Optional<? extends Service> service) throws Throwable;
123
    
124
    default boolean canImpersonate(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable;
125
    default boolean isWildcardedAccount(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable;
126
    default boolean isWildcardedAccount(Collection<String> accounts, Optional<? extends Service> service);
127
    default void collectSurrogateAttributes(AuthenticationBuilder builder, String surrogateUser, String principal);
128
}
129
```
130

131
[Authentication Service](./authentication-service.md)
132

133
### Request and Credential Handling
134

135
Data classes and parsers for managing surrogate authentication requests, credential traits, and integration with CAS authentication flow.
136

137
```java { .api }
138
@ToString
139
@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
140
@Getter
141
@NoArgsConstructor(force = true)
142
@EqualsAndHashCode
143
@RequiredArgsConstructor
144
@SuperBuilder
145
public class SurrogateAuthenticationRequest implements Serializable {
146
    private final MutableCredential credential;
147
    private final String username;
148
    private final String surrogateUsername;
149
    private final boolean selectable;
150
    
151
    boolean hasSurrogateUsername();
152
}
153

154
@ToString
155
@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
156
@Getter
157
@NoArgsConstructor(force = true)
158
@EqualsAndHashCode
159
@RequiredArgsConstructor
160
public class SurrogateCredentialTrait implements CredentialTrait {
161
    private final String surrogateUsername;
162
}
163

164
@FunctionalInterface
165
public interface SurrogateCredentialParser {
166
    String BEAN_NAME = "surrogateCredentialParser";
167
    
168
    Optional<SurrogateAuthenticationRequest> parse(MutableCredential credential);
169
}
170
```
171

172
[Request and Credential Handling](./request-credential-handling.md)
173

174
### Service Access Control
175

176
Service-level access strategies for controlling surrogate authentication permissions at the individual service level, including attribute-based and script-based authorization.
177

178
```java { .api }
179
public abstract class BaseSurrogateRegisteredServiceAccessStrategy extends BaseRegisteredServiceAccessStrategy {
180
    protected boolean isSurrogateAuthenticationSession(RegisteredServiceAccessStrategyRequest request);
181
}
182

183
@Getter
184
@Setter
185
@EqualsAndHashCode(callSuper = true)
186
public class SurrogateRegisteredServiceAccessStrategy extends BaseSurrogateRegisteredServiceAccessStrategy {
187
    protected boolean requireAllAttributes = true;
188
    protected boolean caseInsensitive;
189
    private Map<String, Set<String>> surrogateRequiredAttributes = new HashMap<>(0);
190
    
191
    boolean authorizeRequest(RegisteredServiceAccessStrategyRequest request);
192
    protected boolean doPrincipalAttributesAllowSurrogateServiceAccess(RegisteredServiceAccessStrategyRequest request);
193
}
194

195
@Slf4j
196
@Getter
197
@Setter
198
@EqualsAndHashCode(callSuper = true)
199
public class GroovySurrogateRegisteredServiceAccessStrategy extends BaseSurrogateRegisteredServiceAccessStrategy {
200
    @ExpressionLanguageCapable
201
    private String groovyScript;
202
    
203
    boolean authorizeRequest(RegisteredServiceAccessStrategyRequest request) throws Throwable;
204
}
205
```
206

207
[Service Access Control](./service-access-control.md)