Manage the JWKS URI on Confluent Cloud

You need to manage the JSON Web Key Set (JWKS) URI of your OAuth identity provider to:

  • Ensure that the public keys used to verify the signatures of JSON Web Tokens (JWTs) are up to date. Follow the steps below to manually refresh the JWKS URI if the automatic refresh fails or if you rotate the public keys.

  • If your identity provider is behind a firewall, verify network access to your JWKS URI at least every three months.

Automatic refresh when a key ID is missing

If a Confluent Cloud cluster receives a JWT whose kid header value doesn’t match any cached key, the request fails with a JWT_HEADER_KID_LOOKUP_FAILED error. Confluent Cloud detects this condition and automatically triggers an expedited refresh of the JWKS keys from your identity provider. After the key is rotated, the cluster picks up the new key in approximately one second.

Note

The expedited refresh runs asynchronously. Clients might still see the JWT_HEADER_KID_LOOKUP_FAILED error on the first request after you rotate your signing key. The error resolves itself when the client retries after the new key is loaded.

You don’t need to manually refresh the JWKS URI or wait for the next scheduled refresh, which is determined by the max-age setting.

Expedited refresh doesn’t work if your identity provider behind a firewall. For IdPs behind a firewall, set a lower max-age value for more frequent refreshes, or manually refresh the JWKS URI after you rotate your signing key.

Refresh the JWKS URI of an OAuth identity provider

You can manually refresh the JWKS URI of your OAuth identity provider using either the Confluent Cloud Console or the Confluent Cloud REST API to:

  • Force immediate application of rotated public keys.

  • Recover from automatic refresh failures.

Refresh Frequency Settings

The max-age directive in the Cache-Control header of the JWKS URI response determines how often keys are refreshed. The value for max-age is specified in seconds. Confluent Cloud observes the following values:

  • Minimum: 300 (5 minutes)

  • Maximum: 604800 (7 days)

  • Default: 86400 (24 hours), used when max-age is not specified.

Note: A max-age value below the minimum is automatically set to 300, while a value above the maximum is capped at 604800. To increase refresh frequency, set a lower max-age value in your Cache-Control header.

Example: To set a 1-hour (3600 seconds) refresh frequency, the Cache-Control header should be:

Cache-Control: max-age=3600

If the JWKS URI is temporarily unavailable, the system continues using the cached keys until the next successful refresh. In prolonged outages, you might need to manually refresh the JWKS URI using the procedure below once connectivity is restored.

Use the Confluent Cloud Console to manually refresh the JWKS URI

To manually refresh the JWKS URI of your OAuth identity provider:,

  1. Sign in to the Confluent Cloud Console and go to the Workload identities tab on the Accounts & access page at https://confluent.cloud/settings/org/workload_identities.

  2. Click the identity provider you want to refresh. The details page appears.

  3. Click Edit (icon) and then click Refresh JWKS keys.

The refresh operation proceeds and the identity provider details page appears.

Use the Confluent Cloud REST API to manually refresh the JWKS URI

To use the Confluent Cloud REST API to make a request to refresh the JWKS URI, see Refresh a provider’s JWKS.

Verify network access to the JWKS URI

If your identity provider is behind a firewall, you should verify network access from Confluent Cloud to your identity provider using the public IP addresses at least every three months to ensure that Confluent Cloud can access your Confluent Cloud JWKS endpoint over the internet. Contact your identity provider to add new Confluent Cloud public IP addresses to your firewall allowlist.

You can view the available Confluent Cloud public IP addresses on the Confluent Cloud Console. Navigate to Accounts and access -> Workload identities tab.

../../../../../_images/oauth-oidc-jwks-workload-identities-tab.png