0
# Request and Credential Handling
1

2
This module provides data classes and parsing interfaces for managing surrogate authentication requests and integrating with CAS's credential handling framework. These components bridge the gap between user input, credential processing, and the core surrogate authentication service.
3

4
## Capabilities
5

6
### Surrogate Authentication Request
7

8
A data class representing a complete surrogate authentication request with all necessary context information.
9

10
```java { .api }
11
@ToString
12
@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
13
@Getter
14
@NoArgsConstructor(force = true)
15
@EqualsAndHashCode
16
@RequiredArgsConstructor
17
@SuperBuilder
18
public class SurrogateAuthenticationRequest implements Serializable {
19
    
20
    /**
21
     * The authentication credential containing user information
22
     */
23
    private final MutableCredential credential;
24

25
    /**
26
     * The original username attempting authentication
27
     */
28
    private final String username;
29

30
    /**
31
     * The target username to impersonate 
32
     */
33
    private final String surrogateUsername;
34

35
    /**
36
     * Whether surrogate user selection is available/required
37
     */
38
    private final boolean selectable;
39
    
40
    /**
41
     * Has surrogate username?.
42
     *
43
     * @return true/false
44
     */
45
    public boolean hasSurrogateUsername() {
46
        return StringUtils.isNotBlank(this.surrogateUsername);
47
    }
48
}
49
```
50

51
### Surrogate Credential Trait
52

53
A credential trait for marking credentials with surrogate authentication context.
54

55
```java { .api }
56
@ToString
57
@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
58
@Getter
59
@NoArgsConstructor(force = true)
60
@EqualsAndHashCode
61
@RequiredArgsConstructor
62
public class SurrogateCredentialTrait implements CredentialTrait {
63
    
64
    /**
65
     * The target surrogate username
66
     */
67
    private final String surrogateUsername;
68
}
69
```
70

71
### Surrogate Credential Parser
72

73
Interface for parsing credentials to extract surrogate authentication requests.
74

75
```java { .api }
76
@FunctionalInterface
77
public interface SurrogateCredentialParser {
78

79
    /**
80
     * Default implementation bean name.
81
     */
82
    String BEAN_NAME = "surrogateCredentialParser";
83

84
    /**
85
     * Parse surrogate authentication request.
86
     *
87
     * @param credential the credential to parse
88
     * @return the surrogate authentication request, or empty if no surrogate context found
89
     */
90
    Optional<SurrogateAuthenticationRequest> parse(MutableCredential credential);
91
}
92
```
93

94
## Usage Examples
95

96
### Creating Surrogate Authentication Requests
97

98
```java
99
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationRequest;
100
import org.apereo.cas.authentication.MutableCredential;
101

102
// Using builder pattern
103
SurrogateAuthenticationRequest request = SurrogateAuthenticationRequest.builder()
104
    .credential(mutableCredential)
105
    .username("admin")
106
    .surrogateUsername("targetUser")
107
    .selectable(true)
108
    .build();
109

110
// Check if surrogate username is present
111
if (request.hasSurrogateUsername()) {
112
    String target = request.getSurrogateUsername();
113
    String original = request.getUsername();
114
    System.out.println("User " + original + " wants to impersonate " + target);
115
}
116

117
// Using RequiredArgsConstructor (Lombok-generated)
118
SurrogateAuthenticationRequest request2 = new SurrogateAuthenticationRequest(
119
    credential, "admin", "targetUser", false
120
);
121
```
122

123
### Implementing Credential Parser
124

125
```java
126
import org.apereo.cas.authentication.surrogate.SurrogateCredentialParser;
127
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationRequest;
128
import org.apereo.cas.authentication.MutableCredential;
129

130
import java.util.Optional;
131

132
public class CustomSurrogateCredentialParser implements SurrogateCredentialParser {
133
    
134
    @Override
135
    public Optional<SurrogateAuthenticationRequest> parse(MutableCredential credential) {
136
        // Check if credential contains surrogate context
137
        String username = credential.getId();
138
        
139
        // Example: Parse username+surrogate format like "admin+targetUser"
140
        if (username != null && username.contains("+")) {
141
            String[] parts = username.split("\\+", 2);
142
            if (parts.length == 2) {
143
                String originalUser = parts[0];
144
                String surrogateUser = parts[1];
145
                
146
                return Optional.of(SurrogateAuthenticationRequest.builder()
147
                    .credential(credential)
148
                    .username(originalUser)
149
                    .surrogateUsername(surrogateUser)
150
                    .selectable(false)
151
                    .build());
152
            }
153
        }
154
        
155
        return Optional.empty();
156
    }
157
}
158
```
159

160
### Using Credential Traits
161

162
```java
163
import org.apereo.cas.authentication.surrogate.SurrogateCredentialTrait;
164
import org.apereo.cas.authentication.MutableCredential;
165

166
// Add surrogate trait to credential
167
MutableCredential credential = // ... get credential
168
SurrogateCredentialTrait trait = new SurrogateCredentialTrait("targetUser");
169

170
// Add trait to credential (depends on credential implementation)
171
credential.getCredentialTraits().add(trait);
172

173
// Access trait later
174
Optional<SurrogateCredentialTrait> surrogateTrait = credential.getCredentialTraits()
175
    .stream()
176
    .filter(SurrogateCredentialTrait.class::isInstance)
177
    .map(SurrogateCredentialTrait.class::cast)
178
    .findFirst();
179

180
if (surrogateTrait.isPresent()) {
181
    String surrogateUsername = surrogateTrait.get().getSurrogateUsername();
182
    // Process surrogate authentication
183
}
184
```
185

186
### JSON Serialization
187

188
Both `SurrogateAuthenticationRequest` and `SurrogateCredentialTrait` support JSON serialization via Jackson annotations:
189

190
```java
191
import com.fasterxml.jackson.databind.ObjectMapper;
192

193
ObjectMapper mapper = new ObjectMapper();
194

195
// Serialize request
196
SurrogateAuthenticationRequest request = // ... create request
197
String json = mapper.writeValueAsString(request);
198

199
// Deserialize request  
200
SurrogateAuthenticationRequest restored = mapper.readValue(json, SurrogateAuthenticationRequest.class);
201
```
202

203
## Required Dependencies
204

205
These classes depend on types from:
206

207
```java
208
import org.apereo.cas.authentication.MutableCredential;
209
import org.apereo.cas.authentication.CredentialTrait;
210

211
import com.fasterxml.jackson.annotation.JsonTypeInfo;
212
import lombok.EqualsAndHashCode;
213
import lombok.Getter;
214
import lombok.NoArgsConstructor;
215
import lombok.RequiredArgsConstructor;
216
import lombok.ToString;
217
import lombok.experimental.SuperBuilder;
218
import org.apache.commons.lang3.StringUtils;
219

220
import java.io.Serial;
221
import java.io.Serializable;
222
import java.util.Optional;
223
```