0
# Constants and Configuration
1

2
This document covers the constants and configuration classes in the `org.keycloak.common.constants` package that provide predefined values for protocols, authentication mechanisms, and service configurations.
3

4
## Generic Constants
5

6
The `GenericConstants` class provides general-purpose constants used throughout Keycloak.
7

8
```java { .api }
9
public class GenericConstants {
10
    /**
11
     * Protocol prefix for classpath resources
12
     */
13
    public static final String PROTOCOL_CLASSPATH = "classpath:";
14
}
15
```
16

17
### Usage Examples
18

19
```java
20
// Use classpath protocol
21
String configPath = GenericConstants.PROTOCOL_CLASSPATH + "keycloak.conf";
22

23
// Check for classpath resources
24
if (resourceUrl.startsWith(GenericConstants.PROTOCOL_CLASSPATH)) {
25
    // Handle classpath resource loading
26
}
27
```
28

29
## Kerberos Constants
30

31
The `KerberosConstants` class provides constants for Kerberos/SPNEGO authentication configuration and processing.
32

33
### Protocol and OID Constants
34

35
```java { .api }
36
public class KerberosConstants {
37
    // HTTP authentication constants
38
    public static final String NEGOTIATE = "Negotiate";
39
    
40
    // SPNEGO and Kerberos OIDs
41
    public static final Oid SPNEGO_OID; // 1.3.6.1.5.5.2
42
    public static final Oid KRB5_OID;   // 1.2.840.113554.1.2.2  
43
    public static final Oid KRB5_NAME_OID; // 1.2.840.113554.1.2.2.1
44
}
45
```
46

47
### Configuration Constants
48

49
```java { .api }
50
public class KerberosConstants {
51
    // Main configuration properties
52
    public static final String ALLOW_KERBEROS_AUTHENTICATION = "allowKerberosAuthentication";
53
    public static final String KERBEROS_REALM = "kerberosRealm";
54
    public static final String SERVER_PRINCIPAL = "serverPrincipal";
55
    public static final String KEYTAB = "keyTab";
56
    public static final String DEBUG = "debug";
57
    
58
    // User attribute configuration
59
    public static final String KERBEROS_PRINCIPAL_ATTRIBUTE = "krbPrincipalAttribute";
60
    
61
    // Authentication mode configuration
62
    public static final String ALLOW_PASSWORD_AUTHENTICATION = "allowPasswordAuthentication";
63
    public static final String UPDATE_PROFILE_FIRST_LOGIN = "updateProfileFirstLogin";
64
    public static final String USE_KERBEROS_FOR_PASSWORD_AUTHENTICATION = "useKerberosForPasswordAuthentication";
65
}
66
```
67

68
### Internal Processing Constants
69

70
```java { .api }
71
public class KerberosConstants {
72
    // Internal SPNEGO processing
73
    public static final String RESPONSE_TOKEN = "SpnegoResponseToken";
74
    public static final String GSS_DELEGATION_CREDENTIAL = "gss_delegation_credential";
75
    public static final String GSS_DELEGATION_CREDENTIAL_DISPLAY_NAME = "gss delegation credential";
76
    public static final String AUTHENTICATED_SPNEGO_CONTEXT = "authenticatedSpnegoContext";
77
    public static final String KERBEROS_PRINCIPAL = "KERBEROS_PRINCIPAL";
78
}
79
```
80

81
### Usage Examples
82

83
```java
84
// Configure Kerberos authentication
85
Properties config = new Properties();
86
config.setProperty(KerberosConstants.ALLOW_KERBEROS_AUTHENTICATION, "true");
87
config.setProperty(KerberosConstants.KERBEROS_REALM, "EXAMPLE.COM");
88
config.setProperty(KerberosConstants.SERVER_PRINCIPAL, "HTTP/server.example.com");
89
config.setProperty(KerberosConstants.KEYTAB, "/etc/krb5.keytab");
90

91
// Check for SPNEGO authentication
92
String authHeader = request.getHeader("Authorization");
93
if (authHeader != null && authHeader.startsWith(KerberosConstants.NEGOTIATE)) {
94
    // Process SPNEGO authentication
95
}
96

97
// Handle Kerberos delegation credentials
98
Object credential = context.getAttribute(KerberosConstants.GSS_DELEGATION_CREDENTIAL);
99
if (credential != null) {
100
    // Use delegated credential
101
}
102

103
// Set Kerberos principal in session
104
session.setAttribute(KerberosConstants.KERBEROS_PRINCIPAL, principalName);
105
```
106

107
## Service Account Constants
108

109
The `ServiceAccountConstants` interface provides constants for service account functionality and protocol mapping.
110

111
### Core Service Account Constants
112

113
```java { .api }
114
public interface ServiceAccountConstants {
115
    // Authentication and scope constants
116
    String CLIENT_AUTH = "client_auth";
117
    String SERVICE_ACCOUNT_SCOPE = "service_account";
118
    
119
    // Service account user naming
120
    String SERVICE_ACCOUNT_USER_PREFIX = "service-account-";
121
    
122
    // Client identification
123
    String CLIENT_ID = "client_id";
124
}
125
```
126

127
### Protocol Mapper Constants
128

129
```java { .api }
130
public interface ServiceAccountConstants {
131
    // Protocol mapper names
132
    String CLIENT_ID_PROTOCOL_MAPPER = "Client ID";
133
    String CLIENT_HOST_PROTOCOL_MAPPER = "Client Host";
134
    String CLIENT_ADDRESS_PROTOCOL_MAPPER = "Client IP Address";
135
    
136
    // Session note keys
137
    String CLIENT_ID_SESSION_NOTE = "clientId";
138
    
139
    // Client connection attributes
140
    String CLIENT_HOST = "clientHost";
141
    String CLIENT_ADDRESS = "clientAddress";
142
}
143
```
144

145
### Usage Examples
146

147
```java
148
// Generate service account username
149
String clientId = "my-service";
150
String serviceAccountUsername = ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX + clientId;
151
// Result: "service-account-my-service"
152

153
// Check for service account authentication
154
String grantType = request.getParameter("grant_type");
155
if (ServiceAccountConstants.CLIENT_AUTH.equals(grantType)) {
156
    // Handle service account authentication
157
}
158

159
// Configure service account scope
160
Set<String> scopes = new HashSet<>();
161
scopes.add(ServiceAccountConstants.SERVICE_ACCOUNT_SCOPE);
162

163
// Set client connection information in session notes
164
Map<String, String> sessionNotes = new HashMap<>();
165
sessionNotes.put(ServiceAccountConstants.CLIENT_ID_SESSION_NOTE, clientId);
166
sessionNotes.put(ServiceAccountConstants.CLIENT_HOST, clientHost);
167
sessionNotes.put(ServiceAccountConstants.CLIENT_ADDRESS, clientAddress);
168

169
// Create protocol mapper configuration
170
Map<String, String> mapperConfig = new HashMap<>();
171
mapperConfig.put("mapper.name", ServiceAccountConstants.CLIENT_ID_PROTOCOL_MAPPER);
172
mapperConfig.put("claim.name", ServiceAccountConstants.CLIENT_ID);
173

174
// Check for service account user
175
if (username.startsWith(ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX)) {
176
    String clientId = username.substring(ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX.length());
177
    // Extract original client ID from service account username
178
}
179
```
180

181
## Configuration Patterns
182

183
### Kerberos Configuration Pattern
184

185
```java
186
public class KerberosConfig {
187
    private final Properties config;
188
    
189
    public KerberosConfig(Properties properties) {
190
        this.config = properties;
191
    }
192
    
193
    public boolean isKerberosEnabled() {
194
        return Boolean.parseBoolean(
195
            config.getProperty(KerberosConstants.ALLOW_KERBEROS_AUTHENTICATION, "false")
196
        );
197
    }
198
    
199
    public String getKerberosRealm() {
200
        return config.getProperty(KerberosConstants.KERBEROS_REALM);
201
    }
202
    
203
    public String getServerPrincipal() {
204
        return config.getProperty(KerberosConstants.SERVER_PRINCIPAL);
205
    }
206
    
207
    public String getKeytab() {
208
        return config.getProperty(KerberosConstants.KEYTAB);
209
    }
210
    
211
    public boolean isDebugEnabled() {
212
        return Boolean.parseBoolean(
213
            config.getProperty(KerberosConstants.DEBUG, "false")
214
        );
215
    }
216
}
217
```
218

219
### Service Account Utilities
220

221
```java
222
public class ServiceAccountUtils {
223
    
224
    public static String generateServiceAccountUsername(String clientId) {
225
        return ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX + clientId;
226
    }
227
    
228
    public static String extractClientIdFromServiceAccount(String username) {
229
        if (username.startsWith(ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX)) {
230
            return username.substring(ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX.length());
231
        }
232
        return null;
233
    }
234
    
235
    public static boolean isServiceAccountUser(String username) {
236
        return username != null && username.startsWith(ServiceAccountConstants.SERVICE_ACCOUNT_USER_PREFIX);
237
    }
238
    
239
    public static Map<String, String> createClientSessionNotes(String clientId, String host, String address) {
240
        Map<String, String> notes = new HashMap<>();
241
        notes.put(ServiceAccountConstants.CLIENT_ID_SESSION_NOTE, clientId);
242
        if (host != null) {
243
            notes.put(ServiceAccountConstants.CLIENT_HOST, host);
244
        }
245
        if (address != null) {
246
            notes.put(ServiceAccountConstants.CLIENT_ADDRESS, address);
247
        }
248
        return notes;
249
    }
250
}
251
```
252

253
### Protocol Processing Examples
254

255
```java
256
// SPNEGO token processing
257
public class SpnegoProcessor {
258
    
259
    public boolean isSpnegoRequest(HttpServletRequest request) {
260
        String authHeader = request.getHeader("Authorization");
261
        return authHeader != null && authHeader.startsWith(KerberosConstants.NEGOTIATE);
262
    }
263
    
264
    public void storeSpnegoResponse(HttpSession session, String responseToken) {
265
        session.setAttribute(KerberosConstants.RESPONSE_TOKEN, responseToken);
266
    }
267
    
268
    public void storeAuthenticatedContext(HttpSession session, Object context) {
269
        session.setAttribute(KerberosConstants.AUTHENTICATED_SPNEGO_CONTEXT, context);
270
    }
271
}
272

273
// Service account token validation
274
public class ServiceAccountValidator {
275
    
276
    public boolean hasServiceAccountScope(Set<String> scopes) {
277
        return scopes.contains(ServiceAccountConstants.SERVICE_ACCOUNT_SCOPE);
278
    }
279
    
280
    public boolean isClientAuthGrant(String grantType) {
281
        return ServiceAccountConstants.CLIENT_AUTH.equals(grantType);
282
    }
283
}
284
```