feat: add security at the operation level

examples/operation-security.yml

@@ -0,0 +1,106 @@
+asyncapi: 2.4.0
+info:
+  title: Notifications
+  version: 1.0.0
+  description: >-
+    This contract defines HTTP Push notification for 
+    application authorization revocation topic
+channels:
+  AUTHORIZATION_REVOCATION:
+    subscribe:
+      message:
+        $ref: '#/components/messages/message'
+      bindings:
+        http:
+          type: request
+          method: POST
+          headers:
+            type: object
+            properties:
+              Content-Type:
+                type: string
+                enum:
+                  - application/json
+      security:
+        petstore_auth:
+          - subscribe:auth_revocations
+components:
+  messages:
+    message:
+      headers:
+        type: object
+        properties:
+          X-SIGNATURE:
+            description: ECC message signature
+            type: string
+      payload:
+        type: object
+        properties:
+          metadata:
+            $ref: '#/components/schemas/MetaData'
+          notification:
+            $ref: '#/components/schemas/Notification'
+  schemas:
+    MetaData:
+      type: object
+      properties:
+        topic:
+          type: string
+          description: Topic subscribed to.
+        schemaVersion:
+          type: string
+          description: The schema for this topic.
+        deprecated:
+          type: boolean
+          description: If this is a deprecated schema or topic.
+          default: 'false'
+    Notification:
+      type: object
+      properties:
+        notificationId:
+          type: string
+          description: The notification Id.
+        eventDate:
+          type: string
+          description: The event date associated with this notification in UTC.
+        publishDate:
+          type: string
+          description: The message publish date in UTC.
+        publishAttemptCount:
+          type: integer
+          description: The number of attempts made to publish this message.
+        data:
+          $ref: '#/components/schemas/AuthorizationRevocationData'
+    AuthorizationRevocationData:
+      type: object
+      description: The Authorization Revocation payload.
+      properties:
+        username:
+          type: string
+          description: The username for the user.
+        userId:
+          type: string
+          description: The immutable public userId for the user
+        eiasToken:
+          type: string
+          description: The legacy eiasToken specific to the user
+        revokeReason:
+          type: string
+          enum:
+            - REVOKED_BY_APP
+            - REVOKED_BY_USER
+            - REVOKED_BY_ADMIN
+            - PASSWORD_CHANGE
+          description: The reason for authorization revocation
+        revocationDate:
+          type: string
+          description: Date and time when the authorization was revoked
+  securitySchemes:
+    petstore_auth:
+      type: oauth2
+      description: The oauth security descriptions
+      flows:
+        clientCredentials:
+          tokenUrl: 'https://example.com/api/oauth/dialog'
+          scopes:
+            subscribe:auth_revocations: Scope required for authorization revocation topic

examples/streetlights-operation-security.yml

@@ -0,0 +1,202 @@
+asyncapi: '2.4.0'
+info:
+  title: Streetlights Kafka API
+  version: '1.0.0'
+  description: |
+    The Smartylighting Streetlights API allows you to remotely manage the city lights.
+
+    ### Check out its awesome features:
+
+    * Turn a specific streetlight on/off 🌃
+    * Dim a specific streetlight 😎
+    * Receive real-time information about environmental lighting conditions 📈
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0
+
+servers:
+  test:
+    url: test.mykafkacluster.org:8092
+    protocol: kafka-secure
+    description: Test broker
+    security:
+      - saslScram: []
+  test_oauth:
+    url: test.mykafkacluster.org:8093
+    protocol: kafka-secure
+    description: Test port for oauth 
+    security:
+      - streetlights_auth:
+         - streetlights:write
+         - streetlights:read
+
+
+defaultContentType: application/json
+
+channels:
+  smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured:
+    description: The topic on which measured values may be produced and consumed.
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    publish:
+      summary: Inform about environmental lighting conditions of a particular streetlight.
+      operationId: receiveLightMeasurement
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/lightMeasured'
+      security:
+       streetlights_auth:
+         - streetlights:write  
+  smartylighting.streetlights.1.0.action.{streetlightId}.turn.on:
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    subscribe:
+      operationId: turnOn
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/turnOnOff'
+      security:
+      # This operation level security implies the ability to send a message to 
+      # `smartylighting.streetlights.1.0.action.{streetlightId}.turn.on` with Authorization headers 
+      # with `streetlights:read` scope. It is also possible for the same channel when using `test_auth` 
+      # server to instead use credentials for security (scramSha256 in this example) specified on the server level
+       streetlights_auth:
+         - streetlights:read  
+
+  smartylighting.streetlights.1.0.action.{streetlightId}.turn.off:
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    subscribe:
+      operationId: turnOff
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/turnOnOff'
+      security:
+       streetlights_auth:
+         - streetlights:read    
+  smartylighting.streetlights.1.0.action.{streetlightId}.dim:
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    subscribe:
+      operationId: dimLight
+      traits:
+        - $ref: '#/components/operationTraits/kafka'
+      message:
+        $ref: '#/components/messages/dimLight'
+      security:
+      # This operation level security implies the ability to send a message to 
+      # `smartylighting.streetlights.1.0.action.{streetlightId}.turn.on` with Authorization headers 
+      # with `streetlights:read` scope. It is also possible for the same channel when using `test_auth` 
+      # server to instead use credentials for security (scramSha256 in this example) specified on the server level
+       streetlights_auth:
+         - streetlights:read  
+
+
+components:
+  messages:
+    lightMeasured:
+      name: lightMeasured
+      title: Light measured
+      summary: Inform about environmental lighting conditions of a particular streetlight.
+      contentType: application/json
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: "#/components/schemas/lightMeasuredPayload"
+    turnOnOff:
+      name: turnOnOff
+      title: Turn on/off
+      summary: Command a particular streetlight to turn the lights on or off.
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: "#/components/schemas/turnOnOffPayload"
+    dimLight:
+      name: dimLight
+      title: Dim light
+      summary: Command a particular streetlight to dim the lights.
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: "#/components/schemas/dimLightPayload"
+
+  schemas:
+    lightMeasuredPayload:
+      type: object
+      properties:
+        lumens:
+          type: integer
+          minimum: 0
+          description: Light intensity measured in lumens.
+        sentAt:
+          $ref: "#/components/schemas/sentAt"
+    turnOnOffPayload:
+      type: object
+      properties:
+        command:
+          type: string
+          enum:
+            - on
+            - off
+          description: Whether to turn on or off the light.
+        sentAt:
+          $ref: "#/components/schemas/sentAt"
+    dimLightPayload:
+      type: object
+      properties:
+        percentage:
+          type: integer
+          description: Percentage to which the light should be dimmed to.
+          minimum: 0
+          maximum: 100
+        sentAt:
+          $ref: "#/components/schemas/sentAt"
+    sentAt:
+      type: string
+      format: date-time
+      description: Date and time when the message was sent.
+
+  securitySchemes:
+    saslScram:
+      type: scramSha256
+      description: Provide your username and password for SASL/SCRAM authentication
+    streetlights_auth:
+      type: oauth2
+      description: The oauth security descriptions
+      flows:
+       clientCredentials:
+        tokenUrl: 'https://example.com/api/oauth/dialog'
+        scopes:
+          streetlights:read: Scope required for subscribing to channel
+          streetlights:write: Scope required for publishing to channel
+
+  parameters:
+    streetlightId:
+      description: The ID of the streetlight.
+      schema:
+        type: string
+
+  messageTraits:
+    commonHeaders:
+      headers:
+        type: object
+        properties:
+          my-app-header:
+            type: integer
+            minimum: 0
+            maximum: 100
+
+  operationTraits:
+    kafka:
+      bindings:
+        kafka:
+          clientId:
+            type: string
+            enum: ['my-app-id']

spec/asyncapi.md

@@ -703,7 +703,8 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="operationObjectOperationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
 <a name="operationObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
-<a name="operationObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
+<a name="operationObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
+<a name="operationObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.
 <a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.
 <a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationObjectBindings"></a>bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
@@ -719,6 +720,14 @@ This object can be extended with [Specification Extensions](#specificationExtens
   "operationId": "registerUser",
   "summary": "Action to sign a user up.",
   "description": "A longer description",
+  "security": [
+    {
+     "petstore_auth": [
+       "write:pets",
+       "read:pets"
+     ]
+    }
+  ],
   "tags": [
     { "name": "user" },
     { "name": "signup" },
@@ -761,6 +770,10 @@ This object can be extended with [Specification Extensions](#specificationExtens
 operationId: registerUser
 summary: Action to sign a user up.
 description: A longer description
+security:
+  - petstore_auth:
+    - write:pets
+    - read:pets
 tags:
   - name: user
   - name: signup
@@ -802,6 +815,7 @@ Field Name | Type | Description
 <a name="operationTraitObjectOperationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
 <a name="operationTraitObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
 <a name="operationTraitObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
+<a name="operationTraitObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.
 <a name="operationTraitObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.
 <a name="operationTraitObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationTraitObjectBindings"></a>bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.