asyncapi / asyncapi/bindings

[FEATURE] Kafka: add principal field to operation binding for ACL documentation

Open Beginner friendly
#302 2 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
No language data
Stars
79
Forks
81
PR merge metrics
No merged PRs in 30d

Description

### Why do we need this improvement?

Kafka access is controlled via ACLs, but there is no way to document which
principal an operation requires in an AsyncAPI document. Teams have to look
outside the spec to find out what service account to use and what permissions
to request.

### How will this change help?

The principal and its required permission become part of the contract.
The permission direction is already implicit in the operation `action`:
`send` implies write, `receive` implies read.

Tooling that generates Kafka ACLs or RBAC assignments from AsyncAPI documents
can derive the full access rule from the operation alone.

### Screenshots

_No response_

### How could it be implemented/designed?

Add a single `principal` string field to the Operation Binding Object.

| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
| `principal` | string | The Kafka principal (service account or user) that requires access to perform this operation. | OPTIONAL | The implied permission is `write` for `send` operations and `read` for `receive` operations. |

Example:

```yaml
operations:
publishPaymentEvent:
action: send
bindings:
kafka:
principal: 'payments-service'
bindingVersion: '0.6.0'

consumePaymentEvents:
action: receive
bindings:
kafka:
principal: 'payments-service'
bindingVersion: '0.6.0'
```

In `spec-json-schemas`, the addition to `operation.json` is straightforward:

```json
"principal": {
"type": "string",
"description": "The Kafka principal (service account or user) that requires access to perform this operation. The implied permission is write for send operations and read for receive operations."
}
```

### 🚧 Breaking changes

No

### 👀 Have you checked for similar open issues?

- [x] I checked and didn't find a similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Research direction

Start with spec-json-schemas/operation.json, where the issue identifies the required schema change. Add the optional principal field with its stated description and constraints, then verify the provided send and receive examples validate and that the operation binding schema accepts the new field.

Written by the indexing model from the issue text.

Assessment

Tech stack
kafka
Domain
api
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.