0
# Authentication Service
1

2
The `SurrogateAuthenticationService` interface provides the core functionality for surrogate authentication operations in CAS. It defines methods for checking impersonation permissions, retrieving allowed accounts, handling wildcard permissions, and managing authentication attributes.
3

4
## Capabilities
5

6
### Core Service Interface
7

8
The primary interface for surrogate authentication logic.
9

10
```java { .api }
11
@FunctionalInterface
12
public interface SurrogateAuthenticationService {
13
    /**
14
     * Gets a collection of account names a surrogate can authenticate as.
15
     *
16
     * @param username The username of the surrogate
17
     * @param service  the service
18
     * @return collection of usernames
19
     * @throws Throwable the throwable
20
     */
21
    Collection<String> getImpersonationAccounts(String username, Optional<? extends Service> service) throws Throwable;
22

23
    /**
24
     * Checks whether a principal can authenticate as a surrogate user.
25
     *
26
     * @param surrogate The username of the surrogate
27
     * @param principal the principal
28
     * @param service   the service
29
     * @return true if the given surrogate can authenticate as the user
30
     * @throws Throwable the throwable
31
     */
32
    default boolean canImpersonate(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable {
33
        return false;
34
    }
35

36
    /**
37
     * Is wildcarded account authorized?.
38
     *
39
     * @param surrogate the surrogate
40
     * @param principal the principal
41
     * @param service   the service
42
     * @return true /false
43
     * @throws Throwable the throwable
44
     */
45
    default boolean isWildcardedAccount(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable {
46
        Collection<String> accounts = getImpersonationAccounts(principal.getId(), service);
47
        return isWildcardedAccount(accounts, service);
48
    }
49

50
    /**
51
     * Is wildcarded account accepted and found in the given accounts?.
52
     *
53
     * @param accounts the accounts
54
     * @param service  the service
55
     * @return true /false
56
     */
57
    default boolean isWildcardedAccount(Collection<String> accounts, Optional<? extends Service> service) {
58
        return accounts.size() == 1 && accounts.contains(SurrogateAuthenticationService.WILDCARD_ACCOUNT);
59
    }
60

61
    /**
62
     * Collect surrogate attributes.
63
     *
64
     * @param builder       the builder
65
     * @param surrogateUser the surrogate user
66
     * @param principal     the principal
67
     */
68
    default void collectSurrogateAttributes(AuthenticationBuilder builder, String surrogateUser, String principal) {
69
        LOGGER.debug("Recording surrogate username [{}] as an authentication attribute", surrogateUser);
70
        builder.addAttribute(SurrogateAuthenticationService.AUTHENTICATION_ATTR_SURROGATE_USER, surrogateUser);
71
        builder.addAttribute(SurrogateAuthenticationService.AUTHENTICATION_ATTR_SURROGATE_PRINCIPAL, principal);
72
        builder.addAttribute(SurrogateAuthenticationService.AUTHENTICATION_ATTR_SURROGATE_ENABLED, Boolean.TRUE);
73
    }
74
}
75
```
76

77
### Constants and Attributes
78

79
Important constants used throughout the surrogate authentication system.
80

81
```java { .api }
82
public interface SurrogateAuthenticationService {
83
    /**
84
     * An authorized account may be tagged as a wildcard, meaning
85
     * that the account has special permissions to impersonate anyone.
86
     */
87
    String WILDCARD_ACCOUNT = "*";
88

89
    /**
90
     * Default bean name.
91
     */
92
    String BEAN_NAME = "surrogateAuthenticationService";
93

94
    /**
95
     * Surrogate username attribute in the authentication payload.
96
     */
97
    String AUTHENTICATION_ATTR_SURROGATE_USER = "surrogateUser";
98
    
99
    /**
100
     * Original credential attribute in the authentication payload.
101
     */
102
    String AUTHENTICATION_ATTR_SURROGATE_PRINCIPAL = "surrogatePrincipal";
103
    
104
    /**
105
     * Indicates that surrogate authn is enabled and activated.
106
     */
107
    String AUTHENTICATION_ATTR_SURROGATE_ENABLED = "surrogateEnabled";
108

109
    /**
110
     * Logger instance.
111
     */
112
    Logger LOGGER = LoggerFactory.getLogger(SurrogateAuthenticationService.class);
113
}
114
```
115

116
## Usage Examples
117

118
### Basic Implementation
119

120
```java
121
import org.apereo.cas.authentication.surrogate.SurrogateAuthenticationService;
122
import org.apereo.cas.authentication.principal.Principal;
123
import org.apereo.cas.authentication.principal.Service;
124

125
import java.util.*;
126

127
public class SimpleSurrogateAuthenticationService implements SurrogateAuthenticationService {
128
    
129
    private final Map<String, List<String>> surrogateMap;
130
    
131
    public SimpleSurrogateAuthenticationService(Map<String, List<String>> surrogateMap) {
132
        this.surrogateMap = surrogateMap;
133
    }
134

135
    @Override
136
    public Collection<String> getImpersonationAccounts(String username, Optional<? extends Service> service) throws Throwable {
137
        return surrogateMap.getOrDefault(username, Collections.emptyList());
138
    }
139

140
    @Override
141
    public boolean canImpersonate(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable {
142
        Collection<String> accounts = getImpersonationAccounts(principal.getId(), service);
143
        return accounts.contains(surrogate) || isWildcardedAccount(accounts, service);
144
    }
145
}
146
```
147

148
### Wildcard Administrator Example
149

150
```java
151
// Service that grants wildcard permissions to administrators
152
public class AdminSurrogateAuthenticationService implements SurrogateAuthenticationService {
153
    
154
    private final Set<String> administrators;
155
    
156
    public AdminSurrogateAuthenticationService(Set<String> administrators) {
157
        this.administrators = administrators;
158
    }
159

160
    @Override  
161
    public Collection<String> getImpersonationAccounts(String username, Optional<? extends Service> service) throws Throwable {
162
        if (administrators.contains(username)) {
163
            return Collections.singletonList(SurrogateAuthenticationService.WILDCARD_ACCOUNT);
164
        }
165
        return Collections.emptyList();
166
    }
167

168
    @Override
169
    public boolean canImpersonate(String surrogate, Principal principal, Optional<? extends Service> service) throws Throwable {
170
        return administrators.contains(principal.getId());
171
    }
172
}
173
```
174

175
### Authentication Attribute Collection
176

177
```java
178
import org.apereo.cas.authentication.AuthenticationBuilder;
179

180
// During authentication flow
181
SurrogateAuthenticationService service = // ... get service instance
182
AuthenticationBuilder builder = // ... authentication builder
183

184
// Collect surrogate attributes for authentication context
185
service.collectSurrogateAttributes(builder, "targetUser", "adminUser");
186

187
// The builder now contains:
188
// - surrogateUser: "targetUser" 
189
// - surrogatePrincipal: "adminUser"
190
// - surrogateEnabled: true
191
```
192

193
## Required Dependencies
194

195
This interface depends on types from:
196

197
```java
198
import org.apereo.cas.authentication.AuthenticationBuilder;
199
import org.apereo.cas.authentication.principal.Principal;
200
import org.apereo.cas.authentication.principal.Service;
201
import org.slf4j.Logger;
202
import org.slf4j.LoggerFactory;
203

204
import java.util.Collection;
205
import java.util.Optional;
206
```