0
# Core Adapter Management
1

2
Essential deployment configuration and context management for Keycloak integration. This module provides the foundation for all Keycloak adapter functionality, handling single-tenant and multi-tenant scenarios with comprehensive configuration options.
3

4
## Capabilities
5

6
### KeycloakDeployment
7

8
Core deployment configuration holder that contains all settings needed for Keycloak integration.
9

10
```java { .api }
11
/**
12
 * Core deployment configuration holder containing all Keycloak integration settings
13
 */
14
public class KeycloakDeployment {
15
    public KeycloakDeployment();
16
    
17
    // Configuration state
18
    public boolean isConfigured();
19
    
20
    // Basic configuration
21
    public String getResourceName();
22
    public void setResourceName(String resourceName);
23
    public String getRealm();
24
    public void setRealm(String realm);
25
    public String getAuthServerBaseUrl();
26
    public void setAuthServerBaseUrl(AdapterConfig config);
27
    
28
    // URLs
29
    public String getRealmInfoUrl();
30
    public KeycloakUriBuilder getAuthUrl();
31
    public String getTokenUrl();
32
    public KeycloakUriBuilder getLogoutUrl();
33
    public String getAccountUrl();
34
    public String getJwksUrl();
35
    
36
    // Client configuration
37
    public boolean isBearerOnly();
38
    public void setBearerOnly(boolean bearerOnly);
39
    public boolean isAutodetectBearerOnly();
40
    public void setAutodetectBearerOnly(boolean autodetectBearerOnly);
41
    public boolean isPublicClient();
42
    public void setPublicClient(boolean publicClient);
43
    public boolean isEnableBasicAuth();
44
    public void setEnableBasicAuth(boolean enableBasicAuth);
45
    
46
    // Credentials and authentication
47
    public Map<String, Object> getResourceCredentials();
48
    public void setResourceCredentials(Map<String, Object> resourceCredentials);
49
    public ClientCredentialsProvider getClientAuthenticator();
50
    public void setClientAuthenticator(ClientCredentialsProvider clientAuthenticator);
51
    
52
    // HTTP client
53
    public HttpClient getClient();
54
    public void setClient(HttpClient client);
55
    public void setClient(Callable<HttpClient> callable);
56
    
57
    // SSL configuration
58
    public SslRequired getSslRequired();
59
    public void setSslRequired(SslRequired sslRequired);
60
    public boolean isSSLEnabled();
61
    public int getConfidentialPort();
62
    public void setConfidentialPort(int confidentialPort);
63
    
64
    // Token configuration
65
    public TokenStore getTokenStore();
66
    public void setTokenStore(TokenStore tokenStore);
67
    public String getScope();
68
    public void setScope(String scope);
69
    public boolean isAlwaysRefreshToken();
70
    public void setAlwaysRefreshToken(boolean alwaysRefreshToken);
71
    public int getTokenMinimumTimeToLive();
72
    public void setTokenMinimumTimeToLive(int tokenMinimumTimeToLive);
73
    
74
    // CORS configuration
75
    public boolean isCors();
76
    public void setCors(boolean cors);
77
    public int getCorsMaxAge();
78
    public void setCorsMaxAge(int corsMaxAge);
79
    public String getCorsAllowedHeaders();
80
    public void setCorsAllowedHeaders(String corsAllowedHeaders);
81
    public String getCorsAllowedMethods();
82
    public void setCorsAllowedMethods(String corsAllowedMethods);
83
    public String getCorsExposedHeaders();
84
    public void setCorsExposedHeaders(String corsExposedHeaders);
85
    
86
    // Security configuration
87
    public int getNotBefore();
88
    public void setNotBefore(int notBefore);
89
    public void updateNotBefore(int notBefore);
90
    public boolean isExposeToken();
91
    public void setExposeToken(boolean exposeToken);
92
    public boolean isUseResourceRoleMappings();
93
    public void setUseResourceRoleMappings(boolean useResourceRoleMappings);
94
    
95
    // Session configuration
96
    public String getAdapterStateCookiePath();
97
    public void setAdapterStateCookiePath(String adapterStateCookiePath);
98
    public String getStateCookieName();
99
    public void setStateCookieName(String stateCookieName);
100
    public boolean isTurnOffChangeSessionIdOnLogin();
101
    public void setTurnOffChangeSessionIdOnLogin(boolean turnOffChangeSessionIdOnLogin);
102
    
103
    // Node registration
104
    public boolean isRegisterNodeAtStartup();
105
    public void setRegisterNodeAtStartup(boolean registerNodeAtStartup);
106
    public int getRegisterNodePeriod();
107
    public void setRegisterNodePeriod(int registerNodePeriod);
108
    public String getRegisterNodeUrl();
109
    public String getUnregisterNodeUrl();
110
    
111
    // Advanced configuration
112
    public String getPrincipalAttribute();
113
    public void setPrincipalAttribute(String principalAttribute);
114
    public PublicKeyLocator getPublicKeyLocator();
115
    public void setPublicKeyLocator(PublicKeyLocator publicKeyLocator);
116
    public int getMinTimeBetweenJwksRequests();
117
    public void setMinTimeBetweenJwksRequests(int minTimeBetweenJwksRequests);
118
    public int getPublicKeyCacheTtl();
119
    public void setPublicKeyCacheTtl(int publicKeyCacheTtl);
120
    
121
    // Policy enforcement
122
    public PolicyEnforcer getPolicyEnforcer();
123
    public void setPolicyEnforcer(Callable<PolicyEnforcer> policyEnforcer);
124
    
125
    // PKCE support
126
    public boolean isPkce();
127
    public void setPkce(boolean pkce);
128
    
129
    // OAuth query parameter support
130
    public void setIgnoreOAuthQueryParameter(boolean ignoreOAuthQueryParameter);
131
    public boolean isOAuthQueryParameterEnabled();
132
    
133
    // Redirect rewrite rules
134
    public Map<String, String> getRedirectRewriteRules();
135
    public void setRewriteRedirectRules(Map<String, String> redirectRewriteRules);
136
    
137
    // Bearer token delegation
138
    public boolean isDelegateBearerErrorResponseSending();
139
    public void setDelegateBearerErrorResponseSending(boolean delegateBearerErrorResponseSending);
140
    
141
    // Token audience verification
142
    public boolean isVerifyTokenAudience();
143
    public void setVerifyTokenAudience(boolean verifyTokenAudience);
144
    
145
    // Configuration access
146
    public AdapterConfig getAdapterConfig();
147
}
148
```
149

150
**Usage Examples:**
151

152
```java
153
// Create basic deployment
154
KeycloakDeployment deployment = new KeycloakDeployment();
155
deployment.setRealm("my-realm");
156
deployment.setResourceName("my-client");
157
deployment.setAuthServerBaseUrl(config);
158
deployment.setBearerOnly(true);
159

160
// Configure SSL requirements
161
deployment.setSslRequired(SslRequired.EXTERNAL);
162
deployment.setConfidentialPort(8443);
163

164
// Configure CORS
165
deployment.setCors(true);
166
deployment.setCorsAllowedMethods("GET,POST,PUT,DELETE");
167
deployment.setCorsAllowedHeaders("Content-Type,Authorization");
168

169
// Configure token settings
170
deployment.setTokenMinimumTimeToLive(30);
171
deployment.setAlwaysRefreshToken(false);
172
```
173

174
### KeycloakDeploymentBuilder
175

176
Builder for creating KeycloakDeployment instances from configuration sources.
177

178
```java { .api }
179
/**
180
 * Builder for creating KeycloakDeployment instances from configuration sources
181
 */
182
public class KeycloakDeploymentBuilder {
183
    /**
184
     * Build deployment from input stream containing JSON configuration
185
     * @param is InputStream containing Keycloak JSON configuration
186
     * @return Configured KeycloakDeployment instance
187
     */
188
    public static KeycloakDeployment build(InputStream is);
189
    
190
    /**
191
     * Load adapter configuration from input stream
192
     * @param is InputStream containing configuration
193
     * @return AdapterConfig instance
194
     */
195
    public static AdapterConfig loadAdapterConfig(InputStream is);
196
    
197
    /**
198
     * Build deployment from adapter configuration object
199
     * @param adapterConfig Pre-configured AdapterConfig instance
200
     * @return Configured KeycloakDeployment instance
201
     */
202
    public static KeycloakDeployment build(AdapterConfig adapterConfig);
203
}
204
```
205

206
**Usage Examples:**
207

208
```java
209
// Build from JSON file
210
InputStream configStream = getClass().getResourceAsStream("/keycloak.json");
211
KeycloakDeployment deployment = KeycloakDeploymentBuilder.build(configStream);
212

213
// Build from configuration object
214
AdapterConfig config = new AdapterConfig();
215
config.setRealm("my-realm");
216
config.setResource("my-client");
217
config.setAuthServerUrl("https://keycloak.example.com/auth");
218
KeycloakDeployment deployment = KeycloakDeploymentBuilder.build(config);
219
```
220

221
### AdapterDeploymentContext
222

223
Manages KeycloakDeployment resolution for single-tenant and multi-tenant scenarios.
224

225
```java { .api }
226
/**
227
 * Manages KeycloakDeployment resolution for single-tenant and multi-tenant scenarios
228
 */
229
public class AdapterDeploymentContext {
230
    /**
231
     * Default constructor for programmatic configuration
232
     */
233
    public AdapterDeploymentContext();
234
    
235
    /**
236
     * Single-tenant constructor with fixed deployment
237
     * @param deployment Pre-configured deployment for single tenant
238
     */
239
    public AdapterDeploymentContext(KeycloakDeployment deployment);
240
    
241
    /**
242
     * Multi-tenant constructor with custom resolver
243
     * @param configResolver Custom resolver for per-request deployment resolution
244
     */
245
    public AdapterDeploymentContext(KeycloakConfigResolver configResolver);
246
    
247
    /**
248
     * Resolve deployment for the current request
249
     * @param facade HTTP facade providing request context
250
     * @return Resolved KeycloakDeployment for this request
251
     */
252
    public KeycloakDeployment resolveDeployment(HttpFacade facade);
253
    
254
    /**
255
     * Update deployment configuration
256
     * @param config New configuration to apply
257
     */
258
    public void updateDeployment(AdapterConfig config);
259
}
260
```
261

262
**Usage Examples:**
263

264
```java
265
// Single-tenant deployment
266
KeycloakDeployment deployment = KeycloakDeploymentBuilder.build(configStream);
267
AdapterDeploymentContext context = new AdapterDeploymentContext(deployment);
268

269
// Multi-tenant deployment with custom resolver
270
KeycloakConfigResolver resolver = new KeycloakConfigResolver() {
271
    @Override
272
    public KeycloakDeployment resolve(Request facade) {
273
        String host = facade.getHeader("Host");
274
        if ("tenant1.example.com".equals(host)) {
275
            return getTenant1Deployment();
276
        } else if ("tenant2.example.com".equals(host)) {
277
            return getTenant2Deployment();
278
        }
279
        return getDefaultDeployment();
280
    }
281
};
282
AdapterDeploymentContext multiTenantContext = new AdapterDeploymentContext(resolver);
283

284
// Resolve deployment for current request
285
KeycloakDeployment currentDeployment = context.resolveDeployment(httpFacade);
286
```
287

288
### KeycloakConfigResolver
289

290
Interface for multi-tenant deployment resolution.
291

292
```java { .api }
293
/**
294
 * Interface for resolving Keycloak deployment configuration in multi-tenant scenarios
295
 */
296
public interface KeycloakConfigResolver {
297
    /**
298
     * Resolve deployment configuration based on the current request
299
     * @param facade Request facade providing access to request context
300
     * @return KeycloakDeployment appropriate for this request
301
     */
302
    KeycloakDeployment resolve(Request facade);
303
}
304
```
305

306
**Usage Examples:**
307

308
```java
309
// Custom resolver implementation
310
public class TenantBasedConfigResolver implements KeycloakConfigResolver {
311
    private final Map<String, KeycloakDeployment> tenantDeployments;
312
    
313
    public TenantBasedConfigResolver(Map<String, KeycloakDeployment> deployments) {
314
        this.tenantDeployments = deployments;
315
    }
316
    
317
    @Override
318
    public KeycloakDeployment resolve(Request facade) {
319
        String tenantId = extractTenantId(facade);
320
        return tenantDeployments.get(tenantId);
321
    }
322
    
323
    private String extractTenantId(Request facade) {
324
        // Extract tenant ID from subdomain, path, header, etc.
325
        String host = facade.getHeader("Host");
326
        return host.split("\\.")[0]; // Extract subdomain as tenant ID
327
    }
328
}
329
```
330

331
### AdapterUtils  
332

333
Utility methods for common adapter operations.
334

335
```java { .api }
336
/**
337
 * Utility methods for common adapter operations
338
 */
339
public class AdapterUtils {
340
    /**
341
     * Generate unique identifier string
342
     * @return Unique ID string
343
     */
344
    public static String generateId();
345
    
346
    /**
347
     * Extract roles from security context
348
     * @param session Security context containing role information
349
     * @return Set of role names
350
     */
351
    public static Set<String> getRolesFromSecurityContext(RefreshableKeycloakSecurityContext session);
352
    
353
    /**
354
     * Get principal name from token based on deployment configuration
355
     * @param deployment Deployment configuration
356
     * @param token Access token containing user information
357
     * @return Principal name string
358
     */
359
    public static String getPrincipalName(KeycloakDeployment deployment, AccessToken token);
360
    
361
    /**
362
     * Create Keycloak principal from security context
363
     * @param deployment Deployment configuration
364
     * @param securityContext Security context
365
     * @return KeycloakPrincipal instance
366
     */
367
    public static KeycloakPrincipal<RefreshableKeycloakSecurityContext> createPrincipal(
368
        KeycloakDeployment deployment, 
369
        RefreshableKeycloakSecurityContext securityContext
370
    );
371
    
372
    /**
373
     * Set client credentials on HTTP request
374
     * @param deployment Deployment containing client credentials
375
     * @param post HTTP POST request to configure
376
     * @param formparams Form parameters list to populate
377
     */
378
    public static void setClientCredentials(
379
        KeycloakDeployment deployment, 
380
        HttpPost post, 
381
        List<NameValuePair> formparams
382
    );
383
}
384
```
385

386
**Usage Examples:**
387

388
```java
389
// Generate unique ID
390
String sessionId = AdapterUtils.generateId();
391

392
// Extract principal name
393
String principalName = AdapterUtils.getPrincipalName(deployment, accessToken);
394

395
// Create principal
396
KeycloakPrincipal<RefreshableKeycloakSecurityContext> principal = 
397
    AdapterUtils.createPrincipal(deployment, securityContext);
398

399
// Get user roles
400
Set<String> roles = AdapterUtils.getRolesFromSecurityContext(securityContext);
401
```