0
# Configuration
1

2
Configuration system for OIDC clients supporting both builder pattern for programmatic setup and properties-based configuration. Supports multiple OIDC providers, various grant types, and extensive customization options.
3

4
## Capabilities
5

6
### OidcClientConfig Interface
7

8
Modern configuration interface for OIDC clients extending the common OIDC configuration base. Provides comprehensive configuration options for authentication, token management, and client behavior.
9

10
```java { .api }
11
/**
12
 * Configuration interface for OIDC clients
13
 */
14
public interface OidcClientConfig extends OidcClientCommonConfig {
15
    /**
16
     * Client identifier for named clients
17
     * @return Optional client identifier
18
     */
19
    Optional<String> id();
20
    
21
    /**
22
     * Enable or disable the client
23
     * @return boolean indicating if client is enabled
24
     */
25
    boolean clientEnabled();
26
    
27
    /**
28
     * Access token scopes to request
29
     * @return Optional list of scope strings
30
     */
31
    Optional<List<String>> scopes();
32
    
33
    /**
34
     * Access token audiences to request
35
     * @return Optional list of audience strings
36
     */
37
    Optional<List<String>> audience();
38
    
39
    /**
40
     * Refresh token time skew for early refresh
41
     * @return Optional duration for refresh time skew
42
     */
43
    Optional<Duration> refreshTokenTimeSkew();
44
    
45
    /**
46
     * Access token expiration period override
47
     * @return Optional duration for access token expiration
48
     */
49
    Optional<Duration> accessTokenExpiresIn();
50
    
51
    /**
52
     * Access token expiry time skew
53
     * @return Optional duration for expiry skew
54
     */
55
    Optional<Duration> accessTokenExpirySkew();
56
    
57
    /**
58
     * Whether expiration times are absolute or relative
59
     * @return boolean for absolute expiration
60
     */
61
    boolean absoluteExpiresIn();
62
    
63
    /**
64
     * Grant configuration for this client
65
     * @return Grant configuration
66
     */
67
    Grant grant();
68
    
69
    /**
70
     * Additional grant options
71
     * @return map of grant options
72
     */
73
    Map<String, Map<String, String>> grantOptions();
74
    
75
    /**
76
     * Enable early token acquisition
77
     * @return boolean for early acquisition
78
     */
79
    boolean earlyTokensAcquisition();
80
    
81
    /**
82
     * Custom HTTP headers for requests
83
     * @return map of custom headers
84
     */
85
    Map<String, String> headers();
86
    
87
    /**
88
     * Token refresh interval
89
     * @return Optional duration for refresh interval
90
     */
91
    Optional<Duration> refreshInterval();
92
    
93
    /**
94
     * Create a builder with default configuration
95
     * @return New OidcClientConfigBuilder instance
96
     */
97
    static OidcClientConfigBuilder builder();
98
    
99
    /**
100
     * Create a builder from existing configuration
101
     * @param config Existing configuration to copy
102
     * @return New OidcClientConfigBuilder instance
103
     */
104
    static OidcClientConfigBuilder builder(OidcClientConfig config);
105
    
106
    /**
107
     * Create a builder with auth server URL
108
     * @param authServerUrl The authorization server URL
109
     * @return New OidcClientConfigBuilder instance
110
     */
111
    static OidcClientConfigBuilder authServerUrl(String authServerUrl);
112
    
113
    /**
114
     * Create a builder with registration path
115
     * @param registrationPath The registration path
116
     * @return New OidcClientConfigBuilder instance
117
     */
118
    static OidcClientConfigBuilder registrationPath(String registrationPath);
119
    
120
    /**
121
     * Create a builder with token path
122
     * @param tokenPath The token endpoint path
123
     * @return New OidcClientConfigBuilder instance
124
     */
125
    static OidcClientConfigBuilder tokenPath(String tokenPath);
126
}
127
```
128

129
### Grant Configuration
130

131
Configuration interface for specifying grant types and token property mappings.
132

133
```java { .api }
134
/**
135
 * Grant type configuration interface
136
 */
137
public interface Grant {
138
    /**
139
     * The grant type to use
140
     * @return Grant type enum value
141
     */
142
    Type type();
143
    
144
    /**
145
     * Property name for access token in response
146
     * @return access token property name
147
     */
148
    String accessTokenProperty();
149
    
150
    /**
151
     * Property name for refresh token in response
152
     * @return refresh token property name
153
     */
154
    String refreshTokenProperty();
155
    
156
    /**
157
     * Property name for expires_in value in response
158
     * @return expires in property name
159
     */
160
    String expiresInProperty();
161
    
162
    /**
163
     * Property name for refresh token expires_in value in response
164
     * @return refresh expires in property name
165
     */
166
    String refreshExpiresInProperty();
167
    
168
    /**
169
     * Grant types supported by the OIDC client
170
     */
171
    enum Type {
172
        CLIENT,     // client_credentials
173
        PASSWORD,   // password
174
        CODE,       // authorization_code
175
        EXCHANGE,   // urn:ietf:params:oauth:grant-type:token-exchange
176
        JWT,        // urn:ietf:params:oauth:grant-type:jwt-bearer
177
        REFRESH,    // refresh_token
178
        CIBA,       // urn:openid:params:grant-type:ciba
179
        DEVICE      // urn:ietf:params:oauth:grant-type:device_code
180
    }
181
}
182
```
183

184
### OidcClientConfigBuilder
185

186
Builder class for programmatic configuration of OIDC clients. Provides fluent API for setting up client configuration.
187

188
```java { .api }
189
/**
190
 * Builder for creating OidcClientConfig instances
191
 */
192
public class OidcClientConfigBuilder {
193
    /**
194
     * Create builder with no initial configuration
195
     */
196
    public OidcClientConfigBuilder();
197
    
198
    /**
199
     * Create builder from existing configuration
200
     * @param config Existing configuration to copy
201
     */
202
    public OidcClientConfigBuilder(OidcClientConfig config);
203
    
204
    /**
205
     * Set client identifier
206
     * @param id Client identifier
207
     * @return This builder instance
208
     */
209
    public OidcClientConfigBuilder id(String id);
210
    
211
    /**
212
     * Enable or disable the client
213
     * @param enabled Whether client is enabled
214
     * @return This builder instance
215
     */
216
    public OidcClientConfigBuilder clientEnabled(boolean enabled);
217
    
218
    /**
219
     * Set access token scopes
220
     * @param scopes List of scope strings
221
     * @return This builder instance
222
     */
223
    public OidcClientConfigBuilder scopes(List<String> scopes);
224
    
225
    /**
226
     * Set access token audiences
227
     * @param audience List of audience strings
228
     * @return This builder instance
229
     */
230
    public OidcClientConfigBuilder audience(List<String> audience);
231
    
232
    /**
233
     * Set custom HTTP headers
234
     * @param headers Map of header name to value
235
     * @return This builder instance
236
     */
237
    public OidcClientConfigBuilder headers(Map<String, String> headers);
238
    
239
    /**
240
     * Configure grant settings
241
     * @return GrantBuilder for configuring grant options
242
     */
243
    public GrantBuilder grant();
244
    
245
    /**
246
     * Build the final configuration
247
     * @return Configured OidcClientConfig instance
248
     */
249
    public OidcClientConfig build();
250
    
251
    /**
252
     * Nested builder for grant configuration
253
     */
254
    public static class GrantBuilder {
255
        /**
256
         * Set the grant type
257
         * @param type Grant type to use
258
         * @return This grant builder instance
259
         */
260
        public GrantBuilder type(Grant.Type type);
261
        
262
        /**
263
         * Return to parent builder
264
         * @return Parent OidcClientConfigBuilder instance
265
         */
266
        public OidcClientConfigBuilder and();
267
    }
268
}
269
```
270

271
**Usage Examples:**
272

273
```java
274
import io.quarkus.oidc.client.runtime.OidcClientConfig;
275
import io.quarkus.oidc.client.OidcClientConfigBuilder;
276

277
// Basic client credentials configuration
278
OidcClientConfig config = OidcClientConfig.builder()
279
    .authServerUrl("https://auth.example.com")
280
    .clientId("my-client")
281
    .clientSecret("my-secret")
282
    .grant().type(Grant.Type.CLIENT).and()
283
    .scopes(List.of("read", "write"))
284
    .build();
285

286
// Password grant configuration
287
OidcClientConfig passwordConfig = OidcClientConfig.builder()
288
    .authServerUrl("https://auth.example.com")
289
    .clientId("password-client")
290
    .clientSecret("password-secret")
291
    .grant().type(Grant.Type.PASSWORD).and()
292
    .build();
293

294
// JWT bearer grant configuration
295
OidcClientConfig jwtConfig = OidcClientConfig.builder()
296
    .authServerUrl("https://auth.example.com")
297
    .clientId("jwt-client")
298
    .grant().type(Grant.Type.JWT).and()
299
    .audience(List.of("https://api.example.com"))
300
    .build();
301

302
// Configuration with custom headers and timeouts
303
OidcClientConfig customConfig = OidcClientConfig.builder()
304
    .authServerUrl("https://auth.example.com")
305
    .clientId("custom-client")
306
    .clientSecret("custom-secret")
307
    .headers(Map.of(
308
        "User-Agent", "MyApp/1.0",
309
        "X-Custom-Header", "custom-value"
310
    ))
311
    .refreshTokenTimeSkew(Duration.ofMinutes(5))
312
    .accessTokenExpirySkew(Duration.ofSeconds(30))
313
    .build();
314
```
315

316
### Legacy OidcClientConfig (Deprecated)
317

318
The original configuration class, now deprecated in favor of the runtime configuration interface.
319

320
```java { .api }
321
/**
322
 * Legacy configuration class (deprecated since 3.18)
323
 * @deprecated Use io.quarkus.oidc.client.runtime.OidcClientConfig with OidcClientConfigBuilder
324
 */
325
@Deprecated
326
public class OidcClientConfig implements io.quarkus.oidc.client.runtime.OidcClientConfig {
327
    // Implementation details...
328
}
329
```
330

331
**Migration Example:**
332

333
```java
334
// Old approach (deprecated)
335
import io.quarkus.oidc.client.OidcClientConfig;
336

337
// New approach (recommended)
338
import io.quarkus.oidc.client.runtime.OidcClientConfig;
339
import io.quarkus.oidc.client.OidcClientConfigBuilder;
340

341
// Create configuration using new builder pattern
342
OidcClientConfig newConfig = OidcClientConfig.builder()
343
    .authServerUrl("https://auth.example.com")
344
    .clientId("my-client")
345
    .clientSecret("my-secret")
346
    .build();
347
```
348

349
## Properties-Based Configuration
350

351
In addition to programmatic configuration, clients can be configured using `application.properties`:
352

353
```properties
354
# Default client configuration
355
quarkus.oidc-client.auth-server-url=https://auth.example.com
356
quarkus.oidc-client.client-id=default-client
357
quarkus.oidc-client.credentials.secret=default-secret
358
quarkus.oidc-client.grant.type=client
359

360
# Named client configuration
361
quarkus.oidc-client.provider-1.auth-server-url=https://provider1.example.com
362
quarkus.oidc-client.provider-1.client-id=provider1-client
363
quarkus.oidc-client.provider-1.credentials.secret=provider1-secret
364
quarkus.oidc-client.provider-1.grant.type=password
365

366
# Client with custom scopes and headers
367
quarkus.oidc-client.api-client.auth-server-url=https://api.example.com
368
quarkus.oidc-client.api-client.client-id=api-client
369
quarkus.oidc-client.api-client.credentials.secret=api-secret
370
quarkus.oidc-client.api-client.scopes=read,write,admin
371
quarkus.oidc-client.api-client.headers.User-Agent=MyApp/1.0
372
```