The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
このページを編集

OpenID Connect (OIDC) と OAuth2 クライアントおよびフィルター

Quarkus エクステンションは、OpenID Connect と OAuth 2.0 のアクセストークン管理に利用できます。トークンの取得、更新、伝播に重点を置いています。

これには、以下が含まれます。

  • quarkus-oidc-clientquarkus-rest-client-oidc-filterquarkus-resteasy-client-oidc-filter のエクステンションを使用して、Keycloak のような OpenID Connect および OAuth 2.0 準拠の認可サーバーからアクセストークンを取得および更新できます。

  • quarkus-rest-client-oidc-token-propagation および quarkus-resteasy-client-oidc-token-propagation エクステンションを使用して、現在の Bearer または 認可コードフロー のアクセストークンを伝播できます。

これらのエクステンションによって管理されるアクセストークンは、リモートサービスにアクセスするための HTTP Authorization ベアラー トークンとして使用できます。

OidcClient

次の依存関係を追加します。

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc-client</artifactId>
</dependency>

quarkus-oidc-client エクステンションは、SmallRye Mutiny UniVert.x WebClient を使用してトークンを取得および更新するために使用できる、リアクティブな io.quarkus.oidc.client.OidcClient を提供します。

OidcClient は、IDP トークンエンドポイント URL (自動検出または手動設定が可能) でビルド時に初期化されます。OidcClient はこのエンドポイントを使用して、 client_credentialspassword などのトークングラントでアクセストークンを取得し、 refresh_token グラントでトークンをリフレッシュします。

トークンエンドポイントの設定

デフォルトでは、トークンエンドポイントのアドレスは、設定されている quarkus.oidc-client.auth-server-url/.well-known/openid-configuration パスを追加することで検出されます。

たとえば、次の Keycloak URL があるとします。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus

OidcClient は、トークンエンドポイント URL が http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/tokens であることを検出します。

あるいは、ディスカバリーエンドポイントが利用できない場合や、それへの余分なラウンドトリップを避けたい場合は、ディスカバリーを無効にして、相対パスでトークンエンドポイントアドレスを設定できます。

次に例を示します:

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus
quarkus.oidc-client.discovery-enabled=false
# Token endpoint: http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/tokens
quarkus.oidc-client.token-path=/protocol/openid-connect/tokens

ディスカバリーなしでトークンエンドポイント URL を設定する、よりコンパクトな方法は、quarkus.oidc-client.token-path を絶対 URL に設定することです。

quarkus.oidc-client.token-path=http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/tokens

この場合、quarkus.oidc-client.auth-server-urlquarkus.oidc-client.discovery-enabled の設定は必要ありません。

サポートされるトークングラント

OidcClient がトークンを取得するために使用できる主なトークングラントは、client_credentials (デフォルト) と password グラントです。

クライアントクレデンシャルグラント

OidcClientclient_credentials グラントを使用するように設定する方法は次のとおりです。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret

client_credentials グラントでは、 quarkus.oidc-client.grant-options.client.<param-name>=<value> を使用して、トークンリクエストに追加のパラメーターを設定できます。

ここでは、 audience パラメーターを使用して、トークンの受信者を設定する方法を説明します。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
# 'client' is a shortcut for `client_credentials`
quarkus.oidc-client.grant.type=client
quarkus.oidc-client.grant-options.client.audience=https://example.com/api

パスワードグラント

OidcClientpassword グラントを使用するように設定する方法は次のとおりです。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
quarkus.oidc-client.grant.type=password
quarkus.oidc-client.grant-options.password.username=alice
quarkus.oidc-client.grant-options.password.password=alice

クライアントクレデンシャルグラントと同様に、 quarkus.oidc-client.grant-options.password 設定接頭辞を使用してさらにカスタマイズできます。

その他のグラント

OidcClient は、設定で捕捉できない追加の入力パラメーターを必要とするグラントでトークンを取得するのにも役立ちます。

これらのグラントは、 refresh_token (外部リフレッシュトークンを使用)、 authorization_code 、および現在のアクセストークンを交換するために使用できる 2 つのグラント、すなわち以下のものです。

  • urn:ietf:params:oauth:grant-type:token-exchange

  • urn:ietf:params:oauth:grant-type:jwt-bearer

アクセストークンを取得する必要があり、既存のリフレッシュトークンを現在の Quarkus エンドポイントにポストしている場合は、 refresh_token グラントを使用する必要があります。このグラントは、アウトオブバンドのリフレッシュトークンを使用して新しいトークンセットを取得します。

この場合、 OidcClient を次のように設定します。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
quarkus.oidc-client.grant.type=refresh

次に、OidcClient.refreshTokens メソッドと提供されたリフレッシュトークンを使用して、アクセストークンを取得できます。

複雑なマイクロサービスアプリケーションを構築しており、同じ Bearer トークンが複数のサービスに伝播されて使用されるのを避けたい場合は、 urn:ietf:params:oauth:grant-type:token-exchange または urn:ietf:params:oauth:grant-type:jwt-bearer グラントの使用が必要になる場合があります。

詳細については、Token Propagation for Quarkus RESTToken Propagation for RESTEasy Classic を参照してください。

Quarkus OIDC エクステンション を使用して認可コードフローをサポートできない場合は、 OidcClient を使用して authorization code グラントをサポートする必要がある場合があります。

認可コードフローを実装する正当な理由がある場合は、 OidcClient を次のように設定できます。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
quarkus.oidc-client.grant.type=code

次に、OidcClient.accessTokens メソッドを使用して追加プロパティーの Map を受け入れ、現在の code および redirect_uri パラメーターを渡して、認可コードをトークンと交換できます。

OidcClienturn:openid:params:grant-type:ciba グラントもサポートしています。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
quarkus.oidc-client.grant.type=ciba

次に、OidcClient.accessTokens メソッドを使用して追加プロパティーの Map を受け入れ、auth_req_id パラメーターを渡してトークンの認可コードを交換できます。

グラントスコープ

発行されたアクセストークンに特定のスコープのセットが関連付けられるように要求する必要がある場合があります。専用の quarkus.oidc-client.scopes リストプロパティーを使用します。例: quarkus.oidc-client.scopes=email,phone

OidcClient を直接使用する

OidcClient を直接使用してアクセストークンを取得し、HTTP Authorization ヘッダーに Bearer スキーム値として設定できます。

たとえば、Quarkus エンドポイントがユーザー名を返すマイクロサービスにアクセスする必要があると仮定します。

  1. REST クライアントを作成します。

    package org.acme.security.openid.connect.client;
    
    import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
    
    import io.smallrye.mutiny.Uni;
    import jakarta.ws.rs.GET;
    import jakarta.ws.rs.HeaderParam;
    import jakarta.ws.rs.Path;
    import jakarta.ws.rs.Produces;
    
    @RegisterRestClient
    @Path("/")
    public interface RestClientWithTokenHeaderParam {
    
        @GET
        @Produces("text/plain")
        @Path("userName")
        Uni<String> getUserName(@HeaderParam("Authorization") String authorization);
    }
  2. OidcClient を使用してトークンを取得し、伝播します。

    package org.acme.security.openid.connect.client;
    
    import org.eclipse.microprofile.rest.client.inject.RestClient;
    
    import io.quarkus.oidc.client.runtime.TokensHelper;
    import io.quarkus.oidc.client.OidcClient;
    
    import io.smallrye.mutiny.Uni;
    import jakarta.inject.Inject;
    import jakarta.ws.rs.GET;
    import jakarta.ws.rs.Path;
    import jakarta.ws.rs.Produces;
    
    @Path("/service")
    public class OidcClientResource {
    
        @Inject
        OidcClient client;
        TokensHelper tokenHelper = new TokensHelper(); (1)
    
        @Inject
        @RestClient
        RestClientWithTokenHeaderParam restClient;
    
        @GET
        @Path("user-name")
        @Produces("text/plain")
        public Uni<String> getUserName() {
        	return tokenHelper.getTokens(client).onItem()
            		.transformToUni(tokens -> restClient.getUserName("Bearer " + tokens.getAccessToken()));
        }
    }
    1 io.quarkus.oidc.client.runtime.TokensHelper は、アクセストークンの取得と更新を管理します。

トークンの注入

OidcClient を内部的に使用する Tokens を注入できます。Tokens はアクセストークンを取得し、必要に応じて更新するために利用できます。

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import io.quarkus.oidc.client.Tokens;

@Path("/service")
public class OidcClientResource {

    @Inject Tokens tokens;

    @GET
    public String getResponse() {
        //  Get the access token, which might have been refreshed.
        String accessToken = tokens.getAccessToken();
        // Use the access token to configure MP RestClient Authorization header/etc
    }
}

OidcClients を使用する

io.quarkus.oidc.client.OidcClientsOidcClient インスタンスのコンテナーです。

デフォルトの OidcClient と、次のように設定できる名前付きクライアントが含まれています。

quarkus.oidc-client.client-enabled=false

quarkus.oidc-client.jwt-secret.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.jwt-secret.client-id=quarkus-app
quarkus.oidc-client.jwt-secret.credentials.jwt.secret=AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow

この場合、デフォルトのクライアントは client-enabled=false プロパティーによって無効にされます。jwt-secret クライアントには次のようにアクセスできます。

import org.eclipse.microprofile.rest.client.inject.RestClient;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import io.smallrye.mutiny.Uni;
import io.quarkus.oidc.client.OidcClient;
import io.quarkus.oidc.client.OidcClients;
import io.quarkus.oidc.client.runtime.TokensHelper;

@Path("/clients")
public class OidcClientResource {

    @Inject
    OidcClients clients;
    TokensHelper tokenHelper = new TokensHelper();

    @Inject
    @RestClient
    RestClientWithTokenHeaderParam restClient; (1)

    @GET
    @Path("user-name")
    @Produces("text/plain")
    public Uni<String> getUserName() {
    	OidcClient client = clients.getClient("jwt-secret");
    	return tokenHelper.getTokens(client).onItem()
        		.transformToUni(tokens -> restClient.getUserName("Bearer " + tokens.getAccessToken()));
    }
}
1 OidcClient を直接使用する セクションの RestClientWithTokenHeaderParam 宣言を参照してください。

OIDC マルチテナンシー も使用しており、各 OIDC テナントに独自の OidcClient が関連付けられている場合は、Vert.x RoutingContext tenant-id 属性を使用できます。

次に例を示します:

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import io.quarkus.oidc.client.OidcClient;
import io.quarkus.oidc.client.OidcClients;
import io.vertx.ext.web.RoutingContext;

@Path("/clients")
public class OidcClientResource {

    @Inject
    OidcClients clients;
    @Inject
    RoutingContext context;

    @GET
    public String getResponse() {
        String tenantId = context.get("tenant-id");
        // named OIDC tenant and client configurations use the same key:
        OidcClient client = clients.getClient(tenantId);
        //Use this client to get the token
    }
}

新しい OidcClient をプログラムで作成することもできます。たとえば、起動時に作成する必要があると仮定します。

package org.acme.security.openid.connect.client;

import java.util.Map;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import io.quarkus.oidc.client.OidcClient;
import io.quarkus.oidc.client.runtime.OidcClientConfig;
import io.quarkus.oidc.client.runtime.OidcClientConfig.Grant.Type;
import io.quarkus.oidc.client.OidcClients;
import io.quarkus.runtime.StartupEvent;
import io.smallrye.mutiny.Uni;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;

@ApplicationScoped
public class OidcClientCreator {

    @Inject
    OidcClients oidcClients;
    @ConfigProperty(name = "quarkus.oidc.auth-server-url")
    String oidcProviderAddress;

    private volatile OidcClient oidcClient;

    public void startup(@Observes StartupEvent event) {
    	createOidcClient().subscribe().with(client -> {oidcClient = client;});
    }

    public OidcClient getOidcClient() {
        return oidcClient;
    }

    private Uni<OidcClient> createOidcClient() {
        OidcClientConfig cfg = OidcClientConfig
            .authServerUrl(oidcProviderAddress)
            .id("myclient")
            .clientId("backend-service")
            .credentials("secret")
            .grant(Type.PASSWORD)
            .grantOptions("password", Map.of("username", "alice", "password", "alice"))
            .build();
        return oidcClients.newClient(cfg);
    }
}

これで、このクライアントを次のように使用できます。

import org.eclipse.microprofile.rest.client.inject.RestClient;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import io.smallrye.mutiny.Uni;
import io.quarkus.oidc.client.runtime.TokensHelper;

@Path("/clients")
public class OidcClientResource {

    @Inject
    OidcClientCreator oidcClientCreator;
    TokensHelper tokenHelper = new TokensHelper();

    @Inject
    @RestClient
    RestClientWithTokenHeaderParam restClient; (1)

    @GET
    @Path("user-name")
    @Produces("text/plain")
    public Uni<String> getUserName() {
    	return tokenHelper.getTokens(oidcClientCreator.getOidcClient()).onItem()
        		.transformToUni(tokens -> restClient.getUserName("Bearer " + tokens.getAccessToken()));
    }
}
1 OidcClient を直接使用する セクションの RestClientWithTokenHeaderParam 宣言を参照してください。

名前付き OidcClient とトークンの注入

複数の OidcClient オブジェクトが設定されている場合、 OidcClients を使用する代わりに、 @NamedOidcClient 修飾子で OidcClient 注入ターゲットを指定できます。

package org.acme.security.openid.connect.client;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import io.smallrye.mutiny.Uni;
import io.quarkus.oidc.client.NamedOidcClient;
import io.quarkus.oidc.client.OidcClient;
import io.quarkus.oidc.client.runtime.TokensHelper;

@Path("/clients")
public class OidcClientResource {

    @Inject
    @NamedOidcClient("jwt-secret")
    OidcClient client;

    TokensHelper tokenHelper = new TokensHelper();

    @Inject
    @RestClient
    RestClientWithTokenHeaderParam restClient; (1)

    @GET
    @Path("user-name")
    @Produces("text/plain")
    public Uni<String> getUserName() {
    	return tokenHelper.getTokens(client).onItem()
        		.transformToUni(tokens -> restClient.getUserName("Bearer " + tokens.getAccessToken()));
    }
}
1 OidcClient を直接使用する セクションの RestClientWithTokenHeaderParam 宣言を参照してください。

同じ修飾子を使用して、 Tokens 注入に使用する OidcClient を指定できます。

import java.io.IOException;

import jakarta.annotation.Priority;
import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.Priorities;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.client.ClientRequestFilter;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.ext.Provider;

import io.quarkus.oidc.client.NamedOidcClient;
import io.quarkus.oidc.client.Tokens;

@Provider
@Priority(Priorities.AUTHENTICATION)
@RequestScoped
public class OidcClientRequestCustomFilter implements ClientRequestFilter {

    @Inject
    @NamedOidcClient("jwt-secret")
    Tokens tokens;

    @Override
    public void filter(ClientRequestContext requestContext) throws IOException {
        requestContext.getHeaders().add(HttpHeaders.AUTHORIZATION, "Bearer " + tokens.getAccessToken());
    }
}

RestClient Reactive ClientFilter で OidcClient を使用する

以下の Maven 依存関係を追加します。

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-client-oidc-filter</artifactId>
</dependency>
これにより io.quarkus:quarkus-oidc-client も追加されます。

quarkus-rest-client-oidc-filter エクステンションは io.quarkus.oidc.client.filter.OidcClientRequestReactiveFilter を提供します。

OidcClientRequestFilter と同様に動作します。Use OidcClient in MicroProfile RestClient client filter を参照してください。OidcClient を使用してアクセストークンを取得し、必要に応じて更新し、HTTP Authorization Bearer スキーム値として設定します。

違いは、 Reactive RestClient で動作し、トークンの取得または更新時に現在の IO スレッドをブロックしないノンブロッキングクライアントフィルターを実装している点です。

OidcClientRequestReactiveFilter は、IO スレッドのブロックを避けるため、実行されるまで最初のトークンの取得を遅延させます。

io.quarkus.oidc.client.reactive.filter.OidcClientFilter または org.eclipse.microprofile.rest.client.annotation.RegisterProvider アノテーションを使用して、OidcClientRequestReactiveFilter を選択的に登録できます。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@OidcClientFilter
@Path("/")
public interface ProtectedResourceService {

    @GET
    Uni<String> getUserName();
}

または

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@Path("/")
public interface InformationService {

    @OidcClientFilter
    @GET
    Uni<String> getUserName();

    @OidcClientFilter
    @GET
    Uni<String> getPublicInformation();
}

または

import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.reactive.filter.OidcClientRequestReactiveFilter;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@RegisterProvider(OidcClientRequestReactiveFilter.class)
@Path("/")
public interface ProtectedResourceService {

    @GET
    Uni<String> getUserName();
}

OidcClientRequestReactiveFilter は、デフォルトでデフォルトの OidcClient を使用します。名前付きの OidcClient は、 quarkus.rest-client-oidc-filter.client-name 設定プロパティーで選択できます。 @OidcClientFilter アノテーションの value 属性を設定して OidcClient を選択することもできます。

アノテーションによって設定されたクライアント名は、 quarkus.rest-client-oidc-filter.client-name 設定プロパティーよりも優先されます。

たとえば、この jwt-secret という名前の OIDC クライアント宣言が与えられた場合、このクライアントを次のように参照できます。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@OidcClientFilter("jwt-secret")
@Path("/")
public interface ProtectedResourceService {

    @GET
    Uni<String> getUserName();
}

ProtectedResourceService#getUserName の呼び出しが 401 Unauthorized エラーになった場合に毎回トークンを更新したい場合は、以下の例のように quarkus.rest-client-oidc-filter.refresh-on-unauthorized 設定プロパティーを使用します。

quarkus.rest-client-oidc-filter.refresh-on-unauthorized=true

あるいは、個々のエンドポイントでのみこの機能を有効にする必要がある場合は、以下の例のようにカスタムフィルターを作成します。

package io.quarkus.it.keycloak;

import io.quarkus.oidc.client.reactive.filter.runtime.AbstractOidcClientRequestReactiveFilter;
import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;

@Priority(Priorities.AUTHENTICATION)
public class OidcClientRequestCustomFilter extends AbstractOidcClientRequestReactiveFilter {

    @Override
    protected boolean refreshOnUnauthorized() {
        return true;
    }
}

RestClient ClientFilter で OidcClient を使用する

以下の Maven 依存関係を追加します。

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-client-oidc-filter</artifactId>
</dependency>
これにより io.quarkus:quarkus-oidc-client も追加されます。

quarkus-resteasy-client-oidc-filter エクステンションは、OidcClient を使用してアクセストークンを取得し、必要に応じて更新し、HTTP Authorization Bearer スキーム値として設定する Jakarta REST ClientRequestFilter である io.quarkus.oidc.client.resteasy.filter.OidcClientRequestFilter を提供します。

デフォルトでは、このフィルターは初期化時に OidcClient を取得して、アクセストークンとリフレッシュトークンの最初のペアを取得します。アクセストークンが短命でリフレッシュトークンが利用できない場合は、 quarkus.oidc-client.early-tokens-acquisition=false でトークンの取得を遅延させる必要があります。

io.quarkus.oidc.client.filter.OidcClientFilter または org.eclipse.microprofile.rest.client.annotation.RegisterProvider アノテーションを使用して、OidcClientRequestFilter を選択的に登録できます。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@OidcClientFilter
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

または

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@Path("/")
public interface InformationService {

    @OidcClientFilter
    @GET
    String getUserName();

    @GET
    String getPublicInformation();
}

または

import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.resteasy.filter.OidcClientRequestFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@RegisterProvider(OidcClientRequestFilter.class)
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

あるいは、quarkus.resteasy-client-oidc-filter.register-filter=true プロパティーが設定されている場合、すべての MP Rest または Jakarta REST クライアントで OidcClientRequestFilter を自動的に登録することもできます。

OidcClientRequestFilter は、デフォルトでデフォルトの OidcClient を使用します。名前付きの OidcClient は、 quarkus.resteasy-client-oidc-filter.client-name 設定プロパティーで選択できます。 @OidcClientFilter アノテーションの value 属性を設定して OidcClient を選択することもできます。

アノテーションによって設定されたクライアント名は、 quarkus.resteasy-client-oidc-filter.client-name 設定プロパティーよりも優先されます。

たとえば、この jwt-secret という名前の OIDC クライアント宣言が与えられた場合、このクライアントを次のように参照できます。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@OidcClientFilter("jwt-secret")
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

ProtectedResourceService#getUserName の呼び出しが 401 Unauthorized エラーになった場合に毎回トークンを更新したい場合は、以下の例のように quarkus.resteasy-client-oidc-filter.refresh-on-unauthorized 設定プロパティーを使用します。

quarkus.resteasy-client-oidc-filter.refresh-on-unauthorized=true

あるいは、個々のエンドポイントでのみこの機能を有効にする必要がある場合は、以下の例のようにカスタムフィルターを作成します。

package io.quarkus.it.keycloak;

import io.quarkus.oidc.client.filter.runtime.AbstractOidcClientRequestFilter;
import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;

@Priority(Priorities.AUTHENTICATION)
public class OidcClientRequestCustomFilter extends AbstractOidcClientRequestFilter {

    @Override
    protected boolean refreshOnUnauthorized() {
        return true;
    }
}

カスタムの RestClient ClientFilter を使用する

必要に応じて、独自のカスタムフィルターを使用し、Tokens を注入できます。

import java.io.IOException;
import jakarta.annotation.Priority;
import jakarta.inject.Inject;
import jakarta.ws.rs.Priorities;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.client.ClientRequestFilter;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.ext.Provider;
import io.quarkus.oidc.client.Tokens;

@Provider
@Priority(Priorities.AUTHENTICATION)
public class OidcClientRequestCustomFilter implements ClientRequestFilter {

    @Inject
    Tokens tokens;

    @Override
    public void filter(ClientRequestContext requestContext) throws IOException {
        requestContext.getHeaders().add(HttpHeaders.AUTHORIZATION, "Bearer " + tokens.getAccessToken());
    }
}

Tokens プロデューサーがトークンを取得および更新し、カスタムフィルターがトークンの使用方法とタイミングを決定します。

名前付き Tokens を注入することもできます。名前付き OidcClient とトークンの注入 を参照してください。

アクセストークンの更新

OidcClientRequestReactiveFilterOidcClientRequestFilter、および Tokens プロデューサーは、リフレッシュトークンが利用可能な場合、現在の期限切れアクセストークンを更新します。

さらに、HTTP 401 エラーの原因となる可能性のある期限切れに近いアクセストークンの送信を避けるために、 quarkus.oidc-client.refresh-token-time-skew プロパティーを使用して事前にアクセストークンを更新できます。

たとえば、このプロパティーが 3S に設定されており、アクセストークンが 3 秒未満で期限切れになる場合、トークンは自動的にリフレッシュされます。

デフォルトでは、OIDC クライアントは、トークンが期限切れになったことを検出した場合、または リフレッシュトークンの時間差 が設定されている場合は期限切れに近づいていると検出した場合に、現在のリクエスト中にトークンを更新します。パフォーマンスが重要なアプリケーションでは、受信リクエスト中にトークンの更新を待つことを避け、代わりに非同期トークン更新を設定したい場合があります。

次に例を示します:

quarkus.oidc-client.refresh-interval=1m (1)
1 現在のアクセストークンが期限切れで更新が必要かどうかを毎分確認します。

アクセストークンの更新が必要なのにリフレッシュトークンがない場合は、 client_credentials のように設定されたグラントを使って新しいトークンの取得を試みます。

一部の OpenID Connect プロバイダーは、 client_credentials グラント応答でリフレッシュトークンを返しません。たとえば、Keycloak 12 以降、client_credentials に対してはデフォルトでリフレッシュトークンが返されません。また、プロバイダーはリフレッシュトークンの使用回数を制限している場合があります。

アクセストークンの失効

Keycloak などの OpenID Connect プロバイダーがトークンの失効エンドポイントをサポートしている場合、 OidcClient#revokeAccessToken を使用して現在のアクセストークンを失効させることができます。失効エンドポイントの URL は、トークン要求 URI と共に検出されるか、または quarkus.oidc-client.revoke-path で設定することができます。

このトークンを使用する REST クライアント呼び出しが HTTP 401 ステータスコードで失敗した場合、またはトークンが長期間使用されていて更新したい場合は、アクセストークンを取り消すことができます。

リフレッシュトークンを使ってトークンをリフレッシュすることで、これを行うことができます。ただし、リフレッシュトークンが利用できない場合は、まず現在のアクセストークンを取り消してから、新しいアクセストークンを要求できます。

OidcClient 認証

client_credentials やその他のグラントリクエストが成功するには、OidcClient が OpenID Connect プロバイダーに対して認証する必要があります。すべての OIDC Client Authentication オプションがサポートされています。

次に例を示します:

client_secret_basic :

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=mysecret

または

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.client-secret.value=mysecret

または、CredentialsProvider から取得したシークレットを使用します。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app

# This key is used to retrieve a secret from the map of credentials returned from CredentialsProvider
quarkus.oidc-client.credentials.client-secret.provider.key=mysecret-key
# This is the keyring provided to the CredentialsProvider when looking up the secret, set only if required by the CredentialsProvider implementation
quarkus.oidc.credentials.client-secret.provider.keyring-name=oidc
# Set it only if more than one CredentialsProvider can be registered
quarkus.oidc-client.credentials.client-secret.provider.name=oidc-credentials-provider

client_secret_post :

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.client-secret.value=mysecret
quarkus.oidc-client.credentials.client-secret.method=post

client_secret_jwt、署名アルゴリズムは HS256 です。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.secret=AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow

または、CredentialsProvider から取得したシークレットを使用し、署名アルゴリズムは HS256 です。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app

# This is a key that will be used to retrieve a secret from the map of credentials returned from CredentialsProvider
quarkus.oidc-client.credentials.jwt.secret-provider.key=mysecret-key
# This is the keyring provided to the CredentialsProvider when looking up the secret, set only if required by the CredentialsProvider implementation
quarkus.oidc.credentials.client-secret.provider.keyring-name=oidc
# Set it only if more than one CredentialsProvider can be registered
quarkus.oidc-client.credentials.jwt.secret-provider.name=oidc-credentials-provider

署名アルゴリズムが RS256 で、PEM キーが application.properties にインライン化された private_key_jwt は以下のとおりです。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.key=Base64-encoded private key representation

PEM キーファイルを使用し、署名アルゴリズムが RS256 である private_key_jwt :

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.key-file=privateKey.pem

キーストアファイルを使用し、署名アルゴリズムが RS256 である private_key_jwt :

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.key-store-file=keystore.pkcs12
quarkus.oidc-client.credentials.jwt.key-store-password=mypassword
quarkus.oidc-client.credentials.jwt.key-password=mykeypassword

# Private key alias inside the keystore
quarkus.oidc-client.credentials.jwt.key-id=mykeyAlias

client_secret_jwt または private_key_jwt 認証方法を使用すると、クライアントシークレットがネットワーク経由で送信されることがなくなります。

追加の JWT 認証オプション

client_secret_jwt または private_key_jwt 認証メソッドを使用する場合、JWT 署名アルゴリズム、キー識別子、オーディエンス、サブジェクト、発行者をカスタマイズできます。

次に例を示します:

# private_key_jwt client authentication

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus/
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.key-file=privateKey.pem

# This is a token key identifier 'kid' header - set it if your OpenID Connect provider requires it.
# Note that if the key is represented in a JSON Web Key (JWK) format with a `kid` property, then
# using 'quarkus.oidc-client.credentials.jwt.token-key-id' is unnecessary.
quarkus.oidc-client.credentials.jwt.token-key-id=mykey

# Use the RS512 signature algorithm instead of the default RS256
quarkus.oidc-client.credentials.jwt.signature-algorithm=RS512

# The token endpoint URL is the default audience value; use the base address URL instead:
quarkus.oidc-client.credentials.jwt.audience=${quarkus.oidc-client.auth-server-url}

# custom subject instead of the client ID:
quarkus.oidc-client.credentials.jwt.subject=custom-subject

# custom issuer instead of the client ID:
quarkus.oidc-client.credentials.jwt.issuer=custom-issuer

JWT ベアラー

RFC7523 では、JWT ベアラートークンを使用してクライアントを認証する方法について説明しています。詳細は、クライアント認証での JWT の使用 セクションを参照してください。

次のように有効にします。

quarkus.oidc-client.auth-server-url=${auth-server-url}
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.source=bearer

次に、JWT ベアラートークンを client_assertion パラメーターとして OIDC クライアントに提供します。

Quarkus はファイルシステムから JWT ベアラートークンをロードできます。たとえば、Kubernetes では、サービスアカウントトークンプロジェクションを /var/run/secrets/tokens パスにマウントできます。次に、JWT ベアラートークンパスを次のように設定します。

quarkus.oidc-client.credentials.jwt.token-path=/var/run/secrets/tokens (1)
1 JWT ベアラートークンへのパス。Quarkus はファイルシステムから新しいトークンをロードし、トークンの有効期限が切れると再ロードします。

もう 1 つの選択肢は、追加のグラントパラメーターを受け入れるトークンを取得または更新するために OidcClient メソッドを使用することです。たとえば、 oidcClient.getTokens(Map.of("client_assertion", "ey…​")) を使用します。

OIDC クライアントフィルターを使用する場合は、このアサーションを提供するカスタムフィルターを登録する必要があります。

以下は、Quarkus REST (旧称 RESTEasy Reactive) カスタムフィルターの例です。

package io.quarkus.it.keycloak;

import java.util.Map;

import io.quarkus.oidc.client.reactive.filter.runtime.AbstractOidcClientRequestReactiveFilter;
import io.quarkus.oidc.common.runtime.OidcConstants;
import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;

@Priority(Priorities.AUTHENTICATION)
public class OidcClientRequestCustomFilter extends AbstractOidcClientRequestReactiveFilter {

    @Override
    protected Map<String, String> additionalParameters() {
        return Map.of(OidcConstants.CLIENT_ASSERTION, "ey...");
    }
}

以下は、RESTEasy Classic カスタムフィルターの例です。

package io.quarkus.it.keycloak;

import java.util.Map;

import io.quarkus.oidc.client.filter.runtime.AbstractOidcClientRequestFilter;
import io.quarkus.oidc.common.runtime.OidcConstants;
import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;

@Priority(Priorities.AUTHENTICATION)
public class OidcClientRequestCustomFilter extends AbstractOidcClientRequestFilter {

    @Override
    protected Map<String, String> additionalParameters() {
        return Map.of(OidcConstants.CLIENT_ASSERTION, "ey...");
    }
}

Apple POST JWT

Apple OpenID Connect プロバイダーは client_secret_post メソッドを使用します。ここでシークレットは private_key_jwt 認証方法で生成された JWT ですが、Apple アカウント固有の発行者とサブジェクトプロパティーを使用します。

quarkus-oidc-client は、以下のように設定できる標準外の client_secret_post_jwt 認証方法をサポートしています。

quarkus.oidc-client.auth-server-url=${apple.url}
quarkus.oidc-client.client-id=${apple.client-id}
quarkus.oidc-client.credentials.client-secret.method=post-jwt

quarkus.oidc-client.credentials.jwt.key-file=ecPrivateKey.pem
quarkus.oidc-client.credentials.jwt.signature-algorithm=ES256
quarkus.oidc-client.credentials.jwt.subject=${apple.subject}
quarkus.oidc-client.credentials.jwt.issuer=${apple.issuer}

相互 TLS

一部の OpenID Connect プロバイダーでは、相互 TLS (mTLS) 認証プロセスの一部としてクライアントを認証する必要があります。

quarkus-oidc-client は、以下のように設定することで、 mTLS をサポートすることができます:

quarkus.oidc-client.tls.tls-configuration-name=oidc-client

# configure hostname verification if necessary
#quarkus.tls.oidc-client.hostname-verification-algorithm=NONE

# Keystore configuration
quarkus.tls.oidc-client.key-store.p12.path=client-keystore.p12
quarkus.tls.oidc-client.key-store.p12.password=${key-store-password}

# Add more keystore properties if needed:
#quarkus.tls.oidc-client.key-store.p12.alias=keyAlias
#quarkus.tls.oidc-client.key-store.p12.alias-password=keyAliasPassword

# Truststore configuration
quarkus.tls.oidc-client.trust-store.p12.path=client-truststore.p12
quarkus.tls.oidc-client.trust-store.p12.password=${trust-store-password}
# Add more truststore properties if needed:
#quarkus.tls.oidc-client.trust-store.p12.alias=certAlias

OIDC クライアント SPI

カスタムエクステンションが OIDC クライアントでサポートされているトークングラントの 1 つを使用して OIDC トークンを取得する必要がある場合、エクステンションは OIDC クライアント SPI のみに依存し、必要に応じて OIDC クライアント自体がアクセストークンを取得および更新できるようにします。

  1. 次の依存関係を追加します。

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-oidc-client-spi</artifactId>
    </dependency>
  2. 必要に応じて io.quarkus.oidc.client.spi.TokenProvider CDI Bean を使用するようにエクステンションを更新します。次に例を示します。

    package org.acme.extension;
    
    import jakarta.inject.Inject;
    import io.quarkus.oidc.client.spi.TokenProvider;
    
    public class ExtensionOAuth2Support {
    
       @Inject
       TokenProvider tokenProvider;
    
       public Uni<String> getAccessToken() {
           return tokenProvider.getAccessToken();
       }
    }

    Currently, io.quarkus.oidc.client.spi.TokenProvider is available only for default OIDC clients because custom extensions are unlikely to be aware of multiple named OIDC clients.

テスト

テストプロジェクトに以下の依存関係を追加することから始めます。

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-junit</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.awaitility</groupId>
    <artifactId>awaitility</artifactId>
    <scope>test</scope>
</dependency>

Wiremock

  1. テストプロジェクトに以下の依存関係を追加します。

    <dependency>
        <groupId>org.wiremock</groupId>
        <artifactId>wiremock</artifactId>
        <scope>test</scope>
        <version>${wiremock.version}</version> (1)
    </dependency>
    1 適切な Wiremock バージョンを使用してください。Maven Central で 利用可能なすべての WireMock バージョン を参照してください。
  2. 以下のように、Wiremock ベースの QuarkusTestResourceLifecycleManager を記述します。

    package io.quarkus.it.keycloak;
    
    import static com.github.tomakehurst.wiremock.client.WireMock.matching;
    import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
    
    import java.util.HashMap;
    import java.util.Map;
    
    import com.github.tomakehurst.wiremock.WireMockServer;
    import com.github.tomakehurst.wiremock.client.WireMock;
    import com.github.tomakehurst.wiremock.core.Options.ChunkedEncodingPolicy;
    
    import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
    
    public class KeycloakRealmResourceManager implements QuarkusTestResourceLifecycleManager {
        private WireMockServer server;
    
        @Override
        public Map<String, String> start() {
    
            server = new WireMockServer(wireMockConfig().dynamicPort().useChunkedTransferEncoding(ChunkedEncodingPolicy.NEVER));
            server.start();
    
            server.stubFor(WireMock.post("/tokens")
                    .withRequestBody(matching("grant_type=password&username=alice&password=alice"))
                    .willReturn(WireMock
                            .aResponse()
                            .withHeader("Content-Type", "application/json")
                            .withBody(
                                    "{\"access_token\":\"access_token_1\", \"expires_in\":4, \"refresh_token\":\"refresh_token_1\"}")));
            server.stubFor(WireMock.post("/tokens")
                    .withRequestBody(matching("grant_type=refresh_token&refresh_token=refresh_token_1"))
                    .willReturn(WireMock
                            .aResponse()
                            .withHeader("Content-Type", "application/json")
                            .withBody(
                                    "{\"access_token\":\"access_token_2\", \"expires_in\":4, \"refresh_token\":\"refresh_token_1\"}")));
    
    
            Map<String, String> conf = new HashMap<>();
            conf.put("keycloak.url", server.baseUrl());
            return conf;
        }
    
        @Override
        public synchronized void stop() {
            if (server != null) {
                server.stop();
                server = null;
            }
        }
    }
  3. REST テストエンドポイントを準備します。

    登録された OidcClient フィルターを使用して注入された MP REST クライアントを使用するテストフロントエンドエンドポイントで、ダウンストリームエンドポイントを呼び出すことができます。このエンドポイントはトークンをエコーバックします。たとえば、Quarkus の main リポジトリーにある integration-tests/oidc-client-wiremock を参照してください。

  4. application.properties を次のように設定します。

    # Use the 'keycloak.url' property set by the test KeycloakRealmResourceManager
    quarkus.oidc-client.auth-server-url=${keycloak.url:replaced-by-test-resource}
    quarkus.oidc-client.discovery-enabled=false
    quarkus.oidc-client.token-path=/tokens
    quarkus.oidc-client.client-id=quarkus-service-app
    quarkus.oidc-client.credentials.secret=secret
    quarkus.oidc-client.grant.type=password
    quarkus.oidc-client.grant-options.password.username=alice
    quarkus.oidc-client.grant-options.password.password=alice
  5. テストコードを記述します。

    上記の Wiremock ベースのリソースが与えられた場合、最初のテスト呼び出しでは access_token_1 アクセストークンが返されます。このトークンは 4 秒で期限切れになります。awaitility を使用して約 5 秒間待機します。次のテスト呼び出しでは access_token_2 アクセストークンが返され、期限切れになった access_token_1 アクセストークンが更新されたことを確認できます。

Keycloak

Keycloak を使用する場合は、OpenID Connect ベアラートークンインテグレーションのテスト の Keycloak セクションで説明されているのと同じアプローチを使用できます。

ログでエラーを確認する方法

  1. トークン取得および更新エラーの詳細を確認するには、 io.quarkus.oidc.client.runtime.OidcClientImpl TRACE レベルのロギングを有効にしてください。

    quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientImpl".level=TRACE
    quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientImpl".min-level=TRACE
  2. OidcClient の初期化エラーの詳細を確認するには、 io.quarkus.oidc.client.runtime.OidcClientRecorder TRACE レベルのログを有効にしてください。

    quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientRecorder".level=TRACE
    quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientRecorder".min-level=TRACE

OIDC リクエストフィルター

1 つ以上の OidcRequestFilter 実装を登録することで、OIDC クライアントから OIDC プロバイダーへの OIDC リクエストをフィルター処理できます。これにより、新しいリクエストヘッダーを更新または追加したり、リクエスト本文をカスタマイズまたは分析したりできます。

すべての OIDC プロバイダーエンドポイントへのリクエストをインターセプトする単一のフィルターを設定することも、 @OidcEndpoint アノテーションを使用してこのフィルターを特定のエンドポイントへのリクエストにのみ適用することもできます。

次に例を示します:

package io.quarkus.it.keycloak;

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.arc.Unremovable;
import io.quarkus.oidc.common.OidcEndpoint;
import io.quarkus.oidc.common.OidcEndpoint.Type;
import io.quarkus.oidc.common.OidcRequestFilter;
import io.smallrye.mutiny.Uni;
import io.vertx.core.http.HttpMethod;

@ApplicationScoped
@OidcEndpoint(value = Type.TOKEN)
@Unremovable
public class OidcRequestCustomizer implements OidcRequestFilter {

    @Override
    public Uni<Void> filter(OidcRequestFilterContext requestContext) {
        HttpMethod method = requestContext.request().method();
        String uri = requestContext.request().uri();
        if (method == HttpMethod.POST && uri.endsWith("/token") && requestContext.requestBody() != null) {
            requestContext.request().putHeader("Digest", calculateDigest(requestContext.requestBody().toString()));
        }
        return Uni.createFrom().voidItem();
    }

    private String calculateDigest(String bodyString) {
        // Apply the required digest algorithm to the body string.
        // Implementation details are omitted for brevity.
    }
}

OidcRequestContextProperties を使用してリクエストプロパティーにアクセスできます。現在、 client_id キーを使用してクライアントテナント ID にアクセスし、 grant_type キーを使用して、OIDC クライアントがトークンの取得に使用するグラントタイプにアクセスできます。

OidcRequestFilter は、 String で更新するか、 io.vertx.mutiny.core.buffer.Buffer のインスタンスを準備し、リクエストコンテキストに設定することで、リクエストボディをカスタマイズできます。次に例を示します。

package io.quarkus.it.keycloak;

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.arc.Unremovable;
import io.quarkus.oidc.common.OidcEndpoint;
import io.quarkus.oidc.common.OidcEndpoint.Type;
import io.quarkus.oidc.common.OidcRequestFilter;
import io.smallrye.mutiny.Uni;

@ApplicationScoped
@Unremovable
@OidcEndpoint(value = Type.TOKEN)
public class TokenRequestFilter implements OidcRequestFilter {

    @Override
    public Uni<Void> filter(OidcRequestFilterContext rc) {
        // Add more required properties to the token request
        rc.requestBody(rc.requestBody().toString() + "&opaque_token_param=opaque_token_value"));
        return Uni.createFrom().voidItem();
    }
}

OIDC レスポンスフィルター

1 つ以上の OidcResponseFilter 実装を登録することで、OIDC クライアント要求への応答をフィルタリングできます。これらの実装は、応答ステータス、ヘッダー、および本文をチェックして、それらをログに記録したり、その他のアクションを実行したりできます。

すべての OIDC クライアント要求への応答をインターセプトする単一のフィルターを使用することも、 @OidcEndpoint アノテーションを使用して、このフィルターを特定の OIDC クライアント要求への応答にのみ適用することもできます。

次に例を示します:

package io.quarkus.it.keycloak;

import jakarta.enterprise.context.ApplicationScoped;

import org.jboss.logging.Logger;

import io.quarkus.arc.Unremovable;
import io.quarkus.oidc.common.OidcEndpoint;
import io.quarkus.oidc.common.OidcEndpoint.Type;
import io.quarkus.oidc.common.OidcResponseFilter;
import io.smallrye.mutiny.Uni;
import io.quarkus.oidc.common.runtime.OidcConstants;

@ApplicationScoped
@Unremovable
@OidcEndpoint(value = Type.TOKEN) (1)
public class TokenEndpointResponseFilter implements OidcResponseFilter {
    private static final Logger LOG = Logger.getLogger(TokenEndpointResponseFilter.class);

    @Override
    public Uni<Void> filter(OidcResponseFilterContext rc) {
        String contentType = rc.responseHeaders().get("Content-Type"); (2)
        if (contentType.equals("application/json")
                && "refresh_token".equals(rc.requestProperties().get(OidcConstants.GRANT_TYPE)) (3)
                && rc.responseBody().toJsonObject().containsKey("refresh_token")) { (4)
            LOG.debug("Tokens have been refreshed");
        }
        return Uni.createFrom().voidItem();
    }

}
1 このフィルターを、OIDC トークンエンドポイントのみを対象とするリクエストに制限します。
2 レスポンスの Content-Type ヘッダーを確認します。
3 OidcRequestContextProperties リクエストプロパティーを使用して、それが refresh_grant トークングラント応答であることを確認します。
4 応答 JSON に refresh_token プロパティーが含まれていることを確認します。

OidcResponseFilter は、 io.vertx.mutiny.core.buffer.Buffer のインスタンスを準備し、それを応答コンテキストのプロパティーとして設定することで、応答ボディをカスタマイズできます。次に例を示します。

package io.quarkus.it.keycloak;

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.arc.Unremovable;
import io.quarkus.oidc.common.OidcEndpoint;
import io.quarkus.oidc.common.OidcEndpoint.Type;
import io.quarkus.oidc.common.OidcRequestContextProperties;
import io.quarkus.oidc.common.OidcResponseFilter;
import io.smallrye.mutiny.Uni;
import io.vertx.core.json.JsonObject;
import io.vertx.mutiny.core.buffer.Buffer;

@ApplicationScoped
@Unremovable
@OidcEndpoint(value = Type.TOKEN)
public class TokenResponseFilter implements OidcResponseFilter {

    @Override
    public Uni<Void> filter(OidcResponseFilterContext rc) {
        JsonObject body = rc.responseBody().toJsonObject();
        // JSON `scope` property has multiple values separated by a comma character.
        // It must be replaced with a space character.
        String scope = body.getString("scope");
        body.put("scope", scope.replace(",", " "));
        rc.responseBody(Buffer.buffer(body.toString()));
        return Uni.createFrom().voidItem();
    }
}

Quarkus REST のトークン伝播

quarkus-rest-client-oidc-token-propagation エクステンションは、認証情報の伝播を簡素化する REST クライアントフィルター io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter を提供します。

このフィルターは、現在アクティブなリクエストに存在する ベアラートークン、または 認可コードフローメカニズム から取得したトークンを、HTTP Authorization ヘッダーの Bearer スキーム値として伝播します。

io.quarkus.oidc.token.propagation.common.AccessToken アノテーションまたは org.eclipse.microprofile.rest.client.annotation.RegisterProvider アノテーションのいずれかを使用して、 AccessTokenRequestReactiveFilter を選択的に登録できます。次に例を示します。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.common.AccessToken;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@AccessToken
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

または

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.common.AccessToken;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@Path("/")
public interface InformationService {

    @AccessToken
    @GET
    String getUserName();

    @Path("/public")
    @GET
    String getPublicInformation();
}

または

import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@RegisterProvider(AccessTokenRequestReactiveFilter.class)
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

さらに、 AccessTokenRequestReactiveFilter は、トークンを伝播する前に交換する必要がある複雑なアプリケーションをサポートできます。

Keycloak または Token Exchange トークングラントをサポートする別の OIDC プロバイダーを使用する場合は、次のように AccessTokenRequestReactiveFilter を設定してトークンを交換できます。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
quarkus.oidc-client.grant.type=exchange
quarkus.oidc-client.grant-options.exchange.audience=quarkus-app-exchange

quarkus.rest-client-oidc-token-propagation.exchange-token=true (1)
1 OidcClient 名が io.quarkus.oidc.token.propagation.common.AccessToken#exchangeTokenClient アノテーション属性で設定されている場合、 exchange-token 設定プロパティーは無視されることに注意してください。
AccessTokenRequestReactiveFilterOidcClient を使用して現在のトークンを交換します。また、 quarkus.oidc-client.grant-options.exchange を使用して、OpenID Connect プロバイダーが要求する追加の交換プロパティーを設定できます。

Azure のように、 使用する必要がある JWT ベアラートークングラント を使用して現在のトークンを交換するプロバイダーを使用する場合は、次のように AccessTokenRequestReactiveFilter を設定してトークンを交換できます。

quarkus.oidc-client.auth-server-url=${azure.provider.url}
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret

quarkus.oidc-client.grant.type=jwt
quarkus.oidc-client.grant-options.jwt.requested_token_use=on_behalf_of
quarkus.oidc-client.scopes=https://graph.microsoft.com/user.read,offline_access

quarkus.resteasy-client-oidc-token-propagation.exchange-token=true

AccessTokenRequestReactiveFilter はデフォルトでデフォルトの OidcClient を使用します。名前付き OidcClient は、 quarkus.rest-client-oidc-token-propagation.client-name 設定プロパティーまたは io.quarkus.oidc.token.propagation.common.AccessToken#exchangeTokenClient アノテーション属性を使用して選択できます。

RESTEasy Classic のトークン伝播

quarkus-resteasy-client-oidc-token-propagation エクステンションは、認証情報の伝播を簡素化する 2 つの Jakarta REST jakarta.ws.rs.client.ClientRequestFilter クラス実装を提供します。io.quarkus.oidc.token.propagation.AccessTokenRequestFilter は、HTTP Authorization ヘッダーの Bearer スキーム値として、現在アクティブなリクエストに存在する ベアラートークン または 認可コードフローメカニズム から取得したトークンを伝播します。

io.quarkus.oidc.token.propagation.JsonWebTokenRequestFilter は同じ機能を提供し、さらに JWT トークンもサポートします。

現在の認可コードフローアクセストークンを伝播する必要がある場合、コードフローアクセストークンは (ID トークンとは異なり) 現在認証されているユーザーに代わってリモートサービスにアクセスするために現在の Quarkus エンドポイントに伝播されることを意図しているため、即時トークン伝播がうまく機能します。

ただし、エンドツーエンドの直接的なベアラートークン伝播は避けるべきです。たとえば、 Client → Service A → Service B の場合、 Service BClient から Service A に送信されたトークンを受信します。このような場合、 Service B はトークンが Service A から送信されたのか、直接 Client から送信されたのかを区別できません。Service B で、トークンの送信元が Service A であることを確認するには、新しい発行者とオーディエンスのクレームをアサートできる必要があります。

さらに、複雑なアプリケーションでは、トークンを伝播する前に交換または更新する必要がある場合があります。たとえば、 Service AService B にアクセスするとき、アクセスコンテキストが異なる場合があります。この場合、Service AService B にアクセスするために、狭いスコープまたは完全に異なるスコープのセットを付与される場合があります。

以下のセクションでは、 AccessTokenRequestFilterJsonWebTokenRequestFilter がどのように役立つかを説明します。

RestClient AccessTokenRequestFilter

AccessTokenRequestFilter はすべてのトークンを文字列として扱い、そのため JWT と不透明なトークンの両方で動作できます。

例えば、 io.quarkus.oidc.token.propagation.common.AccessToken または org.eclipse.microprofile.rest.client.annotation.RegisterProvider のどちらかを使用することで、 AccessTokenRequestFilter を選択的に登録することができます。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.common.AccessToken;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@AccessToken
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

または

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.common.AccessToken;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@Path("/")
public interface InformationService {

    @AccessToken
    @GET
    String getUserName();

    @Path("/public")
    @GET
    String getPublicInformation();
}

または

import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.AccessTokenRequestFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@RegisterProvider(AccessTokenRequestFilter.class)
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

あるいは、 quarkus.resteasy-client-oidc-token-propagation.register-filter プロパティーが true に設定され、 quarkus.resteasy-client-oidc-token-propagation.json-web-token プロパティーがデフォルト値である false に設定されている場合、AccessTokenRequestFilter はすべての MP Rest または Jakarta REST クライアントに自動的に登録できます。

伝播前にトークンを交換する

現在のアクセストークンを伝播する前に交換する必要があり、Keycloak または Token Exchange トークングラントをサポートするその他の OpenID Connect プロバイダーを使用する場合は、AccessTokenRequestFilter を次のように設定できます。

quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret
quarkus.oidc-client.grant.type=exchange
quarkus.oidc-client.grant-options.exchange.audience=quarkus-app-exchange

quarkus.resteasy-client-oidc-token-propagation.exchange-token=true

Azure のように、現在のトークンを交換するために JWT ベアラートークングラント使用を要求する プロバイダーを使用する場合、次のように AccessTokenRequestFilter を構成してトークンを交換できます。

quarkus.oidc-client.auth-server-url=${azure.provider.url}
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.secret=secret

quarkus.oidc-client.grant.type=jwt
quarkus.oidc-client.grant-options.jwt.requested_token_use=on_behalf_of
quarkus.oidc-client.scopes=https://graph.microsoft.com/user.read,offline_access

quarkus.resteasy-client-oidc-token-propagation.exchange-token=true
AccessTokenRequestFilterOidcClient を使用して現在のトークンを交換し、 quarkus.oidc-client.grant-options.exchange を使用して、OpenID Connect プロバイダーが要求する追加の交換プロパティーを設定できます。

AccessTokenRequestFilter は、デフォルトでデフォルトの OidcClient を使用します。名前付きの OidcClient は、 quarkus.resteasy-client-oidc-token-propagation.client-name 設定プロパティーで選択できます。

RestClient JsonWebTokenRequestFilter

JsonWebTokenRequestFilter は、issueraudience などのクレームが変更され、更新されたトークンが再署名などの方法で再保護される Bearer JWT トークンを扱う場合に推奨されます。

これは、注入された org.eclipse.microprofile.jwt.JsonWebToken を想定しているため、不透明なトークンでは動作しません。また、OpenID Connect プロバイダーが Token Exchange プロトコルをサポートしている場合は、AccessTokenRequestFilter で JWT と不透明なベアラートークンの両方を安全に交換できるため、代わりに AccessTokenRequestFilter を使用することをお勧めします。

JsonWebTokenRequestFilter を使用すると、 Service A の実装は、注入された org.eclipse.microprofile.jwt.JsonWebToken を新しい issuer および audience のクレーム値で簡単に更新し、更新されたトークンを新しい署名で再保護できます。唯一困難なのは、 Service A が署名キーを持っていることを確認することです。署名キーは、セキュアなファイルシステムまたは Vault などのリモートセキュアストレージからプロビジョニングする必要があります。

たとえば、 io.quarkus.oidc.token.propagation.JsonWebToken または org.eclipse.microprofile.rest.client.annotation.RegisterProvider を使用して、 JsonWebTokenRequestFilter を選択的に登録することが可能です。

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.JsonWebToken;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@JsonWebToken
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

または

import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.JsonWebTokenRequestFilter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@RegisterRestClient
@RegisterProvider(JsonWebTokenRequestFilter.class)
@Path("/")
public interface ProtectedResourceService {

    @GET
    String getUserName();
}

あるいは、quarkus.resteasy-client-oidc-token-propagation.register-filterquarkus.resteasy-client-oidc-token-propagation.json-web-token の両方のプロパティーが true に設定されている場合、JsonWebTokenRequestFilter はすべての MicroProfile REST または Jakarta REST クライアントに自動的に登録できます。

伝播前にトークンを更新する

注入されたトークンの iss (issuer) や aud (audience) のクレームを更新して、新しい署名で保護する必要がある場合は、次のように JsonWebTokenRequestFilter を設定できます。

quarkus.resteasy-client-oidc-token-propagation.secure-json-web-token=true
smallrye.jwt.sign.key.location=/privateKey.pem
# Set a new issuer
smallrye.jwt.new-token.issuer=http://frontend-resource
# Set a new audience
smallrye.jwt.new-token.audience=http://downstream-resource
# Override the existing token issuer and audience claims if they are already set
smallrye.jwt.new-token.override-matching-claims=true

前述のように、Keycloak またはトークン交換プロトコルをサポートする OpenID Connect プロバイダーを使用する場合は、 AccessTokenRequestFilter を使用します。

テスト

通常、2 つの REST テストエンドポイントを準備する必要があります。最初のエンドポイントは、登録済みのトークン伝播フィルターを持つ注入された MP REST クライアントを使用して、2 番目のエンドポイントを呼び出します。

その方法については、OpenID Connect クライアントとトークンの伝播 クイックスタート、特に テスト セクションを参照してください。

GraphQL クライアントインテグレーション

quarkus-oidc-client-graphql エクステンションは、REST クライアントで使用されるアプローチと並行して、OIDC クライアントを GraphQL クライアント に統合する方法を提供します。

このエクステンションがアクティブな場合、ビルダーによってプログラム的にではなくプロパティーを通じて設定された GraphQL クライアントは、OIDC クライアントを使用してアクセストークンを取得し、それを Authorization ヘッダー値として設定します。OIDC クライアントは期限切れのアクセストークンも更新します。

GraphQL クライアントが使用すべき OIDC クライアントを設定するには、 quarkus.oidc-client-graphql.client-name プロパティーで設定済みの OIDC クライアントの 1 つを選択します。次に例を示します。

quarkus.oidc-client-graphql.client-name=oidc-client-for-graphql

# example declaration of the OIDC client itself
quarkus.oidc-client.oidc-client-for-graphql.auth-server-url=${keycloak.url}
quarkus.oidc-client.oidc-client-for-graphql.grant.type=password
quarkus.oidc-client.oidc-client-for-graphql.grant-options.password.username=${username}
quarkus.oidc-client.oidc-client-for-graphql.grant-options.password.password=${password}
quarkus.oidc-client.oidc-client-for-graphql.client-id=${quarkus.oidc.client-id}
quarkus.oidc-client.oidc-client-for-graphql.credentials.client-secret.value=${keycloak.credentials.secret}
quarkus.oidc-client.oidc-client-for-graphql.credentials.client-secret.method=POST

quarkus.oidc-client-graphql.client-name プロパティーを指定しない場合、GraphQL クライアントは明示的な名前なしでデフォルトの OIDC クライアントを使用します。

特に型安全な GraphQL クライアントの場合、 GraphQLClientApi インターフェイスに @io.quarkus.oidc.client.filter.OidcClientFilter アノテーションを付けることで、クライアントごとにこれをオーバーライドできます。

次に例を示します:

@GraphQLClientApi(configKey = "order-client")
@OidcClientFilter("oidc-client-for-graphql")
public interface OrdersGraphQLClient {
    // Queries, mutations, and subscriptions go here.
}

プログラムで作成された GraphQL クライアントでこれを使用するには、VertxDynamicGraphQLClientBuilderVertxTypesafeGraphQLClientBuilder の両方のビルダーに dynamicHeader(String, Uni<String>) メソッドがあり、すべてのリクエストで変更される可能性のあるヘッダーをプラグインできます。

OIDC クライアントをプラグインするには、以下を使用します。

@Inject
OidcClients oidcClients;

VertxDynamicGraphQLClientBuilder builder = ....;
Uni<String> tokenUni = oidcClients.getClient("OIDC_CLIENT_NAME")
    .getTokens().map(t -> "Bearer " + t.getAccessToken());
builder.dynamicHeader("Authorization", tokenUni);
VertxDynamicGraphQLClient client = builder.build();

動的 GraphQL クライアントの場合、 quarkus.oidc-client-graphql."graphql-client".client-name 設定プロパティーを使用して、quarkus.oidc-client-graphql.client-name 設定プロパティーをクライアントごとにオーバーライドできます。

application.properties の例
quarkus.oidc-client-graphql."dynamic-graphql-client-2".client-name=oidc-client-for-graphql-2

# example declaration of the OIDC client itself
quarkus.oidc-client.oidc-client-for-graphql-2.auth-server-url=${keycloak.url}
quarkus.oidc-client.oidc-client-for-graphql-2.grant.type=password
quarkus.oidc-client.oidc-client-for-graphql-2.grant-options.password.username=${username}
quarkus.oidc-client.oidc-client-for-graphql-2.grant-options.password.password=${password}
quarkus.oidc-client.oidc-client-for-graphql-2.client-id=${quarkus.oidc.client-id}
quarkus.oidc-client.oidc-client-for-graphql-2.credentials.client-secret.value=${keycloak.credentials.secret}
quarkus.oidc-client.oidc-client-for-graphql-2.credentials.client-secret.method=POST
動的 GraphQL クライアントの例
@Inject
@GraphQLClient("dynamic-graphql-client-2")
DynamicGraphQLClient dynamicClient;

String dynamicClientAdmin() throws ExecutionException, InterruptedException {
    return dynamicClient.executeSync("query { principalName }").getData().getString("principalName");   (1)
}
1 dynamic-graphql-client-2 GraphQL クライアントの呼び出しには、oidc-client-for-graphql-2 OIDC クライアントによって取得されたアクセストークンを含む Authorization ヘッダーがあります。

ヘルスチェック

quarkus-smallrye-health エクステンションを使用する場合、Quarkus は OIDC クライアントのヘルスチェックを公開できます。

ヘルスチェックは OIDC エンドポイントディスカバリーを使用して接続を検証します。したがって、ディスカバリーを有効にする必要があります。

ヘルスチェックを有効にするには、quarkus.oidc-client.health.enabled を true に設定し、ディスカバリーが無効になっていないことを確認してください:

quarkus.oidc-client.health.enabled=true

設定リファレンス

OIDC クライアント

ビルド時に固定された設定プロパティー - 他のすべての設定プロパティーは実行時にオーバーライド可能

Configuration property

デフォルト

If the OIDC client extension is enabled.

Environment variable: QUARKUS_OIDC_CLIENT_ENABLED

Show more

boolean

true

Whether the OIDC Client extension should automatically register a health check for OIDC clients when a Health Check capability is present.

Environment variable: QUARKUS_OIDC_CLIENT_HEALTH_ENABLED

Show more

boolean

false

quarkus.oidc-client."id".auth-server-url

The base URL of an OpenID Connect (OIDC) server, for example, https://host:port/auth. Do not set this property if you use the public key verification (public-key) or certificate chain verification only (certificate-chain).

By default, when an OIDC configuration metadata discovery is enabled with the discovery-enabled() property, it is retrieved from a well known provider endpoint with its URL calculated by appending a value of the discovery-path() path such as .well-known/openid-configuration to this URL.

For Keycloak, use https://host:port/realms/{realm}, replacing {realm} with the Keycloak realm name.

Environment variable: QUARKUS_OIDC_CLIENT_AUTH_SERVER_URL

Show more

string

quarkus.oidc-client."id".discovery-enabled

Enable discovery of the OIDC endpoints. If not enabled, you must configure the OIDC endpoint URLs individually.

Environment variable: QUARKUS_OIDC_CLIENT_DISCOVERY_ENABLED

Show more

boolean

true

quarkus.oidc-client."id".discovery-path

The relative path of the OIDC discovery endpoint.

Environment variable: QUARKUS_OIDC_CLIENT_DISCOVERY_PATH

Show more

string

.well-known/openid-configuration

quarkus.oidc-client."id".registration-path

The relative path or absolute URL of the OIDC dynamic client registration endpoint. Set if discovery-enabled is false or a discovered token endpoint path must be customized.

Environment variable: QUARKUS_OIDC_CLIENT_REGISTRATION_PATH

Show more

string

quarkus.oidc-client."id".connection-delay

The duration to attempt the initial connection to an OIDC server. For example, setting the duration to 20S allows 10 retries, each 2 seconds apart. This property is only effective when the initial OIDC connection is created. For dropped connections, use the connection-retry-count property instead.

Environment variable: QUARKUS_OIDC_CLIENT_CONNECTION_DELAY

Show more

Duration 

quarkus.oidc-client."id".connection-retry-count

The number of times to retry re-establishing an existing OIDC connection if it is temporarily lost. Different from connection-delay, which applies only to initial connection attempts. For instance, if a request to the OIDC token endpoint fails due to a connection issue, it will be retried as per this setting.

Environment variable: QUARKUS_OIDC_CLIENT_CONNECTION_RETRY_COUNT

Show more

int

3

quarkus.oidc-client."id".connection-timeout

The number of seconds after which the current OIDC connection request times out.

Environment variable: QUARKUS_OIDC_CLIENT_CONNECTION_TIMEOUT

Show more

Duration 

10S

quarkus.oidc-client."id".use-blocking-dns-lookup

Whether DNS lookup should be performed on the worker thread. Use this option when you can see logged warnings about blocked Vert.x event loop by HTTP requests to OIDC server.

Environment variable: QUARKUS_OIDC_CLIENT_USE_BLOCKING_DNS_LOOKUP

Show more

boolean

false

quarkus.oidc-client."id".max-pool-size

The maximum size of the connection pool used by the WebClient.

Environment variable: QUARKUS_OIDC_CLIENT_MAX_POOL_SIZE

Show more

int

quarkus.oidc-client."id".follow-redirects

Follow redirects automatically when WebClient gets HTTP 302. When this property is disabled only a single redirect to exactly the same original URI is allowed but only if one or more cookies were set during the redirect request.

Environment variable: QUARKUS_OIDC_CLIENT_FOLLOW_REDIRECTS

Show more

boolean

true

quarkus.oidc-client."id".token-path

The OIDC token endpoint that issues access and refresh tokens; specified as a relative path or absolute URL. Set if discovery-enabled is false or a discovered token endpoint path must be customized.

Environment variable: QUARKUS_OIDC_CLIENT_TOKEN_PATH

Show more

string

quarkus.oidc-client."id".revoke-path

The relative path or absolute URL of the OIDC token revocation endpoint.

Environment variable: QUARKUS_OIDC_CLIENT_REVOKE_PATH

Show more

string

quarkus.oidc-client."id".client-id

The client id of the application. Each application has a client id that is used to identify the application. Setting the client id is not required if application-type is service and no token introspection is required.

Environment variable: QUARKUS_OIDC_CLIENT_CLIENT_ID

Show more

string

quarkus.oidc-client."id".client-name

The client name of the application. It is meant to represent a human readable description of the application which you may provide when an application (client) is registered in an OpenId Connect provider’s dashboard. For example, you can set this property to have more informative log messages which record an activity of the given client.

Environment variable: QUARKUS_OIDC_CLIENT_CLIENT_NAME

Show more

string

quarkus.oidc-client."id".id

A unique OIDC client identifier. It must be set when OIDC clients are created dynamically and is optional in all other cases.

Environment variable: QUARKUS_OIDC_CLIENT_ID

Show more

string

quarkus.oidc-client."id".client-enabled

If this client configuration is enabled.

Environment variable: QUARKUS_OIDC_CLIENT_CLIENT_ENABLED

Show more

boolean

true

quarkus.oidc-client."id".scopes

List of access token scopes

Environment variable: QUARKUS_OIDC_CLIENT_SCOPES

Show more

文字列のリスト

quarkus.oidc-client."id".audience

List of access token audiences

Environment variable: QUARKUS_OIDC_CLIENT_AUDIENCE

Show more

文字列のリスト

quarkus.oidc-client."id".refresh-token-time-skew

Refresh token time skew. If this property is enabled then the configured duration is converted to seconds and is added to the current time when checking whether the access token should be refreshed. If the sum is greater than this access token’s expiration time then a refresh is going to happen.

Environment variable: QUARKUS_OIDC_CLIENT_REFRESH_TOKEN_TIME_SKEW

Show more

Duration 

quarkus.oidc-client."id".access-token-expires-in

Access token expiration period relative to the current time. This property is only checked when an access token grant response does not include an access token expiration property.

Environment variable: QUARKUS_OIDC_CLIENT_ACCESS_TOKEN_EXPIRES_IN

Show more

Duration 

quarkus.oidc-client."id".access-token-expiry-skew

Access token expiry time skew that can be added to the calculated token expiry time.

Environment variable: QUARKUS_OIDC_CLIENT_ACCESS_TOKEN_EXPIRY_SKEW

Show more

Duration 

quarkus.oidc-client."id".absolute-expires-in

If the access token 'expires_in' property should be checked as an absolute time value as opposed to a duration relative to the current time.

Environment variable: QUARKUS_OIDC_CLIENT_ABSOLUTE_EXPIRES_IN

Show more

boolean

false

quarkus.oidc-client."id".grant.type

Grant type

Environment variable: QUARKUS_OIDC_CLIENT_GRANT_TYPE

Show more

client'client_credentials' grant requiring an OIDC client authentication only, password'password' grant requiring both OIDC client and user ('username' and 'password') authentications, code'authorization_code' grant requiring an OIDC client authentication as well as at least 'code' and 'redirect_uri' parameters which must be passed to OidcClient at the token request time., exchange'urn\:ietf\:params\:oauth\:grant-type\:token-exchange' grant requiring an OIDC client authentication as well as at least 'subject_token' parameter which must be passed to OidcClient at the token request time., jwt'urn\:ietf\:params\:oauth\:grant-type\:jwt-bearer' grant requiring an OIDC client authentication as well as at least an 'assertion' parameter which must be passed to OidcClient at the token request time., refresh'refresh_token' grant requiring an OIDC client authentication and a refresh token. Note, OidcClient supports this grant by default if an access token acquisition response contained a refresh token. However, in some cases, the refresh token is provided out of band, for example, it can be shared between several of the confidential client’s services, etc. If 'quarkus.oidc-client.grant-type' is set to 'refresh' then OidcClient will only support refreshing the tokens., ciba'urn\:openid\:params\:grant-type\:ciba' grant requiring an OIDC client authentication as well as 'auth_req_id' parameter which must be passed to OidcClient at the token request time., device'urn\:ietf\:params\:oauth\:grant-type\:device_code' grant requiring an OIDC client authentication as well as 'device_code' parameter which must be passed to OidcClient at the token request time.

client'client_credentials' grant requiring an OIDC client authentication only

quarkus.oidc-client."id".grant.access-token-property

Access token property name in a token grant response

Environment variable: QUARKUS_OIDC_CLIENT_GRANT_ACCESS_TOKEN_PROPERTY

Show more

string

access_token

quarkus.oidc-client."id".grant.refresh-token-property

Refresh token property name in a token grant response

Environment variable: QUARKUS_OIDC_CLIENT_GRANT_REFRESH_TOKEN_PROPERTY

Show more

string

refresh_token

quarkus.oidc-client."id".grant.expires-in-property

Access token expiry property name in a token grant response

Environment variable: QUARKUS_OIDC_CLIENT_GRANT_EXPIRES_IN_PROPERTY

Show more

string

expires_in

quarkus.oidc-client."id".grant.refresh-expires-in-property

Refresh token expiry property name in a token grant response

Environment variable: QUARKUS_OIDC_CLIENT_GRANT_REFRESH_EXPIRES_IN_PROPERTY

Show more

string

refresh_expires_in

quarkus.oidc-client."id".grant-options."grant-name"

Grant options

Environment variable: QUARKUS_OIDC_CLIENT_GRANT_OPTIONS__GRANT_NAME_

Show more

Map<String,Map<String,String>>

quarkus.oidc-client."id".early-tokens-acquisition

Requires that all filters which use 'OidcClient' acquire the tokens at the post-construct initialization time, possibly long before these tokens are used. This property should be disabled if the access token may expire before it is used for the first time and no refresh token is available.

Environment variable: QUARKUS_OIDC_CLIENT_EARLY_TOKENS_ACQUISITION

Show more

boolean

true

quarkus.oidc-client."id".headers."headers"

Custom HTTP headers which have to be sent to the token endpoint

Environment variable: QUARKUS_OIDC_CLIENT_HEADERS__HEADERS_

Show more

Map<String,String>

quarkus.oidc-client."id".refresh-interval

Token refresh interval. By default, OIDC client refreshes the token during the current request, when it detects that it has expired, or nearly expired if the refresh-token-time-skew() is configured. But, when this property is configured, OIDC client can refresh the token asynchronously in the configured interval. This property is only effective with OIDC client filters and other AbstractTokensProducer extensions, but not when you use the OidcClient#getTokens() API directly.

Environment variable: QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL

Show more

Duration 

HTTP proxy configuration

デフォルト

quarkus.oidc-client."id".proxy.proxy-configuration-name

The name of the proxy configuration to use.

If a name is configured, it uses the configuration from quarkus.proxy.<name>.*. Please note that the 'non-proxy-hosts' option is currently not supported. If a name is configured, but no proxy configuration is found with that name then an error will be thrown.

The default proxy configuration is not used by default.

Environment variable: QUARKUS_OIDC_CLIENT_PROXY_PROXY_CONFIGURATION_NAME

Show more

string

TLS configuration

デフォルト

quarkus.oidc-client."id".tls.tls-configuration-name

The name of the TLS configuration to use.

If a name is configured, it uses the configuration from quarkus.tls.<name>.* If a name is configured, but no TLS configuration is found with that name then an error will be thrown.

The default TLS configuration is not used by default.

Environment variable: QUARKUS_OIDC_CLIENT_TLS_TLS_CONFIGURATION_NAME

Show more

string

Different authentication options for OIDC client to access OIDC token and other secured endpoints

デフォルト

quarkus.oidc-client."id".credentials.secret

The client secret used by the client_secret_basic authentication method. Must be set unless a secret is set in client-secret or jwt client authentication is required. You can use client-secret.value instead, but both properties are mutually exclusive.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_SECRET

Show more

string

quarkus.oidc-client."id".credentials.client-secret.value

The client secret value. This value is ignored if credentials.secret is set. Must be set unless a secret is set in client-secret or jwt client authentication is required.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_CLIENT_SECRET_VALUE

Show more

string

quarkus.oidc-client."id".credentials.client-secret.provider.name

The CredentialsProvider bean name, which should only be set if more than one CredentialsProvider is registered

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_CLIENT_SECRET_PROVIDER_NAME

Show more

string

quarkus.oidc-client."id".credentials.client-secret.provider.keyring-name

The CredentialsProvider keyring name. The keyring name is only required when the CredentialsProvider being used requires the keyring name to look up the secret, which is often the case when a CredentialsProvider is shared by multiple extensions to retrieve credentials from a more dynamic source like a vault instance or secret manager

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_CLIENT_SECRET_PROVIDER_KEYRING_NAME

Show more

string

quarkus.oidc-client."id".credentials.client-secret.provider.key

The CredentialsProvider client secret key

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_CLIENT_SECRET_PROVIDER_KEY

Show more

string

quarkus.oidc-client."id".credentials.client-secret.method

The authentication method. If the clientSecret.value secret is set, this method is basic by default.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_CLIENT_SECRET_METHOD

Show more

basicclient_secret_basic (default)\: The client id and secret are submitted with the HTTP Authorization Basic scheme., postclient_secret_post\: The client id and secret are submitted as the client_id and client_secret form parameters., post-jwtclient_secret_jwt\: The client id and generated JWT secret are submitted as the client_id and client_secret form parameters., queryclient id and secret are submitted as HTTP query parameters. This option is only supported by the OIDC extension.

quarkus.oidc-client."id".credentials.jwt.source

JWT token source: OIDC provider client or an existing JWT bearer token.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SOURCE

Show more

clientJWT token is generated by the OIDC provider client to support client_secret_jwt and private_key_jwt authentication methods., bearerJWT bearer token is used as a client assertion\: https\://www.rfc-editor.org/rfc/rfc7523#section-2.2.

clientJWT token is generated by the OIDC provider client to support client_secret_jwt and private_key_jwt authentication methods.

quarkus.oidc-client."id".credentials.jwt.token-path

Path to a file with a JWT bearer token that should be used as a client assertion. This path can only be set when JWT source (source()) is set to Source#BEARER.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_TOKEN_PATH

Show more

path

quarkus.oidc-client."id".credentials.jwt.secret

If provided, indicates that JWT is signed using a secret key. It is mutually exclusive with key, key-file and key-store properties.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SECRET

Show more

string

quarkus.oidc-client."id".credentials.jwt.secret-provider.name

The CredentialsProvider bean name, which should only be set if more than one CredentialsProvider is registered

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SECRET_PROVIDER_NAME

Show more

string

quarkus.oidc-client."id".credentials.jwt.secret-provider.keyring-name

The CredentialsProvider keyring name. The keyring name is only required when the CredentialsProvider being used requires the keyring name to look up the secret, which is often the case when a CredentialsProvider is shared by multiple extensions to retrieve credentials from a more dynamic source like a vault instance or secret manager

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SECRET_PROVIDER_KEYRING_NAME

Show more

string

quarkus.oidc-client."id".credentials.jwt.secret-provider.key

The CredentialsProvider client secret key

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SECRET_PROVIDER_KEY

Show more

string

quarkus.oidc-client."id".credentials.jwt.key

String representation of a private key. If provided, indicates that JWT is signed using a private key in PEM or JWK format. It is mutually exclusive with secret, key-file and key-store properties. You can use the signature-algorithm property to override the default key algorithm, RS256.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEY

Show more

string

quarkus.oidc-client."id".credentials.jwt.key-file

If provided, indicates that JWT is signed using a private key in PEM or JWK format. It is mutually exclusive with secret, key and key-store properties. You can use the signature-algorithm property to override the default key algorithm, RS256.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEY_FILE

Show more

string

quarkus.oidc-client."id".credentials.jwt.key-store-file

If provided, indicates that JWT is signed using a private key from a keystore. It is mutually exclusive with secret, key and key-file properties.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEY_STORE_FILE

Show more

string

quarkus.oidc-client."id".credentials.jwt.key-store-password

A parameter to specify the password of the keystore file.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEY_STORE_PASSWORD

Show more

string

quarkus.oidc-client."id".credentials.jwt.key-id

The private key id or alias.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEY_ID

Show more

string

quarkus.oidc-client."id".credentials.jwt.key-password

The private key password.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEY_PASSWORD

Show more

string

quarkus.oidc-client."id".credentials.jwt.audience

The JWT audience (aud) claim value. By default, the audience is set to the address of the OpenId Connect Provider’s token endpoint.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_AUDIENCE

Show more

string

quarkus.oidc-client."id".credentials.jwt.keep-audience-trailing-slash

Whether to keep a trailing slash / in the audience() value.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_KEEP_AUDIENCE_TRAILING_SLASH

Show more

boolean

false

quarkus.oidc-client."id".credentials.jwt.token-key-id

The key identifier of the signing key added as a JWT kid header.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_TOKEN_KEY_ID

Show more

string

quarkus.oidc-client."id".credentials.jwt.issuer

The issuer of the signing key added as a JWT iss claim. The default value is the client id.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_ISSUER

Show more

string

quarkus.oidc-client."id".credentials.jwt.subject

Subject of the signing key added as a JWT sub claim The default value is the client id.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SUBJECT

Show more

string

quarkus.oidc-client."id".credentials.jwt.claims."claim-name"

Additional claims.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_CLAIMS__CLAIM_NAME_

Show more

Map<String,String>

quarkus.oidc-client."id".credentials.jwt.signature-algorithm

The signature algorithm used for the key-file property. Supported values: RS256 (default), RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_SIGNATURE_ALGORITHM

Show more

string

quarkus.oidc-client."id".credentials.jwt.lifespan

The JWT lifespan in seconds. This value is added to the time at which the JWT was issued to calculate the expiration time.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_LIFESPAN

Show more

int

10

quarkus.oidc-client."id".credentials.jwt.assertion

If true then the client authentication token is a JWT bearer grant assertion. Instead of producing 'client_assertion' and 'client_assertion_type' form properties, only 'assertion' is produced. This option is only supported by the OIDC client extension.

Environment variable: QUARKUS_OIDC_CLIENT_CREDENTIALS_JWT_ASSERTION

Show more

boolean

false

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。 詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます:

  • 数値の後に hms が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

OIDC トークンの伝播

ビルド時に固定された設定プロパティー - 他のすべての設定プロパティーは実行時にオーバーライド可能

Configuration property

タイプ

デフォルト

If the OIDC Token Reactive Propagation is enabled.

Environment variable: QUARKUS_REST_CLIENT_OIDC_TOKEN_PROPAGATION_ENABLED

Show more

ブーリアン

true

Whether the token propagation is enabled during the SecurityIdentity augmentation.

For example, you may need to use a REST client from SecurityIdentityAugmentor to propagate the current token to acquire additional roles for the SecurityIdentity.

Note, this feature relies on a duplicated context. More information about Vert.x duplicated context can be found in this guide.

Environment variable: QUARKUS_REST_CLIENT_OIDC_TOKEN_PROPAGATION_ENABLED_DURING_AUTHENTICATION

Show more

ブーリアン

false

Exchange the current token with OpenId Connect Provider for a new token using either "urn:ietf:params:oauth:grant-type:token-exchange" or "urn:ietf:params:oauth:grant-type:jwt-bearer" token grant before propagating it.

Environment variable: QUARKUS_REST_CLIENT_OIDC_TOKEN_PROPAGATION_EXCHANGE_TOKEN

Show more

ブーリアン

false

Name of the configured OidcClient. Note this property is only used if the exchangeToken property is enabled.

Environment variable: QUARKUS_REST_CLIENT_OIDC_TOKEN_PROPAGATION_CLIENT_NAME

Show more

string

関連コンテンツ