or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-interface.mdconfiguration.mdindex.mdintegration.mdtoken-management.md
tile.json

tessl/maven-io-quarkus--quarkus-oidc-client

Get and refresh access tokens from OpenID Connect providers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-oidc-client@3.26.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-oidc-client@3.26.0

index.mddocs/

Quarkus OIDC Client Extension

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.

Package Information

  • Package Name: quarkus-oidc-client
  • Package Type: maven
  • Language: Java
  • Installation: Add dependency to your pom.xml:
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc-client</artifactId>
    <version>3.26.2</version>
</dependency>

Core Imports

import io.quarkus.oidc.client.OidcClient;
import io.quarkus.oidc.client.OidcClients;
import io.quarkus.oidc.client.Tokens;
import io.quarkus.oidc.client.runtime.OidcClientConfig;
import io.quarkus.oidc.client.OidcClientConfigBuilder;

Basic Usage

import io.quarkus.oidc.client.OidcClient;
import io.quarkus.oidc.client.OidcClients;
import io.quarkus.oidc.client.Tokens;
import io.smallrye.mutiny.Uni;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import java.util.Map;

@ApplicationScoped
public class TokenService {
    
    @Inject
    OidcClient oidcClient;
    
    @Inject
    OidcClients oidcClients;
    
    public void getTokens() {
        // Get tokens using default client
        Uni<Tokens> tokens = oidcClient.getTokens();
        
        // Get tokens with additional parameters
        Map<String, String> additionalParams = Map.of("scope", "read write");
        Uni<Tokens> tokensWithParams = oidcClient.getTokens(additionalParams);
        
        // Refresh tokens
        String refreshToken = "existing_refresh_token";
        Uni<Tokens> refreshedTokens = oidcClient.refreshTokens(refreshToken);
        
        // Use named client
        OidcClient namedClient = oidcClients.getClient("my-provider");
        Uni<Tokens> namedTokens = namedClient.getTokens();
    }
}

Architecture

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

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

Capabilities

Client Interface

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

public interface OidcClient extends Closeable {
    Uni<Tokens> getTokens();
    Uni<Tokens> getTokens(Map<String, String> additionalGrantParameters);
    Uni<Tokens> refreshTokens(String refreshToken);
    Uni<Tokens> refreshTokens(String refreshToken, Map<String, String> additionalGrantParameters);
    Uni<Boolean> revokeAccessToken(String accessToken);
    Uni<Boolean> revokeAccessToken(String accessToken, Map<String, String> additionalParameters);
}

public interface OidcClients extends Closeable {
    OidcClient getClient();
    OidcClient getClient(String id);
    Uni<OidcClient> newClient(OidcClientConfig clientConfig);
}

Client Interface

Configuration

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

public interface OidcClientConfig extends OidcClientCommonConfig {
    Optional<String> id();
    Optional<Boolean> clientEnabled();
    Optional<List<String>> scopes();
    Optional<List<String>> audience();
    Optional<Duration> refreshTokenTimeSkew();
    Grant grant();
    
    static OidcClientConfigBuilder builder() { /* ... */ }
    static OidcClientConfigBuilder authServerUrl(String authServerUrl) { /* ... */ }
}

public class OidcClientConfigBuilder {
    public OidcClientConfigBuilder id(String id);
    public OidcClientConfigBuilder scopes(List<String> scopes);
    public OidcClientConfigBuilder audience(List<String> audience);
    public GrantBuilder grant();
    public OidcClientConfig build();
}

Configuration

Token Management

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

public class Tokens {
    public Tokens(String accessToken, Long accessTokenExpiresAt, Duration refreshTokenTimeSkew, 
                  String refreshToken, Long refreshTokenExpiresAt, JsonObject grantResponse, String clientId);
    
    public String getAccessToken();
    public String getRefreshToken();
    public String getClientId();
    public Object get(String propertyName);
    public Long getAccessTokenExpiresAt();
    public Duration getRefreshTokenTimeSkew();
    public boolean isAccessTokenExpired();
    public boolean isRefreshTokenExpired();
    public boolean isAccessTokenWithinRefreshInterval();
}

Token Management

Integration

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

@Qualifier
@Retention(RUNTIME)
@Target({FIELD, PARAMETER, METHOD})
public @interface NamedOidcClient {
    String value();
}

@Target({TYPE})
@Retention(RUNTIME)
public @interface OidcClientFilter {
    String value() default "";
}

public interface TokenProvider {
    Uni<String> getAccessToken();
}

Integration

Grant Types Supported

The extension supports all major OAuth2/OIDC grant types:

  • CLIENT (client_credentials) - Client credentials grant
  • PASSWORD (password) - Resource owner password credentials grant
  • CODE (authorization_code) - Authorization code grant
  • EXCHANGE (urn:ietf:params:oauth:grant-type:token-exchange) - Token exchange grant
  • JWT (urn:ietf:params:oauth:grant-type:jwt-bearer) - JWT bearer grant
  • REFRESH (refresh_token) - Refresh token grant
  • CIBA (urn:openid:params:grant-type:ciba) - Client Initiated Backchannel Authentication
  • DEVICE (urn:ietf:params:oauth:grant-type:device_code) - Device authorization grant