AsyncAPI Security Schemes — Complete Guide

In this tutorial, you will learn about AsyncAPI Security Schemes. We cover key concepts, practical examples, and best practices to help you master this topic.

Security schemes in AsyncAPI define how clients authenticate with message brokers and servers. Proper security documentation ensures that consumers know exactly how to connect securely.

What You'll Learn

• Security scheme types in AsyncAPI
• API key authentication
• OAuth2 and Openid Connect
• SASL authentication for Kafka
• Applying security to servers

Why It Matters

Message brokers handle sensitive data. Documenting security requirements ensures that consumers implement correct authentication, preventing unauthorized access and data breaches.

Real-World Use

A financial services company documents SASL/SCRAM authentication for their Kafka clusters in AsyncAPI specs. Each service team configures their clients from the spec, ensuring consistent authentication across all consumers.

Flow Chart

flowchart LR
    A[Client] --> B{Security Scheme}
    B --> C[API Key]
    B --> D[OAuth2]
    B --> E[OpenID Connect]
    B --> F[SASL]
    B --> G[User/Password]
    C --> H[Broker]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[Authenticated]

Code Examples

Example 1: Multiple Security Schemes

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      description: API key for service-to-service auth
      name: X-API-Key

    oauth2:
      type: oauth2
      description: OAuth2 client credentials
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/token
          scopes:
            events.read: Read event streams
            events.write: Write to event streams

    scramSha256:
      type: scramSha256
      description: SASL/SCRAM-SHA-256 for Kafka

    openIdConnect:
      type: openIdConnect
      description: OpenID Connect authentication
      openIdConnectUrl: https://auth.example.com/.well-known/openid-configuration

    userPassword:
      type: userPassword
      description: Basic username/password auth

servers:
  production:
    url: kafka://events.example.com:9092
    protocol: kafka
    security:
      - scramSha256: []
  broker:
    url: amqp://rabbitmq.example.com:5672
    protocol: amqp
    security:
      - userPassword: []

Expected output: Documented security schemes for Kafka (SASL/SCRAM), RabbitMQ (user/password), and OAuth2 for web clients.

Example 2: Applying Security with Scopes

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/auth
          tokenUrl: https://auth.example.com/token
          scopes:
            orders.read: View order events
            orders.write: Create order events
            orders.admin: Administer order processing

servers:
  production:
    url: kafka://orders.example.com:9092
    protocol: kafka
    security:
      - oauth2:
          - orders.read
          - orders.write
  admin:
    url: kafka://admin.example.com:9092
    protocol: kafka
    security:
      - oauth2:
          - orders.admin

Expected output: Different servers with different OAuth2 scopes, controlling access based on the required permission level.

Example 3: Kafka SASL with Multiple Mechanisms

components:
  securitySchemes:
    saslPlain:
      type: plain
      description: SASL/PLAIN authentication
    saslScramSha256:
      type: scramSha256
      description: SASL/SCRAM-SHA-256
    saslScramSha512:
      type: scramSha512
      description: SASL/SCRAM-SHA-512
    saslGssapi:
      type: gssapi
      description: SASL/GSSAPI (Kerberos)
    saslOauthBearer:
      type: oauthBearer
      description: SASL/OAUTHBEARER

servers:
  primary:
    url: kafka://primary.example.com:9092
    protocol: kafka
    security:
      - saslScramSha256: []
  legacy:
    url: kafka://legacy.example.com:9092
    protocol: kafka
    security:
      - saslPlain: []
  kerberized:
    url: kafka://secure.example.com:9092
    protocol: kafka
    security:
      - saslGssapi: []

Expected output: Multiple SASL mechanisms for different Kafka clusters with varying security requirements.

Common Mistakes

Practice Questions

1. What security scheme types does AsyncAPI support?
2. How do you apply OAuth2 scopes to specific servers?
3. What is the difference between apiKey in header vs in query?
4. How does SASL authentication work with Kafka in AsyncAPI?
5. How do you document multiple security requirements?

Challenge

Design a multi-environment security Strategy for a healthcare event platform. Include OAuth2 with HIPAA-scoped access for production, API key for staging, and anonymous access for development. Document SASL/SCRAM for Kafka and mTLS for inter-service communication.

FAQ

Mini Project

Design a complete security architecture for a multi-tenant event platform with three tiers: free (API key), business (OAuth2), and enterprise (SASL/SCRAM + mTLS). Create AsyncAPI security scheme definitions for all tiers and document the authentication flow for each.

What's Next

Learn about tags and external documentation in AsyncAPI