Add security mechanism info to Kafka bindings for server objects

[dalelane]

Is your feature request related to a problem? Please describe.
Kafka has several values that are essential to know when preparing to connect to a secured Kafka cluster, such as sasl.mechanism and security.protocol. Adding these to the Kafka binding for server objects would allow these to be documented.

Can't it be tackled using specification extensions?
It could be captured in extensions.

e.g.

asyncapi: '2.0.0'
...
servers:
  production:
    url: localhost:9092
    protocol: kafka-secure
    security:
    - saslScramCreds: []
...
components:
  securitySchemes:
    saslScramCreds:
      type: userPassword
      x-mykafka-sasl-mechanism: 'SCRAM-SHA-256'
      x-mykafka-security-protocol: 'SASL_SSL'

However I think this is a common enough request that there would be value in doing it in a consistent way. In particular, it would enable code generation to set up the right Kafka client properties.

Describe the solution you'd like
Strawman suggestion:

asyncapi: '2.0.0'
...
servers:
  production:
    url: localhost:9092
    protocol: kafka-secure
    security:
    - saslScramCreds: []
    bindings:
      kafka:
        saslMechanism: 'SCRAM-SHA-256'
        securityProtocol: 'SASL_SSL'
...
components:
  securitySchemes:
    saslScramCreds:
      type: userPassword

Describe alternatives you've considered
Fran Méndez suggested:

We should make it part of the security schemes, it's not only for Kafka after all.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[magicmatatjahu]

I wonder if adding another security mechanism to the AsyncAPI JSON Schema it makes sense in the long term. I mean looking at this table asyncapi/bindings#56 (comment) I have this problem that we may forget something and will have to tweak it in the AsyncAPI scheme and publish new version etc. Would treating securityScheme as extension cause problems in long term? I mean extension like:

# extension
id: saslSecurityScheme
type: securityScheme # new type of extension
title: ...
...

# spec
components:
  securitySchemes:
    usingSaslSecurityScheme
       type: saslSecurityScheme
       ...

I am aware that the above schema is not fully correct, but I hope that the idea itself is understandable.

@fmvilas @derberg @jonaslagoni @smoya @dalelane Any thoughts?

[fmvilas]

we may forget something and will have to tweak it in the AsyncAPI scheme and publish new version

That's not a problem. Publishing a new version of the JSON Schema definition of the spec is not the same as publishing a new version of the spec. Remember, the spec is only the Markdown file.

[dalelane]

@fmvilas @derberg A few PRs ready for this now:

#502
Update the spec markdown description

asyncapi/spec-json-schemas#53
Update the JSON Schema definition

asyncapi/parser-js#289
Update the JS Parser to use the new JSON Schema definition

[asyncapi-bot]

🎉 This issue has been resolved in version 2.1.0-2021-06-release.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[asyncapi-bot]

🎉 This issue has been resolved in version 2.2.0-2021-06-release.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[jonaslagoni]

I guess we can close this right? 🤔