Enable and configure SASL authentication for Apache Kafka®

Aiven for Apache Kafka® supports multiple authentication methods, including Simple Authentication and Security Layer (SASL) over SSL.

Enable SASL authentication

To allow clients to authenticate with SASL, enable kafka_authentication_methods.sasl on your Aiven for Apache Kafka service.

Aiven Console

1. In the Aiven Console, select your Aiven for Apache Kafka service.
2. Click Service settings.
3. Scroll to Advanced configuration and click Configure.
4. Click Add configuration options.
5. Select kafka_authentication_methods.sasl from the list and set the value to Enabled.
6. Click Save configurations.

The Connection information on the Overview page now shows connection details for SASL and client certificate authentication.

note

SASL and client certificate connections use different ports. The host, CA, and user credentials remain the same.

CLI

Enable SASL authentication for your Aiven for Apache Kafka service using Aiven CLI:

1. Get the name of the Aiven for Apache Kafka service:

   avn service list

   Note the SERVICE_NAME corresponding to your Aiven for Apache Kafka service.

2. Enable SASL authentication:

   avn service update SERVICE_NAME -c kafka_authentication_methods.sasl=true

   Parameters:

   • SERVICE_NAME: Name of your Aiven for Apache Kafka service.
   • kafka_authentication_methods.sasl: Set to true to enable SASL authentication.

API

Use the ServiceUpdate API to enable SASL authentication on an existing service:

curl -X PUT "https://api.aiven.io/v1/project/{project_name}/service/{service_name}" \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "user_config": {
             "kafka_authentication_methods": {
               "sasl": true
             }
           }
         }'

Parameters:

• project_name: Name of your Aiven project.
• service_name: Name of your Aiven for Apache Kafka service.
• API_TOKEN: Personal Aiven token.
• kafka_authentication_methods.sasl: Set to true to enable SASL authentication.

Terraform

Set the kafka_authentication_methods.sasl attribute in your aiven_kafka resource to true.

Configure SASL mechanisms

After enabling SASL authentication, choose which SASL mechanisms clients can use.

Supported mechanisms

Aiven for Apache Kafka supports the following SASL mechanisms:

• PLAIN: Enabled by default. Controlled by kafka_sasl_mechanisms.plain.

• SCRAM-SHA-256: Enabled by default. Controlled by kafka_sasl_mechanisms.scram_sha_256.

• SCRAM-SHA-512: Enabled by default. Controlled by kafka_sasl_mechanisms.scram_sha_512.

• OAUTHBEARER: Set kafka.sasl_oauthbearer_jwks_endpoint_url to enable OAuth 2.0/OIDC authentication. PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 remain enabled by default. Each client selects one SASL mechanism when it connects.

  To allow only OAuth 2.0/OIDC authentication, disable kafka_sasl_mechanisms.plain, kafka_sasl_mechanisms.scram_sha_256, and kafka_sasl_mechanisms.scram_sha_512.

  Optional OIDC parameters include kafka.sasl_oauthbearer_expected_issuer, kafka.sasl_oauthbearer_expected_audience, and kafka.sasl_oauthbearer_sub_claim_name.

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. If you disable PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 without setting kafka.sasl_oauthbearer_jwks_endpoint_url, the update fails because no SASL mechanism is available.

Enable or disable PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512

Use kafka_sasl_mechanisms to enable or disable these mechanisms using one of the following methods.

Aiven Console

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

2. Click Service settings.

3. Scroll to Advanced configuration and click Configure.

4. In the Advanced configuration window, configure PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512:

   • To enable or disable PLAIN, set kafka_sasl_mechanisms.plain to Enabled or Disabled.
   • To enable or disable SCRAM-SHA-256, set kafka_sasl_mechanisms.scram_sha_256 to Enabled or Disabled.
   • To enable or disable SCRAM-SHA-512, set kafka_sasl_mechanisms.scram_sha_512 to Enabled or Disabled.

5. Click Save configurations.

CLI

Configure SASL mechanisms for your Aiven for Apache Kafka service using Aiven CLI:

1. Get the name of the Aiven for Apache Kafka service:

   avn service list

   Note the SERVICE_NAME corresponding to your Aiven for Apache Kafka service.

2. Disable the SASL mechanisms that clients do not use. By default, PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 are enabled. For example, to disable PLAIN authentication:

   avn service update SERVICE_NAME \
       -c kafka_sasl_mechanisms.plain=false

   SCRAM-SHA-256 and SCRAM-SHA-512 remain enabled unless you disable them.

   Parameters:

   • SERVICE_NAME: Name of your Aiven for Apache Kafka service.
   • kafka_sasl_mechanisms.plain: Set to true or false to enable or disable PLAIN.
   • kafka_sasl_mechanisms.scram_sha_256: Set to true or false to enable or disable SCRAM-SHA-256.
   • kafka_sasl_mechanisms.scram_sha_512: Set to true or false to enable or disable SCRAM-SHA-512.

API

Use the ServiceUpdate API to configure PLAIN and SCRAM mechanisms on an existing service:

curl -X PUT "https://api.aiven.io/v1/project/{project_name}/service/{service_name}" \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "user_config": {
             "kafka_sasl_mechanisms": {
               "plain": false,
               "scram_sha_256": true,
               "scram_sha_512": true
             }
           }
         }'

Parameters:

• project_name: Name of your Aiven project.
• service_name: Name of your Aiven for Apache Kafka service.
• API_TOKEN: Personal Aiven token.
• kafka_sasl_mechanisms.plain: Set to true or false to enable or disable PLAIN.
• kafka_sasl_mechanisms.scram_sha_256: Set to true or false to enable or disable SCRAM-SHA-256.
• kafka_sasl_mechanisms.scram_sha_512: Set to true or false to enable or disable SCRAM-SHA-512.

Terraform

Use the kafka_sasl_mechanisms attribute in your aiven_kafka resource to enable or disable PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512. Set each mechanism to true or false:

• PLAIN: kafka_sasl_mechanisms.plain
• SCRAM-SHA-256: kafka_sasl_mechanisms.scram_sha_256
• SCRAM-SHA-512: kafka_sasl_mechanisms.scram_sha_512

Enable public CA certificates for SASL authentication

After you enable SASL authentication, you can enable public CA certificates for clients that cannot install or trust the default project CA.

Enable public CA certificates using one of the following methods.

Aiven Console

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

2. Click Service settings.

3. Go to the Cloud and network section and click Actions > More network configurations.

4. In the Network configuration dialog:

   1. Click Add configuration options.
   2. Find letsencrypt_sasl (or letsencrypt_sasl_privatelink for PrivateLink).
   3. Select the configuration option.
   4. Set the value to Enabled.
   5. Click Save configurations.

The Connection information on the Overview page now supports SASL connections using either Project CA or Public CA.

CLI

Enable the public CA certificates for SASL authentication using the Aiven CLI:

1. List the services in your project to find your Aiven for Apache Kafka service name:

   avn service list

   Note the SERVICE_NAME corresponding to your Aiven for Apache Kafka service.

2. Enable public CA certificates for SASL authentication:

   avn service update SERVICE_NAME -c letsencrypt_sasl=true

   For PrivateLink, use -c letsencrypt_sasl_privatelink=true instead.

   Parameters:

   • SERVICE_NAME: Name of your Aiven for Apache Kafka service.

API

Use the ServiceUpdate API to enable public CA certificates for SASL authentication on an existing service:

curl -X PUT "https://api.aiven.io/v1/project/{project_name}/service/{service_name}" \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"user_config": {"letsencrypt_sasl": true}}'

For PrivateLink, use letsencrypt_sasl_privatelink instead of letsencrypt_sasl.

Parameters:

• project_name: Name of your Aiven project.
• service_name: Name of your Aiven for Apache Kafka service.
• API_TOKEN: Personal Aiven token.
• letsencrypt_sasl: Set to true to enable public CA certificates for SASL authentication.

Terraform

This Terraform example enables SASL authentication and public CA for SASL on a Kafka service. It configures SCRAM-SHA-256 and includes a data source that outputs the SASL port for connections that use the public CA.

The complete example is available in the Aiven Terraform Provider repository on GitHub.

Loading...

To apply your Terraform configuration:

1. Initialize Terraform by running:

   terraform init

   The output is similar to the following:

   
   Initializing the backend...
   
   Initializing provider plugins...
   - Finding aiven/aiven versions matching ">= 4.0.0, < 5.0.0"...
   - Installing aiven/aiven v4.9.2...
   - Installed aiven/aiven v4.9.2
   ...
   Terraform has been successfully initialized!
   ...

2. To create an execution plan and preview the changes, run:

   terraform plan

3. To deploy your changes, run:

   terraform apply --auto-approve

note

• The public certificate is issued and validated by Let's Encrypt, a widely trusted certification authority. For details, see How it works.

• When enabling the public CA over a PrivateLink connection, network configuration may take several minutes before clients can connect. A new port must be allocated and the load balancer route table updated before clients can connect.

Related pages

• Enable OAuth 2.0/OIDC authentication for Apache Kafka
• Authentication types