0
# Enums and Types
1

2
This document covers the enumerations and type definitions in the `org.keycloak.common.enums` package that provide configuration options and policy definitions for various Keycloak components.
3

4
## SSL Requirements
5

6
The `SslRequired` enum defines SSL requirement levels for different connection types.
7

8
```java { .api }
9
public enum SslRequired {
10
    /**
11
     * SSL required for all connections
12
     */
13
    ALL,
14
    
15
    /**
16
     * SSL required for external connections only (internal/localhost connections exempt)
17
     */
18
    EXTERNAL,
19
    
20
    /**
21
     * SSL not required for any connections
22
     */
23
    NONE;
24
    
25
    /**
26
     * Checks if SSL is required for the given client connection
27
     */
28
    public boolean isRequired(ClientConnection connection);
29
    
30
    /**
31
     * Checks if SSL is required for the given host
32
     */
33
    public boolean isRequired(String host);
34
}
35
```
36

37
### Usage Examples
38

39
```java
40
// Configure SSL requirement
41
SslRequired sslPolicy = SslRequired.EXTERNAL;
42

43
// Check if SSL required for a connection
44
ClientConnection connection = getClientConnection();
45
if (sslPolicy.isRequired(connection)) {
46
    // Enforce SSL for this connection
47
    redirectToHttps(request);
48
}
49

50
// Check if SSL required for a host
51
String requestHost = request.getServerName();
52
if (sslPolicy.isRequired(requestHost)) {
53
    // SSL required for this host
54
}
55

56
// Different SSL policies
57
switch (sslPolicy) {
58
    case ALL:
59
        // All connections must use SSL
60
        break;
61
    case EXTERNAL:
62
        // Only external connections require SSL
63
        break;
64
    case NONE:
65
        // SSL not required
66
        break;
67
}
68
```
69

70
## Hostname Verification Policies
71

72
The `HostnameVerificationPolicy` enum defines hostname verification behavior for SSL connections.
73

74
```java { .api }
75
public enum HostnameVerificationPolicy {
76
    /**
77
     * No hostname verification performed
78
     */
79
    ANY,
80
    
81
    /**
82
     * @deprecated Allows wildcards in subdomain names
83
     */
84
    @Deprecated
85
    WILDCARD,
86
    
87
    /**
88
     * @deprecated CN must match hostname exactly
89
     */
90
    @Deprecated  
91
    STRICT,
92
    
93
    /**
94
     * Similar to STRICT with better public suffix matching
95
     */
96
    DEFAULT
97
}
98
```
99

100
### Usage Examples
101

102
```java
103
// Configure hostname verification
104
HostnameVerificationPolicy policy = HostnameVerificationPolicy.DEFAULT;
105

106
// Apply hostname verification policy
107
switch (policy) {
108
    case ANY:
109
        // Skip hostname verification (not recommended for production)
110
        sslContext.setHostnameVerifier((hostname, session) -> true);
111
        break;
112
        
113
    case DEFAULT:
114
        // Use default hostname verification with proper public suffix handling
115
        sslContext.setHostnameVerifier(getDefaultHostnameVerifier());
116
        break;
117
        
118
    case WILDCARD:
119
        // Legacy wildcard support (deprecated)
120
        logger.warn("WILDCARD hostname verification is deprecated");
121
        break;
122
        
123
    case STRICT:
124
        // Legacy strict verification (deprecated)  
125
        logger.warn("STRICT hostname verification is deprecated, use DEFAULT");
126
        break;
127
}
128
```
129

130
## Relative URL Usage
131

132
The `RelativeUrlsUsed` enum defines policies for relative URL usage in Keycloak configurations.
133

134
```java { .api }
135
public enum RelativeUrlsUsed {
136
    /**
137
     * Always use relative URI and resolve based on browser request
138
     */
139
    ALWAYS,
140
    
141
    /**
142
     * Relative URI not used, configuration contains absolute URI
143
     */
144
    NEVER
145
}
146
```
147

148
### Usage Examples
149

150
```java
151
// Configure relative URL policy
152
RelativeUrlsUsed urlPolicy = RelativeUrlsUsed.ALWAYS;
153

154
// Generate URLs based on policy
155
String baseUrl;
156
switch (urlPolicy) {
157
    case ALWAYS:
158
        // Use relative URLs, resolve from request
159
        baseUrl = buildRelativeUrl(request);
160
        break;
161
        
162
    case NEVER:
163
        // Use absolute URLs from configuration
164
        baseUrl = getConfiguredBaseUrl();
165
        break;
166
}
167

168
// Build endpoint URLs
169
String loginUrl = baseUrl + "/auth/realms/master/protocol/openid-connect/auth";
170
String tokenUrl = baseUrl + "/auth/realms/master/protocol/openid-connect/token";
171
```
172

173
## Account REST API Versions
174

175
The `AccountRestApiVersion` enum defines supported versions of the Account REST API.
176

177
```java { .api }
178
public enum AccountRestApiVersion {
179
    /**
180
     * Version 1 Alpha 1 of the Account REST API
181
     */
182
    V1_ALPHA1("v1alpha1");
183
    
184
    /**
185
     * Default API version
186
     */
187
    public static final AccountRestApiVersion DEFAULT = V1_ALPHA1;
188
    
189
    /**
190
     * Gets enum value by string version
191
     */
192
    public static AccountRestApiVersion get(String strVersion);
193
    
194
    /**
195
     * Gets the string representation of the version
196
     */
197
    public String getStrVersion();
198
}
199
```
200

201
### Usage Examples
202

203
```java
204
// Get default API version
205
AccountRestApiVersion defaultVersion = AccountRestApiVersion.DEFAULT;
206
String versionString = defaultVersion.getStrVersion(); // "v1alpha1"
207

208
// Parse version from string
209
String requestedVersion = request.getHeader("API-Version");
210
AccountRestApiVersion version = AccountRestApiVersion.get(requestedVersion);
211

212
if (version == null) {
213
    // Unsupported version, use default
214
    version = AccountRestApiVersion.DEFAULT;
215
}
216

217
// Build API endpoint with version
218
String apiPath = "/auth/realms/" + realmName + "/account/" + version.getStrVersion();
219

220
// Version-specific handling
221
switch (version) {
222
    case V1_ALPHA1:
223
        // Handle V1 Alpha 1 API features
224
        processV1Alpha1Request(request, response);
225
        break;
226
        
227
    default:
228
        // Handle with default version
229
        processDefaultRequest(request, response);
230
        break;
231
}
232
```
233

234
## Type Utilities and Patterns
235

236
### SSL Policy Configuration Pattern
237

238
```java
239
public class SslConfiguration {
240
    private final SslRequired sslRequired;
241
    private final HostnameVerificationPolicy hostnamePolicy;
242
    
243
    public SslConfiguration(SslRequired sslRequired, HostnameVerificationPolicy hostnamePolicy) {
244
        this.sslRequired = sslRequired;
245
        this.hostnamePolicy = hostnamePolicy;
246
    }
247
    
248
    public boolean requiresSSL(ClientConnection connection) {
249
        return sslRequired.isRequired(connection);
250
    }
251
    
252
    public boolean requiresSSL(String host) {
253
        return sslRequired.isRequired(host);
254
    }
255
    
256
    public HostnameVerifier createHostnameVerifier() {
257
        switch (hostnamePolicy) {
258
            case ANY:
259
                return (hostname, session) -> true;
260
            case DEFAULT:
261
                return createDefaultVerifier();
262
            default:
263
                logger.warn("Using deprecated hostname verification policy: {}", hostnamePolicy);
264
                return createLegacyVerifier(hostnamePolicy);
265
        }
266
    }
267
}
268
```
269

270
### URL Policy Utilities
271

272
```java
273
public class UrlBuilder {
274
    private final RelativeUrlsUsed urlPolicy;
275
    private final String configuredBaseUrl;
276
    
277
    public UrlBuilder(RelativeUrlsUsed urlPolicy, String configuredBaseUrl) {
278
        this.urlPolicy = urlPolicy;
279
        this.configuredBaseUrl = configuredBaseUrl;
280
    }
281
    
282
    public String buildBaseUrl(HttpServletRequest request) {
283
        switch (urlPolicy) {
284
            case ALWAYS:
285
                return buildFromRequest(request);
286
            case NEVER:
287
                return configuredBaseUrl;
288
            default:
289
                throw new IllegalStateException("Unknown URL policy: " + urlPolicy);
290
        }
291
    }
292
    
293
    private String buildFromRequest(HttpServletRequest request) {
294
        String scheme = request.getScheme();
295
        String host = request.getServerName();
296
        int port = request.getServerPort();
297
        
298
        StringBuilder url = new StringBuilder();
299
        url.append(scheme).append("://").append(host);
300
        
301
        if (!isDefaultPort(scheme, port)) {
302
            url.append(":").append(port);
303
        }
304
        
305
        return url.toString();
306
    }
307
    
308
    private boolean isDefaultPort(String scheme, int port) {
309
        return ("http".equals(scheme) && port == 80) || 
310
               ("https".equals(scheme) && port == 443);
311
    }
312
}
313
```
314

315
### API Version Management
316

317
```java
318
public class ApiVersionManager {
319
    
320
    public static boolean isSupported(String versionString) {
321
        return AccountRestApiVersion.get(versionString) != null;
322
    }
323
    
324
    public static AccountRestApiVersion parseVersion(HttpServletRequest request) {
325
        // Try header first
326
        String versionHeader = request.getHeader("API-Version");
327
        if (versionHeader != null) {
328
            AccountRestApiVersion version = AccountRestApiVersion.get(versionHeader);
329
            if (version != null) {
330
                return version;
331
            }
332
        }
333
        
334
        // Try path parameter
335
        String versionParam = request.getParameter("version");
336
        if (versionParam != null) {
337
            AccountRestApiVersion version = AccountRestApiVersion.get(versionParam);
338
            if (version != null) {
339
                return version;
340
            }
341
        }
342
        
343
        // Return default
344
        return AccountRestApiVersion.DEFAULT;
345
    }
346
    
347
    public static void setVersionHeader(HttpServletResponse response, AccountRestApiVersion version) {
348
        response.setHeader("API-Version", version.getStrVersion());
349
    }
350
}
351
```
352

353
### Security Policy Validator
354

355
```java
356
public class SecurityPolicyValidator {
357
    
358
    public static void validateSslPolicy(SslRequired sslPolicy, HttpServletRequest request) 
359
            throws SecurityException {
360
        
361
        if (sslPolicy == SslRequired.NONE) {
362
            return; // No SSL required
363
        }
364
        
365
        if (!request.isSecure()) {
366
            String host = request.getServerName();
367
            
368
            if (sslPolicy == SslRequired.ALL) {
369
                throw new SecurityException("SSL required for all connections");
370
            }
371
            
372
            if (sslPolicy == SslRequired.EXTERNAL && !isLocalhost(host)) {
373
                throw new SecurityException("SSL required for external connections");
374
            }
375
        }
376
    }
377
    
378
    private static boolean isLocalhost(String host) {
379
        return "localhost".equals(host) || 
380
               "127.0.0.1".equals(host) || 
381
               "::1".equals(host);
382
    }
383
    
384
    public static void validateHostnamePolicy(HostnameVerificationPolicy policy) {
385
        if (policy == HostnameVerificationPolicy.WILDCARD || 
386
            policy == HostnameVerificationPolicy.STRICT) {
387
            
388
            logger.warn("Hostname verification policy {} is deprecated, " +
389
                       "consider using DEFAULT", policy);
390
        }
391
    }
392
}
393
```
394

395
## Integration Examples
396

397
### Complete Security Configuration
398

399
```java
400
public class SecurityConfig {
401
    private final SslRequired sslRequired;
402
    private final HostnameVerificationPolicy hostnamePolicy;
403
    private final RelativeUrlsUsed urlPolicy;
404
    
405
    public SecurityConfig(Properties config) {
406
        this.sslRequired = SslRequired.valueOf(
407
            config.getProperty("ssl.required", "EXTERNAL")
408
        );
409
        this.hostnamePolicy = HostnameVerificationPolicy.valueOf(
410
            config.getProperty("hostname.verification", "DEFAULT")
411
        );
412
        this.urlPolicy = RelativeUrlsUsed.valueOf(
413
            config.getProperty("relative.urls", "ALWAYS")
414
        );
415
    }
416
    
417
    public void validateRequest(HttpServletRequest request) throws SecurityException {
418
        SecurityPolicyValidator.validateSslPolicy(sslRequired, request);
419
        SecurityPolicyValidator.validateHostnamePolicy(hostnamePolicy);
420
    }
421
    
422
    public String buildUrl(HttpServletRequest request, String path) {
423
        UrlBuilder builder = new UrlBuilder(urlPolicy, getConfiguredBaseUrl());
424
        String baseUrl = builder.buildBaseUrl(request);
425
        return baseUrl + path;
426
    }
427
}
428
```