0
# Keycloak Common Library
1

2
The Keycloak Common Library provides foundational utilities, constants, and shared functionality for the Keycloak identity and access management system. This library serves as the core foundation used across Keycloak server and all client adapters, providing cryptographic utilities, profile management, networking tools, and extensive utility functions.
3

4
## Package Information
5

6
- **Package Name**: keycloak-common
7
- **Package Type**: maven
8
- **Group ID**: org.keycloak
9
- **Artifact ID**: keycloak-common
10
- **Language**: Java
11
- **Version**: 26.2.5
12
- **License**: Apache-2.0
13
- **Minimum Java Version**: Java 8+
14

15
## Core Imports
16

17
Maven dependency:
18

19
```xml
20
<dependency>
21
    <groupId>org.keycloak</groupId>
22
    <artifactId>keycloak-common</artifactId>
23
    <version>26.2.5</version>
24
</dependency>
25
```
26

27
Common Java imports:
28

29
```java
30
// Core functionality
31
import org.keycloak.common.Profile;
32
import org.keycloak.common.Version;
33
import org.keycloak.common.ClientConnection;
34
import org.keycloak.common.VerificationException;
35

36
// Constants
37
import org.keycloak.common.constants.GenericConstants;
38
import org.keycloak.common.constants.KerberosConstants;
39
import org.keycloak.common.constants.ServiceAccountConstants;
40

41
// Cryptographic utilities
42
import org.keycloak.common.crypto.CryptoIntegration;
43
import org.keycloak.common.crypto.CryptoProvider;
44
import org.keycloak.common.crypto.FipsMode;
45

46
// Enums
47
import org.keycloak.common.enums.SslRequired;
48
import org.keycloak.common.enums.HostnameVerificationPolicy;
49

50
// Profile management
51
import org.keycloak.common.profile.ProfileConfigResolver;
52
import org.keycloak.common.profile.PropertiesProfileConfigResolver;
53

54
// Utilities
55
import org.keycloak.common.util.Base64;
56
import org.keycloak.common.util.MultivaluedMap;
57
import org.keycloak.common.util.KeycloakUriBuilder;
58

59
// Reflection utilities
60
import org.keycloak.common.util.reflections.Reflections;
61
import org.keycloak.common.util.reflections.Types;
62
```
63

64
## Basic Usage
65

66
### Feature Profile Management
67

68
```java
69
import org.keycloak.common.Profile;
70
import org.keycloak.common.Profile.Feature;
71

72
// Configure and check features
73
Profile profile = Profile.defaults();
74
boolean authzEnabled = Profile.isFeatureEnabled(Feature.AUTHORIZATION);
75

76
// Get all enabled features
77
Set<Feature> allFeatures = profile.getAllFeatures();
78
Set<Feature> previewFeatures = profile.getPreviewFeatures();
79
```
80

81
### Version Information
82

83
```java
84
import org.keycloak.common.Version;
85

86
// Get version information
87
String version = Version.VERSION;
88
String buildTime = Version.BUILD_TIME;
89
String name = Version.NAME; // "Keycloak"
90
```
91

92
### Cryptographic Operations
93

94
```java
95
import org.keycloak.common.crypto.CryptoIntegration;
96
import org.keycloak.common.crypto.CryptoProvider;
97
import org.keycloak.common.crypto.FipsMode;
98

99
// Initialize crypto provider
100
CryptoIntegration.init(ClassLoader.getSystemClassLoader());
101
CryptoProvider provider = CryptoIntegration.getProvider();
102

103
// Check FIPS mode
104
FipsMode fipsMode = FipsMode.DISABLED;
105
boolean isFipsEnabled = fipsMode.isFipsEnabled();
106
```
107

108
## Architecture
109

110
The Keycloak Common Library is organized into seven main packages:
111

112
- **org.keycloak.common**: Core classes including Profile, Version, ClientConnection
113
- **org.keycloak.common.constants**: Configuration constants and protocol definitions
114
- **org.keycloak.common.crypto**: Cryptographic providers and utilities
115
- **org.keycloak.common.enums**: Configuration enums and policy types
116
- **org.keycloak.common.profile**: Feature flag and profile management
117
- **org.keycloak.common.util**: Extensive utility classes for common operations
118
- **org.keycloak.common.util.reflections**: Advanced reflection utilities
119

120
## Capabilities
121

122
### Core Functionality
123

124
Core classes for profile management, version information, client connections, and verification.
125

126
```java { .api }
127
// Feature profile management
128
public class Profile {
129
    public static Profile getInstance();
130
    public static boolean isFeatureEnabled(Feature feature);
131
    public Set<Feature> getAllFeatures();
132
    public ProfileName getName();
133
}
134

135
// Version information
136
public class Version {
137
    public static final String VERSION;
138
    public static final String BUILD_TIME;
139
    public static final String NAME;
140
}
141

142
// Client connection information
143
public interface ClientConnection {
144
    String getRemoteAddr();
145
    String getRemoteHost();
146
    int getRemotePort();
147
    String getLocalAddr();
148
    int getLocalPort();
149
}
150
```
151

152
[Core Functionality](./core-functionality.md)
153

154
### Constants and Configuration
155

156
Comprehensive set of constants for Kerberos, service accounts, and generic configuration.
157

158
```java { .api }
159
// Generic constants
160
public class GenericConstants {
161
    public static final String PROTOCOL_CLASSPATH = "classpath:";
162
}
163

164
// Kerberos constants
165
public class KerberosConstants {
166
    public static final String NEGOTIATE = "Negotiate";
167
    public static final Oid SPNEGO_OID;
168
    public static final String KERBEROS_REALM = "kerberosRealm";
169
}
170

171
// Service account constants
172
public interface ServiceAccountConstants {
173
    String CLIENT_AUTH = "client_auth";
174
    String SERVICE_ACCOUNT_USER_PREFIX = "service-account-";
175
}
176
```
177

178
[Constants and Configuration](./constants-configuration.md)
179

180
### Cryptographic Utilities
181

182
Complete cryptographic abstraction layer supporting both FIPS and non-FIPS modes.
183

184
```java { .api }
185
// Crypto integration
186
public class CryptoIntegration {
187
    public static void init(ClassLoader classLoader);
188
    public static CryptoProvider getProvider();
189
    public static void setProvider(CryptoProvider provider);
190
}
191

192
// Crypto provider interface
193
public interface CryptoProvider {
194
    Provider getBouncyCastleProvider();
195
    <T> T getAlgorithmProvider(Class<T> clazz, String algorithm);
196
    CertificateUtilsProvider getCertificateUtils();
197
    KeyPairGenerator getKeyPairGen(String algorithm);
198
}
199

200
// FIPS mode configuration
201
public enum FipsMode {
202
    NON_STRICT, STRICT, DISABLED;
203
    boolean isFipsEnabled();
204
}
205
```
206

207
[Cryptographic Utilities](./crypto-utilities.md)
208

209
### Enums and Types
210

211
Configuration enums for SSL requirements, hostname verification, and API versioning.
212

213
```java { .api }
214
// SSL requirement levels
215
public enum SslRequired {
216
    ALL, EXTERNAL, NONE;
217
    boolean isRequired(ClientConnection connection);
218
    boolean isRequired(String host);
219
}
220

221
// Hostname verification policies
222
public enum HostnameVerificationPolicy {
223
    ANY, WILDCARD, STRICT, DEFAULT;
224
}
225

226
// Account API versions
227
public enum AccountRestApiVersion {
228
    V1_ALPHA1("v1alpha1");
229
    String getStrVersion();
230
}
231
```
232

233
[Enums and Types](./enums-types.md)
234

235
### Profile Management
236

237
Advanced feature flag management with resolvers and configuration options.
238

239
```java { .api }
240
// Profile configuration resolver
241
public interface ProfileConfigResolver {
242
    Profile.ProfileName getProfileName();
243
    FeatureConfig getFeatureConfig(String feature);
244
}
245

246
// Properties-based resolver
247
public class PropertiesProfileConfigResolver implements ProfileConfigResolver {
248
    public PropertiesProfileConfigResolver(Properties properties);
249
    public static String getPropertyKey(Feature feature);
250
}
251

252
// Comma-separated list resolver
253
public class CommaSeparatedListProfileConfigResolver implements ProfileConfigResolver {
254
    public CommaSeparatedListProfileConfigResolver(String enabledFeatures, String disabledFeatures);
255
}
256
```
257

258
[Profile Management](./profile-management.md)
259

260
### Utility Functions
261

262
Extensive collection of utility classes for encoding, networking, I/O, and data manipulation.
263

264
```java { .api }
265
// Base64 encoding utilities
266
public class Base64 {
267
    public static String encodeBytes(byte[] source);
268
    public static String encodeObject(Serializable serializableObject);
269
    public static void encode(ByteBuffer raw, ByteBuffer encoded);
270
}
271

272
// Multivalued map interface
273
public interface MultivaluedMap<K, V> extends Map<K, List<V>> {
274
    void putSingle(K key, V value);
275
    void add(K key, V value);
276
    V getFirst(K key);
277
    List<V> getList(K key);
278
}
279

280
// URI builder for Keycloak
281
public class KeycloakUriBuilder {
282
    public static KeycloakUriBuilder fromUri(String uriTemplate);
283
    public KeycloakUriBuilder path(String segment);
284
    public URI build(Object... values);
285
}
286
```
287

288
[Utility Functions](./utility-functions.md)
289

290
### Reflection Utilities
291

292
Advanced reflection capabilities for type resolution, method invocation, and annotation handling.
293

294
```java { .api }
295
// Comprehensive reflection utilities
296
public class Reflections {
297
    public static <T> T cast(Object obj);
298
    public static Set<Field> getAllDeclaredFields(Class<?> clazz);
299
    public static Method findDeclaredMethod(Class<?> clazz, String name, Class<?>... args);
300
    public static Object invokeMethod(Method method, Object instance, Object... args);
301
    public static <T> Class<T> getRawType(Type type);
302
}
303

304
// Type resolution utilities
305
public class Types {
306
    public static Type boxedType(Type type);
307
    public static Class<?> getRawType(Type type);
308
    public static Type resolveTypeVariables(Class<?> root, Type type);
309
    public static Class getCollectionBaseType(Class type, Type genericType);
310
}
311
```
312

313
[Reflection Utilities](./reflection-utilities.md)
314

315
## Exception Types
316

317
```java { .api }
318
// Verification exception for crypto operations
319
public class VerificationException extends Exception {
320
    public VerificationException();
321
    public VerificationException(String message);
322
    public VerificationException(String message, Throwable cause);
323
    public VerificationException(Throwable cause);
324
}
325

326
// Profile-related exceptions
327
public class ProfileException extends RuntimeException {
328
    public ProfileException(String message);
329
    public ProfileException(String message, Throwable cause);
330
}
331

332
// PEM utility exceptions
333
public class PemException extends Exception {
334
    public PemException();
335
    public PemException(String message);
336
    public PemException(String message, Throwable cause);
337
    public PemException(Throwable cause);
338
}
339
```