0
# Keycloak Core
1

2
Keycloak Core is the fundamental library for authentication and authorization in the Keycloak identity and access management ecosystem. It provides comprehensive JWT token handling, cryptographic operations, OAuth2/OpenID Connect protocol support, and extensive data representation classes for identity management operations.
3

4
## Package Information
5

6
- **Package Name**: keycloak-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.keycloak</groupId>
13
    <artifactId>keycloak-core</artifactId>
14
    <version>26.2.5</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.keycloak.Config;
22
import org.keycloak.TokenVerifier;
23
import org.keycloak.KeycloakSecurityContext;
24
import org.keycloak.AuthorizationContext;
25
import org.keycloak.representations.AccessToken;
26
import org.keycloak.representations.IDToken;
27
import org.keycloak.representations.JsonWebToken;
28
import org.keycloak.crypto.KeyWrapper;
29
import org.keycloak.crypto.Algorithm;
30
import org.keycloak.jose.jwk.JSONWebKeySet;
31
import org.keycloak.util.TokenUtil;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.keycloak.TokenVerifier;
38
import org.keycloak.representations.AccessToken;
39
import org.keycloak.crypto.KeyWrapper;
40
import org.keycloak.exceptions.TokenVerificationException;
41

42
// Basic token verification
43
try {
44
    AccessToken token = TokenVerifier.create(tokenString, AccessToken.class)
45
        .withDefaultChecks()
46
        .publicKey(publicKey)
47
        .verify()
48
        .getToken();
49
    
50
    String subject = token.getSubject();
51
    String issuer = token.getIssuer();
52
    boolean isActive = token.isActive();
53
    
54
    // Access roles and permissions
55
    AccessToken.Access realmAccess = token.getRealmAccess();
56
    if (realmAccess != null && realmAccess.isUserInRole("admin")) {
57
        // Handle admin access
58
    }
59
} catch (TokenVerificationException e) {
60
    // Handle verification failure
61
}
62

63
// Configuration management
64
Config.Scope authScope = Config.scope("authentication");
65
String defaultProvider = authScope.get("defaultProvider", "password");
66
```
67

68
## Architecture
69

70
Keycloak Core is built around several key architectural components:
71

72
- **Token System**: Comprehensive JWT implementation with specialized token types for different OAuth2/OIDC flows
73
- **Cryptographic Layer**: Pluggable signature and encryption providers supporting RSA, ECDSA, EdDSA, and HMAC algorithms
74
- **JOSE Implementation**: Complete JSON Object Signing and Encryption support including JWS, JWE, and JWK specifications
75
- **Representation Layer**: Extensive data transfer objects for identity management, authorization policies, and configuration
76
- **Configuration System**: Hierarchical configuration management with scoped property access
77
- **Verification Framework**: Flexible token validation system with pluggable verification predicates
78

79
## Capabilities
80

81
### Token Management
82

83
Core JWT token creation, validation, and processing with support for access tokens, ID tokens, refresh tokens, and specialized Keycloak token types.
84

85
```java { .api }
86
public class TokenVerifier<T extends JsonWebToken> {
87
    public static <T extends JsonWebToken> TokenVerifier<T> create(String tokenString, Class<T> clazz);
88
    public TokenVerifier<T> withDefaultChecks();
89
    public TokenVerifier<T> publicKey(PublicKey publicKey);
90
    public TokenVerifier<T> secretKey(SecretKey secretKey);
91
    public TokenVerifier<T> audience(String... audience);
92
    public T verify() throws TokenVerificationException;
93
}
94
```
95

96
[Token Management](./token-management.md)
97

98
### Cryptographic Operations
99

100
Comprehensive cryptographic support for signing, verification, key management, and algorithm abstraction with support for modern cryptographic standards.
101

102
```java { .api }
103
public interface SignatureSignerContext {
104
    byte[] sign(byte[] data) throws SignatureException;
105
    String getAlgorithm();
106
    String getKid();
107
}
108

109
public interface SignatureVerifierContext {
110
    boolean verify(byte[] data, byte[] signature) throws SignatureException;
111
    String getAlgorithm();
112
    String getKid();
113
}
114

115
public class KeyWrapper {
116
    public String getKid();
117
    public String getAlgorithm();
118
    public KeyType getType();
119
    public KeyUse getUse();
120
    public KeyStatus getStatus();
121
    public PublicKey getPublicKey();
122
    public SecretKey getSecretKey();
123
}
124
```
125

126
[Cryptographic Operations](./cryptographic-operations.md)
127

128
### JOSE Implementation
129

130
Complete JSON Object Signing and Encryption implementation including JWS (JSON Web Signature), JWE (JSON Web Encryption), and JWK (JSON Web Key) support.
131

132
```java { .api }
133
public class JWSInput {
134
    public JWSHeader getHeader();
135
    public byte[] getContent();
136
    public <T> T readJsonContent(Class<T> type) throws IOException;
137
    public String getEncodedSignatureInput();
138
    public byte[] getSignature();
139
}
140

141
public class JSONWebKeySet {
142
    public List<JWK> getKeys();
143
    public JWK getKeyByKid(String kid);
144
}
145
```
146

147
[JOSE Implementation](./jose-implementation.md)
148

149
### Token Representations
150

151
Comprehensive token representation classes for OAuth2/OpenID Connect tokens with Keycloak extensions for roles, permissions, and authorization.
152

153
```java { .api }
154
public class AccessToken extends JsonWebToken {
155
    public String getScope();
156
    public String getSessionState();
157
    public Access getRealmAccess();
158
    public Map<String, Access> getResourceAccess();
159
    public Authorization getAuthorization();
160
    
161
    public static class Access {
162
        public Set<String> getRoles();
163
        public boolean isUserInRole(String role);
164
    }
165
}
166

167
public class IDToken extends JsonWebToken {
168
    public String getName();
169
    public String getGivenName();
170
    public String getFamilyName();
171
    public String getPreferredUsername();
172
    public String getEmail();
173
    public Boolean getEmailVerified();
174
    public AddressClaimSet getAddress();
175
}
176
```
177

178
[Token Representations](./token-representations.md)
179

180
### Identity Management Representations
181

182
Extensive data transfer objects for user management, realm configuration, client settings, roles, groups, and authorization policies.
183

184
```java { .api }
185
public class UserRepresentation extends AbstractUserRepresentation {
186
    public String getId();
187
    public String getUsername();
188
    public String getEmail();
189
    public String getFirstName();
190
    public String getLastName();
191
    public Boolean isEnabled();
192
    public Boolean isEmailVerified();
193
    public List<String> getGroups();
194
    public List<String> getRealmRoles();
195
    public Map<String, Object> getAttributes();
196
}
197

198
public class RealmRepresentation {
199
    public String getId();
200
    public String getRealm();
201
    public String getDisplayName();
202
    public Boolean isEnabled();
203
    public List<UserRepresentation> getUsers();
204
    public List<ClientRepresentation> getClients();
205
    public List<RoleRepresentation> getRoles();
206
}
207
```
208

209
[Identity Management](./identity-management.md)
210

211
### Configuration Management
212

213
Hierarchical configuration system with scoped property access, type-safe configuration retrieval, and extensible provider architecture.
214

215
```java { .api }
216
public class Config {
217
    public static void init();
218
    public static Scope scope(String... scope);
219
    public static String getProvider(String spi);
220
    public static String getAdminRealm();
221
    
222
    public interface Scope {
223
        String get(String key);
224
        String get(String key, String defaultValue);
225
        String[] getArray(String key);
226
        Integer getInt(String key);
227
        Integer getInt(String key, Integer defaultValue);
228
        Long getLong(String key);
229
        Long getLong(String key, Long defaultValue);
230
        Boolean getBoolean(String key);
231
        Boolean getBoolean(String key, Boolean defaultValue);
232
    }
233
}
234
```
235

236
[Configuration Management](./configuration-management.md)
237

238
### Security Context
239

240
Runtime security context management providing access to authentication state, token information, and authorization decisions.
241

242
```java { .api }
243
public class KeycloakSecurityContext {
244
    public AccessToken getToken();
245
    public String getTokenString();
246
    public IDToken getIdToken();
247
    public String getIdTokenString();
248
    public RefreshToken getRefreshToken();
249
    public AuthorizationContext getAuthorizationContext();
250
    public String getRealm();
251
}
252

253
public class AuthorizationContext {
254
    public boolean hasPermission(String resource, String scope);
255
    public boolean hasResourcePermission(String resource);
256
    public boolean hasScopePermission(String scope);
257
    public Collection<Permission> getPermissions();
258
    public boolean isGranted();
259
}
260
```
261

262
[Security Context](./security-context.md)
263

264
### Utility Functions
265

266
Essential utility functions for token processing, JSON serialization, basic authentication, and common operations.
267

268
```java { .api }
269
public class TokenUtil {
270
    public static void attachOIDCScope(MultivaluedMap<String, String> queryParams, 
271
                                     MultivaluedMap<String, String> formParams);
272
    public static boolean isOIDCRequest(String scope);
273
    public static boolean isOfflineTokenRequested(String scope);
274
    public static boolean hasScope(String scopes, String targetScope);
275
    public static RefreshToken getRefreshToken(String refreshToken);
276
    public static boolean isOfflineToken(RefreshToken refreshToken);
277
    
278
    // JWE encoding/decoding methods
279
    public static String jweDirectEncode(Object input, String encryptionAlg, 
280
                                       String contentEncAlg, SecretKey encryptionKey);
281
    public static <T> T jweDirectVerifyAndDecode(String jweStr, SecretKey encryptionKey);
282
}
283

284
public class JsonSerialization {
285
    public static String writeValueAsString(Object obj) throws IOException;
286
    public static byte[] writeValueAsBytes(Object obj) throws IOException;
287
    public static <T> T readValue(String json, Class<T> type) throws IOException;
288
    public static <T> T readValue(byte[] json, Class<T> type) throws IOException;
289
}
290
```
291

292
[Utility Functions](./utility-functions.md)
293

294
## Types
295

296
### Core Enums
297

298
```java { .api }
299
public enum TokenCategory {
300
    INTERNAL, ACCESS, ID, ADMIN, USERINFO, LOGOUT, AUTHORIZATION_RESPONSE
301
}
302

303
public enum KeyType {
304
    EC, RSA, OCT, OKP
305
}
306

307
public enum KeyUse {
308
    SIG, ENC
309
}
310

311
public enum KeyStatus {
312
    ACTIVE, PASSIVE, DISABLED
313
}
314
```
315

316
### Exception Types
317

318
```java { .api }
319
public class TokenVerificationException extends Exception {
320
    public TokenVerificationException(String message);
321
    public TokenVerificationException(String message, Throwable cause);
322
}
323

324
public class TokenNotActiveException extends TokenVerificationException {
325
    public TokenNotActiveException(JsonWebToken token, String message);
326
}
327

328
public class TokenSignatureInvalidException extends TokenVerificationException {
329
    public TokenSignatureInvalidException(JsonWebToken token, String message);
330
}
331

332
public class SignatureException extends Exception {
333
    public SignatureException(String message, Throwable cause);
334
}
335
```
336

337
### Principal and Context Types
338

339
```java { .api }
340
public class KeycloakPrincipal<T extends KeycloakSecurityContext> implements Principal {
341
    public String getName();
342
    public T getKeycloakSecurityContext();
343
}
344

345
public abstract class AbstractOAuthClient {
346
    // OAuth client base implementation
347
}
348
```