Skip to main content

Enable OAuth 2.0/OIDC authentication for Apache Kafka®

Aiven for Apache Kafka® supports OAuth 2.0/OIDC authentication for Kafka clients. Use OAuth 2.0/OIDC authentication to let clients authenticate with tokens issued by an identity provider, or by an identity broker such as Outbound Identity Federation.

Prerequisites​

Before you begin, make sure you have:

  • An Aiven for Apache Kafka service.
  • SASL authentication enabled on the service. OAuth 2.0/OIDC uses the OAUTHBEARER SASL mechanism.
  • Access to an OIDC provider, such as Auth0, Okta, Google Identity Platform, Azure, or another OIDC-compliant provider.
  • Configuration details from your OIDC provider:
    • JWKS endpoint URL: Required. HTTPS URL to retrieve the JSON Web Key Set, or JWKS.
    • Issuer URL or identifier: Required by most OIDC providers. Identifies and verifies the JWT issuer.
    • Audience identifiers: Required by most OIDC providers. Validates the JWT's intended recipients. For multiple audiences, note each value.
    • Subject claim name: Optional. Typically sub, but this can vary depending on your OIDC provider.

Configuration steps vary by identity provider. See your provider's documentation for JWKS URL, issuer, and audience values.

Configure OAuth 2.0/OIDC settings​

Set kafka.sasl_oauthbearer_jwks_endpoint_url to enable OAUTHBEARER.

To use only OAuth 2.0/OIDC authentication, enable SASL authentication, set kafka.sasl_oauthbearer_jwks_endpoint_url, and disable PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512.

note

When SASL authentication is enabled, at least one SASL mechanism must be available. OAUTHBEARER satisfies this requirement when kafka.sasl_oauthbearer_jwks_endpoint_url is set.

Configure OAuth 2.0/OIDC authentication using one of the following methods.

  1. In the Aiven Console, select your project and choose your Aiven for Apache Kafka service.

  2. Click Service settings.

  3. Scroll to Advanced configuration and click Configure.

  4. In the Advanced configuration window, click Add configuration options.

  5. Enable SASL authentication by setting kafka_authentication_methods.sasl to Enabled.

  6. Configure the JWKS endpoint by setting kafka.sasl_oauthbearer_jwks_endpoint_url to your provider's JWKS URL.

    This enables the OAUTHBEARER mechanism. PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 remain enabled by default.

  7. Optional: Configure other OIDC parameters, such as expected issuer, expected audience, and subject claim. See OIDC parameters for details.

  8. Optional: To use only OAuth 2.0/OIDC authentication, set kafka_sasl_mechanisms.plain, kafka_sasl_mechanisms.scram_sha_256, and kafka_sasl_mechanisms.scram_sha_512 to Disabled.

  9. Click Save configurations.

OIDC parameters​

Configure the following OIDC parameters:

  • kafka.sasl_oauthbearer_jwks_endpoint_url

    • Description: Endpoint for retrieving the JSON Web Key Set, or JWKS, which enables OIDC authentication. Corresponds to the Apache Kafka parameter sasl.oauthbearer.jwks.endpoint.url.

    • Value: Enter the HTTPS JWKS endpoint URL provided by your OIDC provider.

      note

      Starting with Apache Kafka 4.0, the broker verifies that the JWKS endpoint URL for OAuth authentication matches an entry in the system property org.apache.kafka.sasl.oauthbearer.allowed.urls. Aiven sets this property from the value of kafka.sasl_oauthbearer_jwks_endpoint_url. You do not need additional configuration.

  • kafka.sasl_oauthbearer_sub_claim_name

    • Optional

    • Description: Name of the JWT's subject claim for broker verification. It is typically set to sub. Corresponds to the Apache Kafka parameter sasl.oauthbearer.sub.claim.name.

    • Value: Enter sub or the specific claim name provided by your OIDC provider if different.

      note

      The claim must be a string. Claims that contain arrays, such as groups, are not supported.

  • kafka.sasl_oauthbearer_expected_issuer

    • Optional
    • 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.

  • kafka.sasl_oauthbearer_expected_audience

    • Optional
    • Description: Validates the intended JWT audience for the broker. Corresponds to the Apache Kafka parameter sasl.oauthbearer.expected.audience. Use this parameter when your OIDC provider specifies an audience.
    • Value: Enter the audience identifiers given by your OIDC provider. If there are multiple audiences, separate them with commas.

For more information about each corresponding Apache Kafka parameter, see Apache Kafka documentation on configuration options starting with sasl.oauthbearer.

warning

Changing OIDC settings triggers a rolling restart of Apache Kafka brokers. As a result, the brokers temporarily operate with different configurations. To reduce operational impact, apply these changes during a maintenance window.

Related pages