0
# Client Interface
1

2
Core OIDC client functionality providing reactive token operations for obtaining, refreshing, and revoking access tokens. All operations return Mutiny `Uni<T>` for non-blocking, reactive processing.
3

4
## Capabilities
5

6
### OidcClient Interface
7

8
Primary interface for OIDC token operations. Each method returns a Mutiny `Uni<T>` for reactive processing.
9

10
```java { .api }
11
/**
12
 * Primary OIDC client interface for token grant operations
13
 */
14
public interface OidcClient extends Closeable {
15
    /**
16
     * Get access and refresh tokens using the configured grant type
17
     * @return Uni<Tokens> containing access and refresh tokens
18
     */
19
    Uni<Tokens> getTokens();
20
    
21
    /**
22
     * Get access and refresh tokens with additional grant parameters
23
     * @param additionalGrantParameters Additional parameters to include in the token request
24
     * @return Uni<Tokens> containing access and refresh tokens
25
     */
26
    Uni<Tokens> getTokens(Map<String, String> additionalGrantParameters);
27
    
28
    /**
29
     * Refresh access tokens using a refresh token
30
     * @param refreshToken The refresh token to use for obtaining new tokens
31
     * @return Uni<Tokens> containing new access and refresh tokens
32
     */
33
    Uni<Tokens> refreshTokens(String refreshToken);
34
    
35
    /**
36
     * Refresh access tokens using a refresh token with additional parameters
37
     * @param refreshToken The refresh token to use for obtaining new tokens
38
     * @param additionalGrantParameters Additional parameters to include in the refresh request
39
     * @return Uni<Tokens> containing new access and refresh tokens
40
     */
41
    Uni<Tokens> refreshTokens(String refreshToken, Map<String, String> additionalGrantParameters);
42
    
43
    /**
44
     * Revoke an access token
45
     * @param accessToken The access token to revoke
46
     * @return Uni<Boolean> true if the token has been revoked or found already invalidated,
47
     *         false if the token cannot be currently revoked
48
     */
49
    Uni<Boolean> revokeAccessToken(String accessToken);
50
    
51
    /**
52
     * Revoke an access token with additional parameters
53
     * @param accessToken The access token to revoke
54
     * @param additionalParameters Additional parameters to include in the revocation request
55
     * @return Uni<Boolean> true if the token has been revoked or found already invalidated,
56
     *         false if the token cannot be currently revoked
57
     */
58
    Uni<Boolean> revokeAccessToken(String accessToken, Map<String, String> additionalParameters);
59
}
60
```
61

62
**Usage Examples:**
63

64
```java
65
import io.quarkus.oidc.client.OidcClient;
66
import io.quarkus.oidc.client.Tokens;
67
import jakarta.inject.Inject;
68

69
@ApplicationScoped
70
public class TokenService {
71
    
72
    @Inject
73
    OidcClient oidcClient;
74
    
75
    public void performTokenOperations() {
76
        // Basic token retrieval
77
        Uni<Tokens> tokens = oidcClient.getTokens();
78
        
79
        // Token retrieval with custom scope
80
        Map<String, String> params = Map.of("scope", "read write admin");
81
        Uni<Tokens> scopedTokens = oidcClient.getTokens(params);
82
        
83
        // Token refresh
84
        tokens.subscribe().with(tokenResult -> {
85
            String refreshToken = tokenResult.getRefreshToken();
86
            if (refreshToken != null) {
87
                Uni<Tokens> refreshedTokens = oidcClient.refreshTokens(refreshToken);
88
                // Handle refreshed tokens...
89
            }
90
        });
91
        
92
        // Token revocation
93
        tokens.subscribe().with(tokenResult -> {
94
            String accessToken = tokenResult.getAccessToken();
95
            Uni<Boolean> revocation = oidcClient.revokeAccessToken(accessToken);
96
            revocation.subscribe().with(revoked -> {
97
                if (revoked) {
98
                    System.out.println("Token revoked successfully");
99
                } else {
100
                    System.out.println("Token revocation failed, may need to retry");
101
                }
102
            });
103
        });
104
    }
105
}
106
```
107

108
### OidcClients Interface
109

110
Factory interface for managing multiple OIDC client instances. Allows access to default clients, named clients, and creation of new clients with custom configurations.
111

112
```java { .api }
113
/**
114
 * Factory interface for managing multiple OIDC client instances
115
 */
116
public interface OidcClients extends Closeable {
117
    /**
118
     * Get the default OIDC client
119
     * @return The default OidcClient instance
120
     */
121
    OidcClient getClient();
122
    
123
    /**
124
     * Get an OIDC client by its identifier
125
     * @param id The identifier of the client to retrieve
126
     * @return The OidcClient instance with the specified id
127
     */
128
    OidcClient getClient(String id);
129
    
130
    /**
131
     * Create a new OIDC client with the provided configuration
132
     * @param clientConfig The configuration for the new client
133
     * @return Uni<OidcClient> representing the asynchronously created client
134
     */
135
    Uni<OidcClient> newClient(OidcClientConfig clientConfig);
136
}
137
```
138

139
**Usage Examples:**
140

141
```java
142
import io.quarkus.oidc.client.OidcClients;
143
import io.quarkus.oidc.client.OidcClient;
144
import io.quarkus.oidc.client.runtime.OidcClientConfig;
145
import jakarta.inject.Inject;
146

147
@ApplicationScoped
148
public class MultiClientService {
149
    
150
    @Inject
151
    OidcClients oidcClients;
152
    
153
    public void useMultipleClients() {
154
        // Use default client
155
        OidcClient defaultClient = oidcClients.getClient();
156
        Uni<Tokens> defaultTokens = defaultClient.getTokens();
157
        
158
        // Use named client (configured in application.properties)
159
        OidcClient authProviderClient = oidcClients.getClient("auth-provider");
160
        Uni<Tokens> authTokens = authProviderClient.getTokens();
161
        
162
        // Create new client programmatically
163
        OidcClientConfig config = OidcClientConfig.builder()
164
            .authServerUrl("https://my-provider.com/auth")
165
            .clientId("my-client")
166
            .clientSecret("my-secret")
167
            .build();
168
            
169
        Uni<OidcClient> newClient = oidcClients.newClient(config);
170
        newClient.subscribe().with(client -> {
171
            Uni<Tokens> tokens = client.getTokens();
172
            // Handle tokens...
173
        });
174
    }
175
}
176
```
177

178
### OidcClientException
179

180
Exception class thrown by OIDC client operations when errors occur during token requests, refreshes, or revocations.
181

182
```java { .api }
183
/**
184
 * Exception thrown by OIDC client operations
185
 */
186
public class OidcClientException extends RuntimeException {
187
    public OidcClientException();
188
    public OidcClientException(String message);
189
    public OidcClientException(Throwable cause);
190
    public OidcClientException(String message, Throwable cause);
191
}
192
```
193

194
**Error Handling:**
195

196
```java
197
import io.quarkus.oidc.client.OidcClientException;
198

199
// Handle exceptions in reactive chains
200
oidcClient.getTokens()
201
    .subscribe().with(
202
        tokens -> {
203
            // Success - handle tokens
204
            String accessToken = tokens.getAccessToken();
205
        },
206
        failure -> {
207
            if (failure instanceof OidcClientException) {
208
                // Handle OIDC-specific errors
209
                System.err.println("OIDC error: " + failure.getMessage());
210
            } else {
211
                // Handle other errors
212
                System.err.println("Unexpected error: " + failure.getMessage());
213
            }
214
        }
215
    );
216
```