0
# Core Functionality
1

2
This document covers the core functionality classes in the `org.keycloak.common` package that provide essential capabilities for profile management, version information, client connections, and verification operations.
3

4
## Profile Management
5

6
The `Profile` class manages Keycloak feature profiles and feature flags, allowing runtime configuration of capabilities.
7

8
### Profile Class
9

10
```java { .api }
11
public class Profile {
12
    // Static methods for profile configuration
13
    public static Profile defaults();
14
    public static Profile configure(ProfileConfigResolver... resolvers);
15
    public static Profile init(ProfileName profileName, Map<Feature, Boolean> features);
16
    public static Profile getInstance();
17
    public static void reset();
18
    
19
    // Feature query methods
20
    public static boolean isFeatureEnabled(Feature feature);
21
    public static Set<String> getAllUnversionedFeatureNames();
22
    public static Set<String> getDisableableUnversionedFeatureNames();
23
    public static Set<Feature> getFeatureVersions(String feature);
24
    
25
    // Instance methods
26
    public ProfileName getName();
27
    public Set<Feature> getAllFeatures();
28
    public Set<Feature> getDisabledFeatures();
29
    public Set<Feature> getPreviewFeatures();
30
    public Set<Feature> getExperimentalFeatures();
31
    public Set<Feature> getDeprecatedFeatures();
32
    public Set<Feature> getFeatures(Feature.Type type);
33
    public Map<Feature, Boolean> getFeatures();
34
}
35
```
36

37
### ProfileName Enum
38

39
```java { .api }
40
public enum ProfileName {
41
    DEFAULT,
42
    PREVIEW
43
}
44
```
45

46
### Feature Enum
47

48
```java { .api }
49
public enum Feature {
50
    // Identity and Access Management Features
51
    AUTHORIZATION("authorization"),
52
    ACCOUNT_API("account-api"),
53
    ADMIN_FINE_GRAINED_AUTHZ("admin-fine-grained-authz"),
54
    
55
    // Protocol and Authentication Features  
56
    DOCKER("docker"),
57
    SCRIPTS("scripts"),
58
    TOKEN_EXCHANGE("token-exchange"),
59
    WEB_AUTHN("web-authn"),
60
    CLIENT_POLICIES("client-policies"),
61
    CIBA("ciba"),
62
    PAR("par"),
63
    DYNAMIC_SCOPES("dynamic-scopes"),
64
    STEP_UP_AUTHENTICATION("step-up-authentication"),
65
    KERBEROS("kerberos"),
66
    RECOVERY_CODES("recovery-codes"),
67
    PASSKEYS("passkeys"),
68
    
69
    // Security and Compliance Features
70
    FIPS("fips"),
71
    DPOP("dpop"),
72
    
73
    // Device and Client Features
74
    DEVICE_FLOW("device-flow"),
75
    CLIENT_TYPES("client-types"),
76
    
77
    // User and Session Management
78
    TRANSIENT_USERS("transient-users"),
79
    PERSISTENT_USER_SESSIONS("persistent-user-sessions"),
80
    
81
    // Infrastructure Features
82
    MULTI_SITE("multi-site"),
83
    CLUSTERLESS("clusterless"),
84
    HOSTNAME_V2("hostname-v2"),
85
    
86
    // Standards and Protocols
87
    OID4VC_VCI("oid4vc-vci"),
88
    
89
    // Monitoring and Observability
90
    OPENTELEMETRY("opentelemetry"),
91
    USER_EVENT_METRICS("user-event-metrics"),
92
    
93
    // User Interface
94
    DECLARATIVE_UI("declarative-ui"),
95
    
96
    // Organization Management
97
    ORGANIZATION("organization"),
98
    
99
    // Caching and Performance
100
    CACHE_EMBEDDED_REMOTE_STORE("cache-embedded-remote-store"),
101
    
102
    // Federation and Integration
103
    IPA_TUURA_FEDERATION("ipa-tuura-federation"),
104
    
105
    // Deployment and Updates
106
    ROLLING_UPDATES_V1("rolling-updates-v1");
107
    
108
    // Feature methods
109
    public String getKey();
110
    public String getUnversionedKey();
111
    public String getVersionedKey();
112
    public String getLabel();
113
    public Type getType();
114
    public Set<Feature> getDependencies();
115
    public int getVersion();
116
    public boolean isAvailable();
117
}
118
```
119

120
### Feature.Type Enum
121

122
```java { .api }
123
public enum Type {
124
    DEFAULT,
125
    DISABLED_BY_DEFAULT,
126
    DEPRECATED,
127
    PREVIEW,
128
    PREVIEW_DISABLED_BY_DEFAULT,
129
    EXPERIMENTAL
130
}
131
```
132

133
### Usage Examples
134

135
```java
136
// Basic feature checking
137
if (Profile.isFeatureEnabled(Feature.AUTHORIZATION)) {
138
    // Authorization feature is enabled
139
}
140

141
// Configure profile with specific features
142
Map<Feature, Boolean> features = new HashMap<>();
143
features.put(Feature.SCRIPTS, false);
144
features.put(Feature.DOCKER, true);
145
Profile profile = Profile.init(ProfileName.DEFAULT, features);
146

147
// Get feature information
148
Set<Feature> previewFeatures = profile.getPreviewFeatures();
149
Set<Feature> experimentalFeatures = profile.getExperimentalFeatures();
150

151
// Check feature metadata
152
Feature authzFeature = Feature.AUTHORIZATION;
153
String key = authzFeature.getKey();
154
Feature.Type type = authzFeature.getType();
155
Set<Feature> dependencies = authzFeature.getDependencies();
156
```
157

158
## Version Information
159

160
The `Version` class provides static access to Keycloak version information.
161

162
```java { .api }
163
public class Version {
164
    // Version constants
165
    public static final String UNKNOWN;
166
    public static final String NAME; // "Keycloak"
167
    public static final String NAME_HTML;
168
    public static final String VERSION;
169
    public static final String RESOURCES_VERSION;
170
    public static final String BUILD_TIME;
171
}
172
```
173

174
### Usage Examples
175

176
```java
177
// Get version information
178
String keycloakVersion = Version.VERSION;
179
String buildTime = Version.BUILD_TIME;
180
String productName = Version.NAME;
181

182
// Use in logging or diagnostics
183
logger.info("Running {} version {} (built {})", 
184
    Version.NAME, Version.VERSION, Version.BUILD_TIME);
185
```
186

187
## Client Connection Interface
188

189
The `ClientConnection` interface provides information about client network connections.
190

191
```java { .api }
192
public interface ClientConnection {
193
    /**
194
     * Returns the IP address as a string if available, otherwise null
195
     */
196
    String getRemoteAddr();
197
    
198
    /**
199
     * Returns the remote host (IP address or proxy header info)  
200
     */
201
    String getRemoteHost();
202
    
203
    /**
204
     * Returns the remote port
205
     */
206
    int getRemotePort();
207
    
208
    /**
209
     * Returns the local address
210
     */
211
    String getLocalAddr();
212
    
213
    /**
214
     * Returns the local port
215
     */
216
    int getLocalPort();
217
}
218
```
219

220
### Usage Examples
221

222
```java
223
public void logClientConnection(ClientConnection connection) {
224
    String remoteAddr = connection.getRemoteAddr();
225
    String remoteHost = connection.getRemoteHost();
226
    int remotePort = connection.getRemotePort();
227
    
228
    logger.info("Client connection from {}:{} ({})", 
229
        remoteHost, remotePort, remoteAddr);
230
}
231

232
public boolean isLocalConnection(ClientConnection connection) {
233
    String remoteAddr = connection.getRemoteAddr();
234
    return "127.0.0.1".equals(remoteAddr) || "::1".equals(remoteAddr);
235
}
236
```
237

238
## Verification Exception
239

240
The `VerificationException` is thrown during verification operations, particularly in cryptographic contexts.
241

242
```java { .api }
243
public class VerificationException extends Exception {
244
    /**
245
     * Default constructor
246
     */
247
    public VerificationException();
248
    
249
    /**
250
     * Constructor with message
251
     */
252
    public VerificationException(String message);
253
    
254
    /**
255
     * Constructor with message and cause
256
     */
257
    public VerificationException(String message, Throwable cause);
258
    
259
    /**
260
     * Constructor with cause
261
     */
262
    public VerificationException(Throwable cause);
263
}
264
```
265

266
### Usage Examples
267

268
```java
269
public void verifySignature(byte[] signature, byte[] data) throws VerificationException {
270
    try {
271
        // Perform signature verification
272
        if (!isValidSignature(signature, data)) {
273
            throw new VerificationException("Signature verification failed");
274
        }
275
    } catch (Exception e) {
276
        throw new VerificationException("Error during verification", e);
277
    }
278
}
279

280
public void handleVerification() {
281
    try {
282
        verifySignature(signature, data);
283
    } catch (VerificationException e) {
284
        logger.error("Verification failed: {}", e.getMessage());
285
        // Handle verification failure
286
    }
287
}
288
```
289

290
## Error Handling Patterns
291

292
```java
293
// Profile configuration errors
294
try {
295
    Profile profile = Profile.configure(resolver);
296
} catch (ProfileException e) {
297
    logger.error("Profile configuration failed: {}", e.getMessage());
298
    // Handle configuration failure - use defaults or fail gracefully
299
}
300

301
// Feature availability checking with error handling
302
try {
303
    if (Feature.AUTHORIZATION.isAvailable() && Profile.isFeatureEnabled(Feature.AUTHORIZATION)) {
304
        // Use authorization features
305
    } else {
306
        logger.warn("Authorization feature not available or not enabled");
307
    }
308
} catch (Exception e) {
309
    logger.error("Error checking feature availability", e);
310
}
311

312
// Safe version access with null checking
313
String version = Version.VERSION != null ? Version.VERSION : Version.UNKNOWN;
314

315
// Verification exception handling
316
public void processSecureOperation() throws VerificationException {
317
    try {
318
        // Perform verification logic
319
        verifySignature(data, signature);
320
    } catch (GeneralSecurityException e) {
321
        throw new VerificationException("Cryptographic verification failed", e);
322
    } catch (Exception e) {
323
        throw new VerificationException("Unexpected error during verification", e);
324
    }
325
}
326
```