OpenID Connect (OIDC) and OAuth2 client and filters
You can use Quarkus extensions for OpenID Connect and OAuth 2.0 access token management, focusing on acquiring, refreshing, and propagating tokens.
This includes the following:
-
Using
quarkus-oidc-client
,quarkus-rest-client-oidc-filter
andquarkus-resteasy-client-oidc-filter
extensions to acquire and refresh access tokens from OpenID Connect and OAuth 2.0 compliant Authorization Servers such as Keycloak. -
Using
quarkus-rest-client-oidc-token-propagation
andquarkus-resteasy-client-oidc-token-propagation
extensions to propagate the currentBearer
orAuthorization Code Flow
access tokens.
The access tokens managed by these extensions can be used as HTTP Authorization Bearer tokens to access the remote services.
OidcClient
添加以下依赖关系:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-oidc-client</artifactId>
</dependency>
The quarkus-oidc-client
extension provides a reactive io.quarkus.oidc.client.OidcClient
, which can be used to acquire and refresh tokens using SmallRye Mutiny Uni
and Vert.x WebClient
.
OidcClient
is initialized at build time with the IDP token endpoint URL, which can be auto-discovered or manually configured. OidcClient
uses this endpoint to acquire access tokens by using token grants such as client_credentials
or password
and refresh the tokens by using a refresh_token
grant.
Token endpoint configuration
By default, the token endpoint address is discovered by adding a /.well-known/openid-configuration
path to the configured quarkus.oidc-client.auth-server-url
.
For example, given this Keycloak URL:
quarkus.oidc-client.auth-server-url=http://localhost:8180/auth/realms/quarkus
OidcClient
will discover that the token endpoint URL is http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/tokens
.
Alternatively, if the discovery endpoint is unavailable or you want to save on the discovery endpoint round-trip, you can disable the discovery and configure the token endpoint address with a relative path value. For example:
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
A more compact way to configure the token endpoint URL without the discovery is to set quarkus.oidc-client.token-path
to an absolute URL:
quarkus.oidc-client.token-path=http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/tokens
Setting quarkus.oidc-client.auth-server-url
and quarkus.oidc-client.discovery-enabled
is not required in this case.
Supported token grants
The main token grants that OidcClient
can use to acquire the tokens are the client_credentials
(default) and password
grants.
Client credentials grant
Here is how OidcClient
can be configured to use the client_credentials
grant:
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
The client_credentials
grant allows setting extra parameters for the token request by using quarkus.oidc-client.grant-options.client.<param-name>=<value>
. Here is how to set the intended token recipient by using the audience
parameter:
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
Password grant
Here is how OidcClient
can be configured to use the password
grant:
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
It can be further customized by using a quarkus.oidc-client.grant-options.password
configuration prefix, similar to how the client credentials grant can be customized.
Other grants
OidcClient
can also help acquire the tokens by using grants that require some extra input parameters that cannot be captured in the configuration. These grants are refresh_token
(with the external refresh token), authorization_code
, and two grants which can be used to exchange the current access token, namely, urn:ietf:params:oauth:grant-type:token-exchange
and urn:ietf:params:oauth:grant-type:jwt-bearer
.
If you need to acquire an access token and have posted an existing refresh token to the current Quarkus endpoint, you must use the refresh_token
grant. This grant employs an out-of-band refresh token to obtain a new token set.
In this case, configure OidcClient
as follows:
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
Then you can use the OidcClient.refreshTokens
method with a provided refresh token to get the access token.
Using the urn:ietf:params:oauth:grant-type:token-exchange
or urn:ietf:params:oauth:grant-type:jwt-bearer
grants might be required if you are building a complex microservices application and want to avoid the same Bearer
token be propagated to and used by more than one service. See Token Propagation for Quarkus REST and Token Propagation for RESTEasy Classic for more details.
Using OidcClient
to support the authorization code
grant might be required if, for some reason, you cannot use the Quarkus OIDC extension to support Authorization Code Flow. If there is a very good reason for you to implement Authorization Code Flow, then you can configure OidcClient
as follows:
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
Then, you can use the OidcClient.accessTokens
method to accept a Map of extra properties and pass the current code
and redirect_uri
parameters to exchange the authorization code for the tokens.
OidcClient
also supports the urn:openid:params:grant-type:ciba
grant:
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
Then, you can use the OidcClient.accessTokens
method to accept a Map of extra properties and pass the auth_req_id
parameter to exchange the token authorization code.
Use OidcClient directly
You can use OidcClient
directly to acquire access tokens and set them in an HTTP Authorization
header as a Bearer
scheme value.
For example, let’s assume the Quarkus endpoint has to access a microservice that returns a user name. First, create a REST client:
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);
}
Now, use OidcClient
to acquire the tokens and propagate them:
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 manages the access token acquisition and refresh. |
Inject tokens
You can inject Tokens
that use OidcClient
internally. Tokens
can be used to acquire the access tokens and refresh them if necessary:
import jakarta.inject.PostConstruct;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
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
}
}
Use OidcClients
io.quarkus.oidc.client.OidcClients
is a container of OidcClient
s - it includes a default OidcClient
and named clients which can be configured like this:
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
In this case, the default client is disabled with a client-enabled=false
property. The jwt-secret
client can be accessed like this:
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
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 | See the RestClientWithTokenHeaderParam declaration in the Use OidcClient directly section. |
If you also use OIDC multitenancy, and each OIDC tenant has its own associated
|
You can also create a new OidcClient
programmatically.
For example, let’s assume you must create it at startup time:
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.OidcClientConfig;
import io.quarkus.oidc.client.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 = new OidcClientConfig();
cfg.setId("myclient");
cfg.setAuthServerUrl(oidcProviderAddress);
cfg.setClientId("backend-service");
cfg.getCredentials().setSecret("secret");
cfg.getGrant().setType(Type.PASSWORD);
cfg.setGrantOptions(Map.of("password",
Map.of("username", "alice", "password", "alice")));
return oidcClients.newClient(cfg);
}
}
Now, you can use this client like this:
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
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 | See the RestClientWithTokenHeaderParam declaration in the Use OidcClient directly section. |
Inject named OidcClient and tokens
In case of multiple configured OidcClient
objects, you can specify the OidcClient
injection target by the extra qualifier @NamedOidcClient
instead of working with OidcClients
:
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 io.smallrye.mutiny.Uni;
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 | See the RestClientWithTokenHeaderParam declaration in the Use OidcClient directly section. |
The same qualifier can be used to specify the OidcClient
used for a Tokens
injection:
@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());
}
}
Use OidcClient in RestClient Reactive ClientFilter
Add the following Maven Dependency:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-client-oidc-filter</artifactId>
</dependency>
Note it will also bring io.quarkus:quarkus-oidc-client
.
quarkus-rest-client-oidc-filter
extension provides io.quarkus.oidc.client.filter.OidcClientRequestReactiveFilter
.
It works similarly to the way OidcClientRequestFilter
does (see Use OidcClient in MicroProfile RestClient client filter) - it uses OidcClient
to acquire the access token, refresh it if needed, and set it as an HTTP Authorization
Bearer
scheme value. The difference is that it works with Reactive RestClient and implements a non-blocking client filter that does not block the current IO thread when acquiring or refreshing the tokens.
OidcClientRequestReactiveFilter
delays an initial token acquisition until it is executed to avoid blocking an IO thread.
You can selectively register OidcClientRequestReactiveFilter
by using either io.quarkus.oidc.client.reactive.filter.OidcClientFilter
or org.eclipse.microprofile.rest.client.annotation.RegisterProvider
annotations:
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import io.smallrye.mutiny.Uni;
@RegisterRestClient
@OidcClientFilter
@Path("/")
public interface ProtectedResourceService {
@GET
Uni<String> getUserName();
}
or
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;
@RegisterRestClient
@RegisterProvider(OidcClientRequestReactiveFilter.class)
@Path("/")
public interface ProtectedResourceService {
@GET
Uni<String> getUserName();
}
OidcClientRequestReactiveFilter
uses a default OidcClient
by default. A named OidcClient
can be selected with a quarkus.rest-client-oidc-filter.client-name
configuration property.
You can also select OidcClient
by setting the value
attribute of the @OidcClientFilter
annotation. The client name set through annotation has higher priority than the quarkus.rest-client-oidc-filter.client-name
configuration property.
For example, given this jwt-secret
named OIDC client declaration, you can refer to this client like this:
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
import io.smallrye.mutiny.Uni;
@RegisterRestClient
@OidcClientFilter("jwt-secret")
@Path("/")
public interface ProtectedResourceService {
@GET
Uni<String> getUserName();
}
Use OidcClient in RestClient ClientFilter
Add the following Maven Dependency:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-client-oidc-filter</artifactId>
</dependency>
Note it will also bring io.quarkus:quarkus-oidc-client
.
quarkus-resteasy-client-oidc-filter
extension provides io.quarkus.oidc.client.filter.OidcClientRequestFilter
Jakarta REST ClientRequestFilter which uses OidcClient
to acquire the access token, refresh it if needed, and set it as an HTTP Authorization
Bearer
scheme value.
By default, this filter will get OidcClient
to acquire the first pair of access and refresh tokens at its initialization time. If the access tokens are short-lived and refresh tokens are unavailable, then the token acquisition should be delayed with quarkus.oidc-client.early-tokens-acquisition=false
.
You can selectively register OidcClientRequestFilter
by using either io.quarkus.oidc.client.filter.OidcClientFilter
or org.eclipse.microprofile.rest.client.annotation.RegisterProvider
annotations:
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
@RegisterRestClient
@OidcClientFilter
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
or
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientRequestFilter;
@RegisterRestClient
@RegisterProvider(OidcClientRequestFilter.class)
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
Alternatively, OidcClientRequestFilter
can be registered automatically with all MP Rest or Jakarta REST clients if the quarkus.resteasy-client-oidc-filter.register-filter=true
property is set.
OidcClientRequestFilter
uses a default OidcClient
by default. A named OidcClient
can be selected with a quarkus.resteasy-client-oidc-filter.client-name
configuration property.
You can also select OidcClient
by setting the value
attribute of the @OidcClientFilter
annotation. The client name set through annotation has higher priority than the quarkus.resteasy-client-oidc-filter.client-name
configuration property.
For example, given this jwt-secret
named OIDC client declaration, you can refer to this client like this:
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.client.filter.OidcClientFilter;
@RegisterRestClient
@OidcClientFilter("jwt-secret")
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
Use a custom RestClient ClientFilter
If you prefer, you can use your own custom filter and inject Tokens
:
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());
}
}
The Tokens
producer will acquire and refresh the tokens, and the custom filter will decide how and when to use the token.
You can also inject named Tokens
, see Inject named OidcClient and Tokens
Refreshing access tokens
OidcClientRequestReactiveFilter
, OidcClientRequestFilter
and Tokens
producers will refresh the current expired access token if the refresh token is available.
Additionally, the quarkus.oidc-client.refresh-token-time-skew
property can be used for a preemptive access token refreshment to avoid sending nearly expired access tokens that might cause HTTP 401 errors. For example, if this property is set to 3S
and the access token will expire in less than 3 seconds, then this token will be auto-refreshed.
If the access token needs to be refreshed, but no refresh token is available, then an attempt is made to acquire a new token by using a configured grant, such as client_credentials
.
Some OpenID Connect Providers will not return a refresh token in a client_credentials
grant response. For example, starting from Keycloak 12, a refresh token will not be returned by default for client_credentials
. The providers might also restrict the number of times a refresh token can be used.
Revoking access tokens
If your OpenId Connect provider, such as Keycloak, supports a token revocation endpoint, then OidcClient#revokeAccessToken
can be used to revoke the current access token. The revocation endpoint URL will be discovered alongside the token request URI or can be configured with quarkus.oidc-client.revoke-path
.
You might want to have the access token revoked if using this token with a REST client fails with an HTTP 401
status code or if the access token has already been used for a long time and you would like to refresh it.
This can be achieved by requesting a token refresh by using a refresh token. However, if the refresh token is unavailable, you can refresh it by revoking it first and then requesting a new access token.
OidcClient authentication
OidcClient
has to authenticate to the OpenID Connect Provider for the client_credentials
and other grant requests to succeed.
All the OIDC Client Authentication options are supported, for example:
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
or
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
Or with the secret retrieved from a 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
, signature algorithm is 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
Or with the secret retrieved from a CredentialsProvider, signature algorithm is 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
private_key_jwt
with the PEM key inlined in application.properties, and where the signature algorithm is RS256
:
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
private_key_jwt
with the PEM key file, signature algorithm is RS256
:
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
private_key_jwt
with the keystore file, signature algorithm is RS256
:
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.jks
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
Using client_secret_jwt
or private_key_jwt
authentication methods ensures that no client secret goes over the wire.
Additional JWT authentication options
If either client_secret_jwt
or private_key_jwt
authentication methods are used, then the JWT signature algorithm, key identifier, audience, subject, and issuer can be customized, for example:
# 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 Bearer
RFC7523 explains how JWT Bearer tokens can be used to authenticate clients, see the Using JWTs for Client Authentication section for more information.
It can be enabled as follows:
quarkus.oidc-client.auth-server-url=${auth-server-url}
quarkus.oidc-client.client-id=quarkus-app
quarkus.oidc-client.credentials.jwt.source=bearer
Next, the JWT bearer token must be provided as a client_assertion
parameter to the OIDC client.
You can use OidcClient
methods for acquiring or refreshing tokens which accept additional grant parameters, for example, oidcClient.getTokens(Map.of("client_assertion", "ey…"))
.
If you work work with the OIDC client filters then you must register a custom filter which will provide this assertion.
Here is an example of the Quarkus REST (formerly RESTEasy Reactive) custom filter:
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...");
}
}
Here is an example of the RestEasy Classic custom filter:
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 Provider uses a client_secret_post
method where a secret is a JWT produced with a private_key_jwt
authentication method but with Apple account-specific issuer and subject properties.
quarkus-oidc-client
supports a non-standard client_secret_post_jwt
authentication method, which can be configured as follows:
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}
Mutual TLS
Some OpenID Connect Providers require that a client is authenticated as part of the mutual TLS (mTLS
) authentication process.
quarkus-oidc-client
can be configured as follows to support mTLS
:
quarkus.oidc-client.tls.verification=certificate-validation
# Keystore configuration
quarkus.oidc-client.tls.key-store-file=client-keystore.jks
quarkus.oidc-client.tls.key-store-password=${key-store-password}
# Add more keystore properties if needed:
#quarkus.oidc-client.tls.key-store-alias=keyAlias
#quarkus.oidc-client.tls.key-store-alias-password=keyAliasPassword
# Truststore configuration
quarkus.oidc-client.tls.trust-store-file=client-truststore.jks
quarkus.oidc-client.tls.trust-store-password=${trust-store-password}
# Add more truststore properties if needed:
#quarkus.oidc-client.tls.trust-store-alias=certAlias
测试
首先在你的测试项目中添加以下依赖项:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-junit5</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.awaitility</groupId>
<artifactId>awaitility</artifactId>
<scope>test</scope>
</dependency>
Wiremock
在你的测试项目中添加以下依赖项:
<dependency>
<groupId>org.wiremock</groupId>
<artifactId>wiremock</artifactId>
<scope>test</scope>
</dependency>
Write a Wiremock-based QuarkusTestResourceLifecycleManager
, for example:
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;
}
}
}
Prepare the REST test endpoints. You can have the test front-end endpoint, which uses the injected MP REST client with a registered OidcClient filter, call the downstream endpoint. This endpoint echoes the token back. For example, see the integration-tests/oidc-client-wiremock
in the main
Quarkus repository.
Set application.properties
, for example:
# 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
And finally, write the test code. Given the Wiremock-based resource above, the first test invocation should return the access_token_1
access token, which will expire in 4 seconds. Use awaitility
to wait for about 5 seconds, and now the next test invocation should return the access_token_2
access token, which confirms the expired access_token_1
access token has been refreshed.
Keycloak
If you work with Keycloak, you can use the same approach described in the OpenID Connect Bearer Token Integration testing Keycloak section.
如何检查日志中的错误
Enable io.quarkus.oidc.client.runtime.OidcClientImpl
TRACE
level logging to see more details about the token acquisition and refresh errors:
quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientImpl".level=TRACE
quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientImpl".min-level=TRACE
Enable io.quarkus.oidc.client.runtime.OidcClientRecorder
TRACE
level logging to see more details about the OidcClient initialization errors:
quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientRecorder".level=TRACE
quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientRecorder".min-level=TRACE
OIDC request filters
You can filter OIDC requests made by Quarkus to the OIDC provider by registering one or more OidcRequestFilter
implementations, which can update or add new request headers. For example, a filter can analyze the request body and add its digest as a new header value:
package io.quarkus.it.keycloak;
import jakarta.enterprise.context.ApplicationScoped;
import io.quarkus.arc.Unremovable;
import io.quarkus.oidc.common.OidcRequestContextProperties;
import io.quarkus.oidc.common.OidcRequestFilter;
import io.vertx.core.http.HttpMethod;
import io.vertx.mutiny.core.buffer.Buffer;
import io.vertx.mutiny.ext.web.client.HttpRequest;
@ApplicationScoped
@Unremovable
public class OidcRequestCustomizer implements OidcRequestFilter {
@Override
public void filter(HttpRequest<Buffer> request, Buffer buffer, OidcRequestContextProperties contextProperties) {
HttpMethod method = request.method();
String uri = request.uri();
if (method == HttpMethod.POST && uri.endsWith("/service") && buffer != null) {
request.putHeader("Digest", calculateDigest(buffer.toString()));
}
}
private String calculateDigest(String bodyString) {
// Apply the required digest algorithm to the body string
}
}
Token Propagation for Quarkus REST
The quarkus-rest-client-oidc-token-propagation
extension provides a REST Client filter, io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter
, that simplifies the propagation of authentication information. This client propagates the bearer token present in the currently active request or the token acquired from the authorization code flow mechanism as the HTTP Authorization
header’s Bearer
scheme value.
You can selectively register AccessTokenRequestReactiveFilter
by using either io.quarkus.oidc.token.propagation.AccessToken
or org.eclipse.microprofile.rest.client.annotation.RegisterProvider
annotation, for example:
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.AccessToken;
@RegisterRestClient
@AccessToken
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
or
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.reactive.AccessTokenRequestReactiveFilter;
@RegisterRestClient
@RegisterProvider(AccessTokenRequestReactiveFilter.class)
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
Additionally, AccessTokenRequestReactiveFilter
can support a complex application that needs to exchange the tokens before propagating them.
If you work with Keycloak or another OIDC provider that supports a Token Exchange token grant, then you can configure AccessTokenRequestReactiveFilter
to exchange the token like this:
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 (1)
1 | Please note that the exchange-token configuration property is ignored when the OidcClient name is set with the io.quarkus.oidc.token.propagation.AccessToken#exchangeTokenClient annotation attribute. |
Note AccessTokenRequestReactiveFilter
will use OidcClient
to exchange the current token, and you can use quarkus.oidc-client.grant-options.exchange
to set the additional exchange properties expected by your OpenID Connect Provider.
If you work with providers such as Azure
that require using JWT bearer token grant to exchange the current token, then you can configure AccessTokenRequestReactiveFilter
to exchange the token like this:
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
uses a default OidcClient
by default. A named OidcClient
can be selected with a quarkus.rest-client-oidc-token-propagation.client-name
configuration property or with the io.quarkus.oidc.token.propagation.AccessToken#exchangeTokenClient
annotation attribute.
Token Propagation for RESTEasy Classic
The quarkus-resteasy-client-oidc-token-propagation
extension provides two Jakarta REST jakarta.ws.rs.client.ClientRequestFilter
class implementations that simplify the propagation of authentication information.
io.quarkus.oidc.token.propagation.AccessTokenRequestFilter
propagates the Bearer token present in the current active request or the token acquired from the Authorization code flow mechanism, as the HTTP Authorization
header’s Bearer
scheme value.
The io.quarkus.oidc.token.propagation.JsonWebTokenRequestFilter
provides the same functionality but, in addition, provides support for JWT tokens.
When you need to propagate the current Authorization Code Flow access token, then the immediate token propagation will work well - as the code flow access tokens (as opposed to ID tokens) are meant to be propagated for the current Quarkus endpoint to access the remote services on behalf of the currently authenticated user.
However, the direct end-to-end Bearer token propagation should be avoided. For example, Client → Service A → Service B
where Service B
receives a token sent by Client
to Service A
. In such cases, Service B
cannot distinguish if the token came from Service A
or from Client
directly. For Service B
to verify the token came from Service A
, it should be able to assert a new issuer and audience claims.
Additionally, a complex application might need to exchange or update the tokens before propagating them. For example, the access context might be different when Service A
is accessing Service B
. In this case, Service A
might be granted a narrow or completely different set of scopes to access Service B
.
The following sections show how AccessTokenRequestFilter
and JsonWebTokenRequestFilter
can help.
RestClient AccessTokenRequestFilter
AccessTokenRequestFilter
treats all tokens as Strings, and as such, it can work with both JWT and opaque tokens.
You can selectively register AccessTokenRequestFilter
by using either io.quarkus.oidc.token.propagation.AccessToken
or org.eclipse.microprofile.rest.client.annotation.RegisterProvider
, for example:
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.AccessToken;
@RegisterRestClient
@AccessToken
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
or
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.AccessTokenRequestFilter;
@RegisterRestClient
@RegisterProvider(AccessTokenRequestFilter.class)
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
Alternatively, AccessTokenRequestFilter
can be registered automatically with all MP Rest or Jakarta REST clients if the quarkus.resteasy-client-oidc-token-propagation.register-filter
property is set to true
and quarkus.resteasy-client-oidc-token-propagation.json-web-token
property is set to false
(which is a default value).
Exchange token before propagation
If the current access token needs to be exchanged before propagation and you work with Keycloak or other OpenID Connect Provider which supports a Token Exchange token grant, then you can configure AccessTokenRequestFilter
like this:
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
If you work with providers such as Azure
that require using JWT bearer token grant to exchange the current token, then you can configure AccessTokenRequestFilter
to exchange the token like this:
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
Note AccessTokenRequestFilter
will use OidcClient
to exchange the current token, and you can use quarkus.oidc-client.grant-options.exchange
to set the additional exchange properties expected by your OpenID Connect Provider.
AccessTokenRequestFilter
uses a default OidcClient
by default. A named OidcClient
can be selected with a quarkus.resteasy-client-oidc-token-propagation.client-name
configuration property.
RestClient JsonWebTokenRequestFilter
Using JsonWebTokenRequestFilter
is recommended if you work with Bearer JWT tokens where these tokens can have their claims, such as issuer
and audience
modified and the updated tokens secured (for example, re-signed) again. It expects an injected org.eclipse.microprofile.jwt.JsonWebToken
and, therefore, will not work with the opaque tokens. Also, if your OpenID Connect Provider supports a Token Exchange protocol, then it is recommended to use AccessTokenRequestFilter
instead - as both JWT and opaque bearer tokens can be securely exchanged with AccessTokenRequestFilter
.
JsonWebTokenRequestFilter
makes it easy for Service A
implementations to update the injected org.eclipse.microprofile.jwt.JsonWebToken
with the new issuer
and audience
claim values and secure the updated token again with a new signature. The only difficult step is ensuring that Service A
has a signing key; it should be provisioned from a secure file system or remote secure storage such as Vault.
You can selectively register JsonWebTokenRequestFilter
by using either io.quarkus.oidc.token.propagation.JsonWebToken
or org.eclipse.microprofile.rest.client.annotation.RegisterProvider
, for example:
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.JsonWebToken;
@RegisterRestClient
@JsonWebToken
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
or
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.JsonWebTokenRequestFilter;
@RegisterRestClient
@RegisterProvider(JsonWebTokenRequestFilter.class)
@Path("/")
public interface ProtectedResourceService {
@GET
String getUserName();
}
Alternatively, JsonWebTokenRequestFilter
can be registered automatically with all MicroProfile REST or Jakarta REST clients if both quarkus.resteasy-client-oidc-token-propagation.register-filter
and quarkus.resteasy-client-oidc-token-propagation.json-web-token
properties are set to true
.
Update token before propagation
If the injected token needs to have its iss
(issuer) or aud
(audience) claims updated and secured again with a new signature, then you can configure JsonWebTokenRequestFilter
like this:
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
As mentioned, use AccessTokenRequestFilter
if you work with Keycloak or an OpenID Connect Provider that supports a Token Exchange protocol.
测试
You can generate the tokens as described in OpenID Connect Bearer Token Integration testing section.
Prepare the REST test endpoints. You can have the test front-end endpoint, which uses the injected MP REST client with a registered token propagation filter, call the downstream endpoint. For example, see the integration-tests/resteasy-client-oidc-token-propagation
in the main
Quarkus repository.
GraphQL client integration
The quarkus-oidc-client-graphql
extension provides a way to integrate an OIDC client into GraphQL clients paralleling the approach used with REST clients.
When this extension is active, any GraphQL client configured through properties (rather than programmatically by the builder) will use the OIDC client to acquire an access token, which it will then set as the Authorization
header value.
The OIDC client will also refresh expired access tokens.
To configure which OIDC client should be used by the GraphQL client, select one of the configured OIDC clients with the quarkus.oidc-client-graphql.client-name
property, for example:
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
If you don’t specify the quarkus.oidc-client-graphql.client-name property,
GraphQL clients will use the default OIDC client (without an explicit name).
|
Specifically for type-safe GraphQL clients, you can override this on a
per-client basis by annotating the GraphQLClientApi
interface with
@io.quarkus.oidc.client.filter.OidcClientFilter
. For example:
@GraphQLClientApi(configKey = "order-client")
@OidcClientFilter("oidc-client-for-graphql")
public interface OrdersGraphQLClient {
// Queries, mutations, and subscriptions go here.
}
To be able to use this with a programmatically created GraphQL client, both
builders (VertxDynamicGraphQLClientBuilder
and
VertxTypesafeGraphQLClientBuilder
) contain a method dynamicHeader(String,
Uni<String>
) that allows you to plug in a header that might change for
every request. To plug an OIDC client into it, use
@Inject
OidcClients oidcClients;
VertxTypesafeGraphQLClientBuilder builder = ....;
Uni<String> tokenUni = oidcClients.getClient("OIDC_CLIENT_NAME")
.getTokens().map(t -> "Bearer " + t.getAccessToken());
builder.dynamicHeader("Authorization", tokenUni);
VertxDynamicGraphQLClient client = builder.build();
Configuration reference
OIDC client
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
类型 |
默认 |
---|---|---|
If the OIDC client extension is enabled. Environment variable: Show more |
boolean |
|
The base URL of the OpenID Connect (OIDC) server, for example, Environment variable: Show more |
string |
|
Discovery of the OIDC endpoints. If not enabled, you must configure the OIDC endpoint URLs individually. Environment variable: Show more |
boolean |
|
The OIDC token endpoint that issues access and refresh tokens; specified as a relative path or absolute URL. Set if Environment variable: Show more |
string |
|
The relative path or absolute URL of the OIDC token revocation endpoint. Environment variable: Show more |
string |
|
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 Environment variable: Show more |
string |
|
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: Show more |
string |
|
The duration to attempt the initial connection to an OIDC server. For example, setting the duration to Environment variable: Show more |
||
The number of times to retry re-establishing an existing OIDC connection if it is temporarily lost. Different from Environment variable: Show more |
int |
|
The number of seconds after which the current OIDC connection request times out. Environment variable: Show more |
|
|
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: Show more |
boolean |
|
The maximum size of the connection pool used by the WebClient. Environment variable: Show more |
int |
|
The client secret used by the Environment variable: Show more |
string |
|
The client secret value. This value is ignored if Environment variable: Show more |
string |
|
The CredentialsProvider bean name, which should only be set if more than one CredentialsProvider is registered Environment variable: Show more |
string |
|
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: Show more |
string |
|
The CredentialsProvider client secret key Environment variable: Show more |
string |
|
The authentication method. If the Environment variable: Show more |
|
|
JWT token source: OIDC provider client or an existing JWT bearer token. Environment variable: Show more |
|
|
If provided, indicates that JWT is signed using a secret key. Environment variable: Show more |
string |
|
The CredentialsProvider bean name, which should only be set if more than one CredentialsProvider is registered Environment variable: Show more |
string |
|
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: Show more |
string |
|
The CredentialsProvider client secret key Environment variable: Show more |
string |
|
String representation of a private key. If provided, indicates that JWT is signed using a private key in PEM or JWK format. You can use the Environment variable: Show more |
string |
|
If provided, indicates that JWT is signed using a private key in PEM or JWK format. You can use the Environment variable: Show more |
string |
|
If provided, indicates that JWT is signed using a private key from a keystore. Environment variable: Show more |
string |
|
A parameter to specify the password of the keystore file. Environment variable: Show more |
string |
|
The private key id or alias. Environment variable: Show more |
string |
|
The private key password. Environment variable: Show more |
string |
|
The JWT audience ( Environment variable: Show more |
string |
|
The key identifier of the signing key added as a JWT Environment variable: Show more |
string |
|
The issuer of the signing key added as a JWT Environment variable: Show more |
string |
|
Subject of the signing key added as a JWT Environment variable: Show more |
string |
|
Additional claims. Environment variable: Show more |
Map<String,String> |
|
The signature algorithm used for the Environment variable: Show more |
string |
|
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: Show more |
int |
|
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: Show more |
boolean |
|
The host name or IP address of the Proxy. Environment variable: Show more |
string |
|
The port number of the Proxy. The default value is Environment variable: Show more |
int |
|
The username, if the Proxy needs authentication. Environment variable: Show more |
string |
|
The password, if the Proxy needs authentication. Environment variable: Show more |
string |
|
Certificate validation and hostname verification, which can be one of the following Environment variable: Show more |
|
|
An optional keystore that holds the certificate information instead of specifying separate files. Environment variable: Show more |
path |
|
The type of the keystore file. If not given, the type is automatically detected based on the file name. Environment variable: Show more |
string |
|
The provider of the keystore file. If not given, the provider is automatically detected based on the keystore file type. Environment variable: Show more |
string |
|
The password of the keystore file. If not given, the default value, Environment variable: Show more |
string |
|
The alias of a specific key in the keystore. When SNI is disabled, if the keystore contains multiple keys and no alias is specified, the behavior is undefined. Environment variable: Show more |
string |
|
The password of the key, if it is different from the Environment variable: Show more |
string |
|
The truststore that holds the certificate information of the certificates to trust. Environment variable: Show more |
path |
|
The password of the truststore file. Environment variable: Show more |
string |
|
The alias of the truststore certificate. Environment variable: Show more |
string |
|
The type of the truststore file. If not given, the type is automatically detected based on the file name. Environment variable: Show more |
string |
|
The provider of the truststore file. If not given, the provider is automatically detected based on the truststore file type. Environment variable: Show more |
string |
|
A unique OIDC client identifier. It must be set when OIDC clients are created dynamically and is optional in all other cases. Environment variable: Show more |
string |
|
If this client configuration is enabled. Environment variable: Show more |
boolean |
|
List of access token scopes Environment variable: Show more |
list of string |
|
Refresh token time skew in seconds. If this property is enabled then the configured number of seconds 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: Show more |
||
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: Show more |
boolean |
|
Grant type Environment variable: Show more |
|
|
Access token property name in a token grant response Environment variable: Show more |
string |
|
Refresh token property name in a token grant response Environment variable: Show more |
string |
|
Access token expiry property name in a token grant response Environment variable: Show more |
string |
|
Refresh token expiry property name in a token grant response Environment variable: Show more |
string |
|
Grant options Environment variable: Show more |
Map<String,Map<String,String>> |
|
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: Show more |
boolean |
|
Custom HTTP headers which have to be sent to the token endpoint Environment variable: Show more |
Map<String,String> |
|
类型 |
默认 |
|
The base URL of the OpenID Connect (OIDC) server, for example, Environment variable: Show more |
string |
|
Discovery of the OIDC endpoints. If not enabled, you must configure the OIDC endpoint URLs individually. Environment variable: Show more |
boolean |
|
The OIDC token endpoint that issues access and refresh tokens; specified as a relative path or absolute URL. Set if Environment variable: Show more |
string |
|
The relative path or absolute URL of the OIDC token revocation endpoint. Environment variable: Show more |
string |
|
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 Environment variable: Show more |
string |
|
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: Show more |
string |
|
The duration to attempt the initial connection to an OIDC server. For example, setting the duration to Environment variable: Show more |
||
The number of times to retry re-establishing an existing OIDC connection if it is temporarily lost. Different from Environment variable: Show more |
int |
|
The number of seconds after which the current OIDC connection request times out. Environment variable: Show more |
|
|
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: Show more |
boolean |
|
The maximum size of the connection pool used by the WebClient. Environment variable: Show more |
int |
|
The client secret used by the Environment variable: Show more |
string |
|
The client secret value. This value is ignored if Environment variable: Show more |
string |
|
The CredentialsProvider bean name, which should only be set if more than one CredentialsProvider is registered Environment variable: Show more |
string |
|
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: Show more |
string |
|
The CredentialsProvider client secret key Environment variable: Show more |
string |
|
The authentication method. If the Environment variable: Show more |
|
|
JWT token source: OIDC provider client or an existing JWT bearer token. Environment variable: Show more |
|
|
If provided, indicates that JWT is signed using a secret key. Environment variable: Show more |
string |
|
The CredentialsProvider bean name, which should only be set if more than one CredentialsProvider is registered Environment variable: Show more |
string |
|
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: Show more |
string |
|
The CredentialsProvider client secret key Environment variable: Show more |
string |
|
String representation of a private key. If provided, indicates that JWT is signed using a private key in PEM or JWK format. You can use the Environment variable: Show more |
string |
|
If provided, indicates that JWT is signed using a private key in PEM or JWK format. You can use the Environment variable: Show more |
string |
|
If provided, indicates that JWT is signed using a private key from a keystore. Environment variable: Show more |
string |
|
A parameter to specify the password of the keystore file. Environment variable: Show more |
string |
|
The private key id or alias. Environment variable: Show more |
string |
|
The private key password. Environment variable: Show more |
string |
|
The JWT audience ( Environment variable: Show more |
string |
|
The key identifier of the signing key added as a JWT Environment variable: Show more |
string |
|
The issuer of the signing key added as a JWT Environment variable: Show more |
string |
|
Subject of the signing key added as a JWT Environment variable: Show more |
string |
|
Additional claims. Environment variable: Show more |
Map<String,String> |
|
The signature algorithm used for the Environment variable: Show more |
string |
|
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: Show more |
int |
|
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: Show more |
boolean |
|
The host name or IP address of the Proxy. Environment variable: Show more |
string |
|
The port number of the Proxy. The default value is Environment variable: Show more |
int |
|
The username, if the Proxy needs authentication. Environment variable: Show more |
string |
|
The password, if the Proxy needs authentication. Environment variable: Show more |
string |
|
Certificate validation and hostname verification, which can be one of the following Environment variable: Show more |
|
|
An optional keystore that holds the certificate information instead of specifying separate files. Environment variable: Show more |
path |
|
The type of the keystore file. If not given, the type is automatically detected based on the file name. Environment variable: Show more |
string |
|
The provider of the keystore file. If not given, the provider is automatically detected based on the keystore file type. Environment variable: Show more |
string |
|
The password of the keystore file. If not given, the default value, Environment variable: Show more |
string |
|
The alias of a specific key in the keystore. When SNI is disabled, if the keystore contains multiple keys and no alias is specified, the behavior is undefined. Environment variable: Show more |
string |
|
The password of the key, if it is different from the Environment variable: Show more |
string |
|
The truststore that holds the certificate information of the certificates to trust. Environment variable: Show more |
path |
|
The password of the truststore file. Environment variable: Show more |
string |
|
The alias of the truststore certificate. Environment variable: Show more |
string |
|
The type of the truststore file. If not given, the type is automatically detected based on the file name. Environment variable: Show more |
string |
|
The provider of the truststore file. If not given, the provider is automatically detected based on the truststore file type. Environment variable: Show more |
string |
|
A unique OIDC client identifier. It must be set when OIDC clients are created dynamically and is optional in all other cases. Environment variable: Show more |
string |
|
If this client configuration is enabled. Environment variable: Show more |
boolean |
|
List of access token scopes Environment variable: Show more |
list of string |
|
Refresh token time skew in seconds. If this property is enabled then the configured number of seconds 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: Show more |
||
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: Show more |
boolean |
|
Grant type Environment variable: Show more |
|
|
Access token property name in a token grant response Environment variable: Show more |
string |
|
Refresh token property name in a token grant response Environment variable: Show more |
string |
|
Access token expiry property name in a token grant response Environment variable: Show more |
string |
|
Refresh token expiry property name in a token grant response Environment variable: Show more |
string |
|
Grant options Environment variable: Show more |
Map<String,Map<String,String>> |
|
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: Show more |
boolean |
|
Custom HTTP headers which have to be sent to the token endpoint Environment variable: Show more |
Map<String,String> |
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|
OIDC token propagation
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
类型 |
默认 |
---|---|---|
If the OIDC Token Reactive Propagation is enabled. Environment variable: Show more |
boolean |
|
Whether the token propagation is enabled during the For example, you may need to use a REST client from Note, this feature relies on a duplicated context. More information about Vert.x duplicated context can be found in this guide. Environment variable: Show more |
boolean |
|
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: Show more |
boolean |
|
Name of the configured OidcClient. Note this property is only used if the Environment variable: Show more |
string |