asyncapi / asyncapi/spec

Support AND logic for multiple security schemes in AsyncAPI 3.x

Open
#1,129 7 comments 0 reactions 0 assignees View on GitHub
💡 Proposal (RFC 1)
Dominant language
JavaScript
Stars
5.3k
Forks
382
Avg merge
7m
Merged PRs (30d)
4

Description

## Problem
Currently, AsyncAPI 3.x only allows expressing OR semantics between multiple security schemes using the security array:

```
security:
- $ref: '#/components/securitySchemes/saslScram'
- $ref: '#/components/securitySchemes/mtls'
```

This means either SASL/SCRAM or mTLS can authorize a connection.
However, in many real-world scenarios, a server or operation may require multiple authentication schemes simultaneously (logical AND), for example:
SASL/SCRAM and a valid client certificate (mTLS) for a Kafka broker

Currently, there is no spec-compliant way to enforce both requirements in AsyncAPI 3.x without using a vendor extension (x- fields) or describing it only in prose. This limitation prevents full machine-readable documentation and automated validation of multi-factor authentication requirements.

## Current workarounds
1. Use only one $ref and describe the second requirement in description
Pros: Spec-compliant
Cons: Not machine-enforceable, tooling cannot validate
2. Vendor extension
Pros: Documents AND requirement
Cons: Non-standard, tooling may ignore it
Neither approach is ideal for consistent, spec-compliant multi-scheme security modeling.

## Proposal
Introduce a native, spec-supported syntax to express AND logic between multiple security schemes in a single security requirement object. Possible approaches:
1. Array of $refs array.
```
security:
- - $ref: '#/components/securitySchemes/saslScram'
- $ref: '#/components/securitySchemes/mtls'
```
2. Named keys with logical AND semantics (similar to v2):
```
security:
- saslScram: []
mtls: []
```
Requirements for tooling: Studio, CLI validator, and generators should enforce that all schemes in a single requirement object are required.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the AsyncAPI 3.x security array and security requirement objects, then compare the two proposed AND syntaxes. Trace the stated impact on Studio, the CLI validator, and generators; done means a single spec-supported syntax and clear enforcement requirements are agreed.

Written by the indexing model from the issue text.

Assessment

Domain
authentication, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.