From 796683b1927a6c65ee5df277cee01515376d1f2c Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Thu, 7 Dec 2023 21:13:30 +0530 Subject: [PATCH 1/3] adding content about securing operations --- .../asyncapi-document/securing-operations.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/securing-operations.md diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md new file mode 100644 index 00000000000..6f373a44f09 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -0,0 +1,82 @@ +--- +title: 'Securing Operations' +weight: 120 +--- + +The server security concept implies that the security measures defined at the server level apply to all operations within all channels by default. + +## Security Features + +The security requirements specified at the server level are enforced consistently across the entire Asyncapi document. There may be situations where certain operations within specific channels require different security measures than the default server-level settings. + +- To accommodate such scenarios, the AsyncAPI document allows you to use the `security` property at the `operation` level. This means users can define security requirements at both the global level and the operation (endpoint) level. + +```yaml +channels: + AUTHORIZATION_REVOCATION: + address: AUTHORIZATION_REVOCATION + messages: + subscribe.message: + $ref: '#/components/messages/message' + +security: + - apiKey: [] +``` + +- One more way is when users don't use the `server` feature from AsyncAPI, and only include `channels` and `operations`. In this case, the user needs to specify the security of the operation within the `operations`. + +```yaml +channels: + AUTHORIZATION_REVOCATION: + address: AUTHORIZATION_REVOCATION + messages: + subscribe.message: + $ref: '#/components/messages/message' +operations: + AUTHORIZATION_REVOCATION.subscribe: + action: send + channel: + $ref: '#/channels/AUTHORIZATION_REVOCATION' + security: + - type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + availableScopes: + 'subscribe:auth_revocations': Scope required for authorization revocation topic + scopes: + - 'subscribe:auth_revocations' +``` + +The `security` field comprises of 2 parts - + +- Security scheme object = This portion mentions the security schemes associated with the given operation. One of the security scheme objects must be satisfied to authorize an operation. + +- Reference object = This portion references a definition by linking to somewhere else in the document using the `$ref:` keyword. + +## Specifying Security Requirement + +To specify different security requirements for a specific operation, you can include the `security` property within the operation's definition. +The security property is an array where you can define one or more security requirement objects. + +For example, let's say you have an AsyncAPI document with a channel called users and two operations within that channel: `createUser` and `getUser`. +The server-level security is set to use API key authentication for all operations within all channels. + +The following example explains how to include security requirements for operations definition + +```yaml + +title: User sign up +summary: Action to sign a user up. +description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send +security: + - OAuth2: [] +``` + +In the above example, the `security` property is added under the `getUser` operation, indicating that the OAuth2 security requirement should be applied to that specific operation within the user's channel. The empty array [] signifies that no additional configuration is needed for the OAuth2 security mechanism. + +Utilizing the security property at the operation level allows you to deviate from the server-level security settings and define unique security requirements for individual operations within your AsyncAPI document. The capability ensures that you can adequately secure your API operations, even if they require different security measures. From 89de001309bdee5e691c8510cc2af65c16c07fbd Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Thu, 14 Dec 2023 17:01:57 +0100 Subject: [PATCH 2/3] Update securing-operations.md --- .../asyncapi-document/securing-operations.md | 105 +++++++++--------- 1 file changed, 53 insertions(+), 52 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 6f373a44f09..395cbbee77b 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -1,42 +1,44 @@ --- -title: 'Securing Operations' +title: 'Operation security' weight: 120 --- -The server security concept implies that the security measures defined at the server level apply to all operations within all channels by default. - -## Security Features - -The security requirements specified at the server level are enforced consistently across the entire Asyncapi document. There may be situations where certain operations within specific channels require different security measures than the default server-level settings. - -- To accommodate such scenarios, the AsyncAPI document allows you to use the `security` property at the `operation` level. This means users can define security requirements at both the global level and the operation (endpoint) level. - -```yaml -channels: - AUTHORIZATION_REVOCATION: - address: AUTHORIZATION_REVOCATION - messages: - subscribe.message: - $ref: '#/components/messages/message' - -security: - - apiKey: [] +The server security concept implies that the security measures defined at the server level apply to all operations within all channels by default. To change that default behaviour for specific operation, you need to apply security information directly on that operation. + +## Add security + +To accommodate such scenarios, the AsyncAPI document allows you to use the `security` field at the `operation` level. You can have multiple security schemes but only one must be satisfied to authorize such operation. + +The diagram below describes how to use reusable security schemes: + +```mermaid +graph LR + C[components] + F[address] + I[messages] + A[components] + B[securitySchemes] + D[security] + C --> F + C --> I + C --> D + D --> |$ref| B + A --> B + + style C fill:#47BCEE,stroke:#000; + style D fill:#47BCEE,stroke:#000; ``` -- One more way is when users don't use the `server` feature from AsyncAPI, and only include `channels` and `operations`. In this case, the user needs to specify the security of the operation within the `operations`. +## Operation section + +Operation security information is represented by [Security scheme](/docs/reference/specification/v3.0.0#securitySchemeObject) on operation level. You can also use `$ref` keyword to reference the scheme stored in different location, like for example `components.securitySchemes`. ```yaml -channels: - AUTHORIZATION_REVOCATION: - address: AUTHORIZATION_REVOCATION - messages: - subscribe.message: - $ref: '#/components/messages/message' operations: - AUTHORIZATION_REVOCATION.subscribe: + sendAuthRevoke: action: send channel: - $ref: '#/channels/AUTHORIZATION_REVOCATION' + $ref: '#/channels/authRevoke' security: - type: oauth2 description: The oauth security descriptions @@ -49,34 +51,33 @@ operations: - 'subscribe:auth_revocations' ``` -The `security` field comprises of 2 parts - - -- Security scheme object = This portion mentions the security schemes associated with the given operation. One of the security scheme objects must be satisfied to authorize an operation. - -- Reference object = This portion references a definition by linking to somewhere else in the document using the `$ref:` keyword. +Above example shows an `sendAuthRevoke` operation from AsyncAPI document that explains what operations client app can perform with existing notification service. In case there would be a server with separate server security, operation must satisfy it as well. -## Specifying Security Requirement +## `securitySchemes` section -To specify different security requirements for a specific operation, you can include the `security` property within the operation's definition. -The security property is an array where you can define one or more security requirement objects. - -For example, let's say you have an AsyncAPI document with a channel called users and two operations within that channel: `createUser` and `getUser`. -The server-level security is set to use API key authentication for all operations within all channels. - -The following example explains how to include security requirements for operations definition +To reuse security schemes between operations, place them in `components.securitySchemes` and reference through `$ref` keyword in your operation: ```yaml +operations: + sendAuthRevoke: + action: send + channel: + $ref: '#/channels/authRevoke' + security: + - $ref: '#/components/securitySchemes/oauth' -title: User sign up -summary: Action to sign a user up. -description: A longer description -channel: - $ref: '#/channels/userSignup' -action: send -security: - - OAuth2: [] +components: + securitySchemes: + oauth: + type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + availableScopes: + 'subscribe:auth_revocations': Scope required for authorization revocation topic + scopes: + - 'subscribe:auth_revocations' ``` -In the above example, the `security` property is added under the `getUser` operation, indicating that the OAuth2 security requirement should be applied to that specific operation within the user's channel. The empty array [] signifies that no additional configuration is needed for the OAuth2 security mechanism. - -Utilizing the security property at the operation level allows you to deviate from the server-level security settings and define unique security requirements for individual operations within your AsyncAPI document. The capability ensures that you can adequately secure your API operations, even if they require different security measures. +With above approach you can reuse scheme within multiple operations, even across multiple AsyncAPI documents. From 7db80620ce4e0cf4ab3c20093218c88e22d6a3a1 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 15 Dec 2023 21:10:05 -0800 Subject: [PATCH 3/3] tw editorial fixes --- .../asyncapi-document/securing-operations.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 395cbbee77b..c6619832a48 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -3,13 +3,13 @@ title: 'Operation security' weight: 120 --- -The server security concept implies that the security measures defined at the server level apply to all operations within all channels by default. To change that default behaviour for specific operation, you need to apply security information directly on that operation. +The server security concept in AsyncAPI means that the security settings specified at the server level automatically apply to all operations across all channels. If you want to modify these default security settings for a particular operation, you need to specify the security details directly on that operation. ## Add security -To accommodate such scenarios, the AsyncAPI document allows you to use the `security` field at the `operation` level. You can have multiple security schemes but only one must be satisfied to authorize such operation. +To accommodate such scenarios, the AsyncAPI document allows you to use the `security` field at the `operation` level. You can have multiple security schemes, but only one must be satisfied to authorize such an operation. -The diagram below describes how to use reusable security schemes: +The diagram below describes how to implement reusable security schemes: ```mermaid graph LR @@ -31,7 +31,7 @@ graph LR ## Operation section -Operation security information is represented by [Security scheme](/docs/reference/specification/v3.0.0#securitySchemeObject) on operation level. You can also use `$ref` keyword to reference the scheme stored in different location, like for example `components.securitySchemes`. +Security information for an operation is defined using a [Security Scheme](/docs/reference/specification/v3.0.0#securitySchemeObject) at the operation level. You can reference a scheme from another location, such as `components.securitySchemes`, using the `$ref` keyword. ```yaml operations: @@ -51,11 +51,11 @@ operations: - 'subscribe:auth_revocations' ``` -Above example shows an `sendAuthRevoke` operation from AsyncAPI document that explains what operations client app can perform with existing notification service. In case there would be a server with separate server security, operation must satisfy it as well. +The previous example, featuring the `sendAuthRevoke` operation in an AsyncAPI document, demonstrates the capabilities of a client application with an existing notification service. If a server has its own security requirements, this operation must also comply with those. ## `securitySchemes` section -To reuse security schemes between operations, place them in `components.securitySchemes` and reference through `$ref` keyword in your operation: +To reuse security schemes between operations, place them in `components.securitySchemes` and reference them via the `$ref` keyword in your operation: ```yaml operations: @@ -80,4 +80,4 @@ components: - 'subscribe:auth_revocations' ``` -With above approach you can reuse scheme within multiple operations, even across multiple AsyncAPI documents. +The previous code snippet shows the approach for reusing schema within multiple operations, even across multiple AsyncAPI documents.