Describing Kafka security in AsyncAPI

The new version of AsyncAPI, 2.1.0, was released today. One of the updates is that it lets you describe Kafka security mechanisms and protocols. In this post, I’ll show how you can do this, and how it relates to configuring a Kafka client.

Kafka config means AsyncAPI
sasl.mechanism security.protocol encryption? auth? server protocol security scheme type
unset PLAINTEXT no no kafka
PLAIN SASL_PLAINTEXT no yes, using SASL/PLAIN kafka plain
SCRAM-SHA-256 SASL_PLAINTEXT no yes, using SASL/SCRAM kafka scramSha256
SCRAM-SHA-512 SASL_PLAINTEXT no yes, using SASL/SCRAM kafka scramSha512
OAUTHBEARER SASL_PLAINTEXT no yes, using OAuth kafka oauth2
GSSAPI SASL_PLAINTEXT no yes, using GSSAPI kafka gssapi
unset SSL yes no kafka-secure
PLAIN SASL_SSL yes yes, using SASL/PLAIN kafka-secure plain
SCRAM-SHA-256 SASL_SSL yes yes, using SASL/SCRAM kafka-secure scramSha256
SCRAM-SHA-512 SASL_SSL yes yes, using SASL/SCRAM kafka-secure scramSha512
OAUTHBEARER SASL_SSL yes yes, using OAuth kafka-secure oauth2
GSSAPI SASL_SSL yes yes, using GSSAPI kafka-secure gssapi
unset SSL yes yes, using mutual TLS kafka-secure X509

What that table is obviously missing is some unnecessary interactivity!

This means that if you need to configure your Kafka client with these properties:

=
=

And would configure a Java Kafka client like this:

Properties props = new Properties();
props.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, 
          "mykafkacluster.org:8092");
props.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG,
          "");
props.put(SaslConfigs.SASL_MECHANISM,
          "");
...

Then you should describe this in an AsyncAPI document like this:

asyncapi: 2.1.0
info:
  title: My Kafka topic
  version: 1.0.0
servers:
  demo:
    url: mykafkacluster.org:8092
    protocol: 
    security:
      - mySecurity: []
components:
  securitySchemes:
    mySecurity:
      type: 
channels:
  MY.TOPIC:
    subscribe:
      message:
        name: myMessage
        payload:
          type: object
          properties:
            val:
              type: string

For more info about what is new in AsyncAPI 2.1.0, check out the release notes.

Tags: , ,

Leave a Reply