0
# Quarkus OIDC Client Extension
1

2
The Quarkus OIDC Client extension provides OpenID Connect (OIDC) client functionality for obtaining and refreshing access tokens from OIDC providers. It supports various OAuth2/OIDC grant types and integrates seamlessly with Quarkus's reactive programming model using Mutiny for asynchronous operations.
3

4
## Package Information
5

6
- **Package Name**: quarkus-oidc-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to your `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>io.quarkus</groupId>
14
    <artifactId>quarkus-oidc-client</artifactId>
15
    <version>3.26.2</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import io.quarkus.oidc.client.OidcClient;
23
import io.quarkus.oidc.client.OidcClients;
24
import io.quarkus.oidc.client.Tokens;
25
import io.quarkus.oidc.client.runtime.OidcClientConfig;
26
import io.quarkus.oidc.client.OidcClientConfigBuilder;
27
```
28

29
## Basic Usage
30

31
```java
32
import io.quarkus.oidc.client.OidcClient;
33
import io.quarkus.oidc.client.OidcClients;
34
import io.quarkus.oidc.client.Tokens;
35
import io.smallrye.mutiny.Uni;
36
import jakarta.enterprise.context.ApplicationScoped;
37
import jakarta.inject.Inject;
38
import java.util.Map;
39

40
@ApplicationScoped
41
public class TokenService {
42
    
43
    @Inject
44
    OidcClient oidcClient;
45
    
46
    @Inject
47
    OidcClients oidcClients;
48
    
49
    public void getTokens() {
50
        // Get tokens using default client
51
        Uni<Tokens> tokens = oidcClient.getTokens();
52
        
53
        // Get tokens with additional parameters
54
        Map<String, String> additionalParams = Map.of("scope", "read write");
55
        Uni<Tokens> tokensWithParams = oidcClient.getTokens(additionalParams);
56
        
57
        // Refresh tokens
58
        String refreshToken = "existing_refresh_token";
59
        Uni<Tokens> refreshedTokens = oidcClient.refreshTokens(refreshToken);
60
        
61
        // Use named client
62
        OidcClient namedClient = oidcClients.getClient("my-provider");
63
        Uni<Tokens> namedTokens = namedClient.getTokens();
64
    }
65
}
66
```
67

68
## Architecture
69

70
The Quarkus OIDC Client extension is built around several key components:
71

72
- **Client Interface**: `OidcClient` provides reactive token operations with Mutiny `Uni<T>` return types
73
- **Client Factory**: `OidcClients` manages multiple OIDC client instances and configurations
74
- **Token Management**: `Tokens` class encapsulates access and refresh tokens with expiration tracking
75
- **Configuration System**: Builder pattern for programmatic configuration and annotation-based CDI integration
76
- **Grant Support**: Comprehensive OAuth2/OIDC grant type support including client credentials, authorization code, refresh token, and more
77
- **Integration Layer**: Seamless CDI injection, JAX-RS filter integration, and SPI for custom implementations
78

79
## Capabilities
80

81
### Client Interface
82

83
Core OIDC client functionality for token operations including obtaining, refreshing, and revoking tokens. All operations return Mutiny `Uni<T>` for reactive processing.
84

85
```java { .api }
86
public interface OidcClient extends Closeable {
87
    Uni<Tokens> getTokens();
88
    Uni<Tokens> getTokens(Map<String, String> additionalGrantParameters);
89
    Uni<Tokens> refreshTokens(String refreshToken);
90
    Uni<Tokens> refreshTokens(String refreshToken, Map<String, String> additionalGrantParameters);
91
    Uni<Boolean> revokeAccessToken(String accessToken);
92
    Uni<Boolean> revokeAccessToken(String accessToken, Map<String, String> additionalParameters);
93
}
94

95
public interface OidcClients extends Closeable {
96
    OidcClient getClient();
97
    OidcClient getClient(String id);
98
    Uni<OidcClient> newClient(OidcClientConfig clientConfig);
99
}
100
```
101

102
[Client Interface](./client-interface.md)
103

104
### Configuration
105

106
Configuration system supporting both builder pattern for programmatic setup and annotation-based configuration. Supports multiple OIDC providers and grant types.
107

108
```java { .api }
109
public interface OidcClientConfig extends OidcClientCommonConfig {
110
    Optional<String> id();
111
    Optional<Boolean> clientEnabled();
112
    Optional<List<String>> scopes();
113
    Optional<List<String>> audience();
114
    Optional<Duration> refreshTokenTimeSkew();
115
    Grant grant();
116
    
117
    static OidcClientConfigBuilder builder() { /* ... */ }
118
    static OidcClientConfigBuilder authServerUrl(String authServerUrl) { /* ... */ }
119
}
120

121
public class OidcClientConfigBuilder {
122
    public OidcClientConfigBuilder id(String id);
123
    public OidcClientConfigBuilder scopes(List<String> scopes);
124
    public OidcClientConfigBuilder audience(List<String> audience);
125
    public GrantBuilder grant();
126
    public OidcClientConfig build();
127
}
128
```
129

130
[Configuration](./configuration.md)
131

132
### Token Management
133

134
Token container and management functionality providing access to tokens, expiration tracking, and automatic refresh capabilities.
135

136
```java { .api }
137
public class Tokens {
138
    public Tokens(String accessToken, Long accessTokenExpiresAt, Duration refreshTokenTimeSkew, 
139
                  String refreshToken, Long refreshTokenExpiresAt, JsonObject grantResponse, String clientId);
140
    
141
    public String getAccessToken();
142
    public String getRefreshToken();
143
    public String getClientId();
144
    public Object get(String propertyName);
145
    public Long getAccessTokenExpiresAt();
146
    public Duration getRefreshTokenTimeSkew();
147
    public boolean isAccessTokenExpired();
148
    public boolean isRefreshTokenExpired();
149
    public boolean isAccessTokenWithinRefreshInterval();
150
}
151
```
152

153
[Token Management](./token-management.md)
154

155
### Integration
156

157
CDI injection support, JAX-RS client filter integration, and SPI interfaces for extending OIDC client functionality.
158

159
```java { .api }
160
@Qualifier
161
@Retention(RUNTIME)
162
@Target({FIELD, PARAMETER, METHOD})
163
public @interface NamedOidcClient {
164
    String value();
165
}
166

167
@Target({TYPE})
168
@Retention(RUNTIME)
169
public @interface OidcClientFilter {
170
    String value() default "";
171
}
172

173
public interface TokenProvider {
174
    Uni<String> getAccessToken();
175
}
176
```
177

178
[Integration](./integration.md)
179

180
## Grant Types Supported
181

182
The extension supports all major OAuth2/OIDC grant types:
183

184
- **CLIENT** (`client_credentials`) - Client credentials grant
185
- **PASSWORD** (`password`) - Resource owner password credentials grant  
186
- **CODE** (`authorization_code`) - Authorization code grant
187
- **EXCHANGE** (`urn:ietf:params:oauth:grant-type:token-exchange`) - Token exchange grant
188
- **JWT** (`urn:ietf:params:oauth:grant-type:jwt-bearer`) - JWT bearer grant
189
- **REFRESH** (`refresh_token`) - Refresh token grant
190
- **CIBA** (`urn:openid:params:grant-type:ciba`) - Client Initiated Backchannel Authentication
191
- **DEVICE** (`urn:ietf:params:oauth:grant-type:device_code`) - Device authorization grant