Enable OAUTH2/OIDC authentication for Apache Kafka®
Aiven for Apache Kafka® enables secure client authentication using OIDC/OAuth2, allowing clients to verify users through an authorization server.
By activating this, you can use token-based authentication and integrate with identity providers. Setting the JSON Web Key Set (JWKS) JWKS endpoint via the Aiven console activates the OIDC mechanism for Kafka, which triggers a rolling restart of the Kafka brokers. This restart does not cause service downtime.
To use the OAUTHBEARER
mechanism, you must enable kafka_authentication_methods.sasl
.
Additionally, at least one of the SASL mechanisms (PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512)
must be enabled. See
Enable and configure SASL authentication with Aiven for Apache Kafka®.
Prerequisites
Aiven for Apache Kafka integrates with a wide range of OpenID Connect identity providers (IdPs). However, the exact configuration steps can differ based on your chosen IdP. Refer to your Identity Provider's official documentation for specific configuration guidelines.
Before proceeding with the setup, ensure you have:
- Aiven for Apache Kafka® service running.
- Access to an OIDC provider: Options include Auth0, Okta, Google Identity Platform, Azure, or any other OIDC compliant provider.
- Required configuration details from your OIDC provider:
- JWKS Endpoint URL: URL to retrieve the JSON Web Key Set (JWKS).
- Subject Claim Name: Typically
sub
, but this can vary depending on your OIDC provider. - Issuer URL or Identifier: Identifies and verifies the JWT issuer.
- Audience identifiers: Validates the JWT's intended recipients. For multiple audiences, make a note of all.
Enable OAuth2/OIDC for Apache Kafka®
- Aiven Console
- CLI
-
In the Aiven Console, select your project and choose your Aiven for Apache Kafka® service.
-
Click Service settings.
-
Scroll to Advanced configuration and click Configure.
-
In the Advanced configuration window, click Add configuration options.
-
Set the OIDC parameters as detailed in the OIDC Parameters section.
-
Click Save configurations.
To enable OAuth2/OIDC authentication for your Aiven for Apache Kafka service using Aiven CLI:
-
Get the name of your Aiven for Apache Kafka service:
avn service list
Note the
SERVICE_NAME
corresponding to your Aiven for Apache Kafka service. -
Enable OAuth2/OIDC authentication for your service:
avn service update <SERVICE_NAME> \
-c kafka.sasl_oauthbearer_expected_audience="my-audience, another-audience" \
-c kafka.sasl_oauthbearer_expected_issuer="https://my-issuer.example.com" \
-c kafka.sasl_oauthbearer_jwks_endpoint_url="https://my-jwks-endpoint.example.com/jwks" \
-c kafka.sasl_oauthbearer_sub_claim_name="custom-sub"
For detailed explanations on the OIDC parameters, see the OIDC Parameters section.
OIDC parameters
Set the following OIDC parameters:
kafka.sasl_oauthbearer_jwks_endpoint_url
- Description: Endpoint for retrieving the JSON Web Key Set
(JWKS), which enables OIDC authentication. Corresponds to
the Apache Kafka parameter
sasl.oauthbearer.jwks.endpoint.url
. - Value: Enter the JWKS endpoint URL provided by your OIDC provider.
- Description: Endpoint for retrieving the JSON Web Key Set
(JWKS), which enables OIDC authentication. Corresponds to
the Apache Kafka parameter
- Optional:
kafka.sasl_oauthbearer_sub_claim_name
- Description: Name of the JWT's subject claim for broker
verification. It is typically set to
sub
. Corresponds to the Apache Kafka parametersasl.oauthbearer.sub.claim.name
. - Value: Enter
sub
or the specific claim name provided by your OIDC provider if different.
- Description: Name of the JWT's subject claim for broker
verification. It is typically set to
- Optional:
kafka.sasl_oauthbearer_expected_issuer
- Description: Specifies the JWT's issuer for the broker to
verify. Corresponds to the Apache Kafka parameter
sasl.oauthbearer.expected.issuer
. - Value: Enter the issuer URL or identifier provided by your OIDC provider.
- Description: Specifies the JWT's issuer for the broker to
verify. Corresponds to the Apache Kafka parameter
- Optional:
kafka.sasl_oauthbearer_expected_audience
- Description: Validates the intended JWT audience for the
broker. Corresponds to the Apache Kafka parameter
sasl.oauthbearer.expected.audience
. It is used if your OIDC provider specifies an audience. - Value: Input the audience identifiers given by your OIDC provider. If there are multiple audiences, separate them with commas.
- Description: Validates the intended JWT audience for the
broker. Corresponds to the Apache Kafka parameter
For more information on each corresponding Apache Kafka parameter,
see Apache Kafka documentation on
configuration options starting with sasl.oauthbearer
.
Adjusting OIDC configurations, such as enabling, disabling, or modifying settings, can lead to a rolling restart of Apache Kafka brokers. As a result, the brokers may temporarily operate with different configurations. To minimize any operational disruptions, plan to implement these changes during a maintenance window or at a time that ensures a minimal impact on your operations.