Sync documentation of main branch

actions-user · actions-user · commit b37b1a06f878 · 2025-06-12T02:06:26.000Z
diff --git a/_generated-doc/main/config/quarkus-all-config.adoc b/_generated-doc/main/config/quarkus-all-config.adoc
@@ -72353,6 +72353,32 @@ endif::add-copy-button-to-env-var[]
 |Map<String,String>
 |
 
+a| [[quarkus-oidc-client_quarkus-oidc-client-refresh-interval]] [.property-path]##link:#quarkus-oidc-client_quarkus-oidc-client-refresh-interval[`quarkus.oidc-client.refresh-interval`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.oidc-client.refresh-interval+++[]
+endif::add-copy-button-to-config-props[]
+
+
+`quarkus.oidc-client."id".refresh-interval`
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.oidc-client."id".refresh-interval+++[]
+endif::add-copy-button-to-config-props[]
+
+[.description]
+--
+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.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL+++`
+endif::add-copy-button-to-env-var[]
+--
+|link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html[Duration] link:#duration-note-anchor-all-config[icon:question-circle[title=More information about the Duration format]]
+|
+
 h|[[quarkus-oidc-client_section_quarkus-oidc-client-proxy]] [.section-name.section-level0]##link:#quarkus-oidc-client_section_quarkus-oidc-client-proxy[HTTP proxy configuration]##
 h|Type
 h|Default
diff --git a/_generated-doc/main/config/quarkus-oidc-client.adoc b/_generated-doc/main/config/quarkus-oidc-client.adoc
@@ -756,6 +756,32 @@ endif::add-copy-button-to-env-var[]
 |Map<String,String>
 |
 
+a| [[quarkus-oidc-client_quarkus-oidc-client-refresh-interval]] [.property-path]##link:#quarkus-oidc-client_quarkus-oidc-client-refresh-interval[`quarkus.oidc-client.refresh-interval`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.oidc-client.refresh-interval+++[]
+endif::add-copy-button-to-config-props[]
+
+
+`quarkus.oidc-client."id".refresh-interval`
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.oidc-client."id".refresh-interval+++[]
+endif::add-copy-button-to-config-props[]
+
+[.description]
+--
+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.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL+++`
+endif::add-copy-button-to-env-var[]
+--
+|link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html[Duration] link:#duration-note-anchor-quarkus-oidc-client_quarkus-oidc-client[icon:question-circle[title=More information about the Duration format]]
+|
+
 h|[[quarkus-oidc-client_section_quarkus-oidc-client-proxy]] [.section-name.section-level0]##link:#quarkus-oidc-client_section_quarkus-oidc-client-proxy[HTTP proxy configuration]##
 h|Type
 h|Default
diff --git a/_generated-doc/main/config/quarkus-oidc-client_quarkus.oidc-client.adoc b/_generated-doc/main/config/quarkus-oidc-client_quarkus.oidc-client.adoc
@@ -756,6 +756,32 @@ endif::add-copy-button-to-env-var[]
 |Map<String,String>
 |
 
+a| [[quarkus-oidc-client_quarkus-oidc-client-refresh-interval]] [.property-path]##link:#quarkus-oidc-client_quarkus-oidc-client-refresh-interval[`quarkus.oidc-client.refresh-interval`]##
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.oidc-client.refresh-interval+++[]
+endif::add-copy-button-to-config-props[]
+
+
+`quarkus.oidc-client."id".refresh-interval`
+ifdef::add-copy-button-to-config-props[]
+config_property_copy_button:+++quarkus.oidc-client."id".refresh-interval+++[]
+endif::add-copy-button-to-config-props[]
+
+[.description]
+--
+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.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_OIDC_CLIENT_REFRESH_INTERVAL+++`
+endif::add-copy-button-to-env-var[]
+--
+|link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html[Duration] link:#duration-note-anchor-quarkus-oidc-client_quarkus-oidc-client[icon:question-circle[title=More information about the Duration format]]
+|
+
 h|[[quarkus-oidc-client_section_quarkus-oidc-client-proxy]] [.section-name.section-level0]##link:#quarkus-oidc-client_section_quarkus-oidc-client-proxy[HTTP proxy configuration]##
 h|Type
 h|Default
diff --git a/_versions/main/guides/security-openid-connect-client-reference.adoc b/_versions/main/guides/security-openid-connect-client-reference.adoc
@@ -713,6 +713,16 @@ You can also inject named `Tokens`, see <<named-oidc-clients,Inject named OidcCl
 `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.
 
+
+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](https://quarkus.io/guides/security-openid-connect-client-reference#quarkus-oidc-client_quarkus-oidc-client-refresh-token-time-skew) is configured.
+Performance critical applications may want to avoid having to wait for a possible token refresh during the incoming requests and configure an asynchronous token refresh instead, for example:
+
+[source,properties]
+----
+quarkus.oidc-client.refresh-interval=1m <1>
+----
+<1> Check every minute if the current access token is expired and must be 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.
