From 158f16e90e3577cfd9d7bda50338bf65925bedcf Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Sep 2023 21:48:54 +0530 Subject: [PATCH 01/14] added securing-operations --- .../concepts/asyncapi-document/_section.md | 4 ++ .../asyncapi-document/securing-operations.md | 49 +++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/securing-operations.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md new file mode 100644 index 000000000000..3873e954ac1b --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -0,0 +1,4 @@ +--- +title: Securing Operations +weight: 150 +--- 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 000000000000..a597e5d145b3 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -0,0 +1,49 @@ +In an AsyncAPI document, the concept of server security implies that the security measures defined at the server level apply to all operations within all channels by default. + +## Features of Security in AsyncAPI Documents + +- The security requirements specified at the server level are enforced consistently across the entire API. + +- There may be situations where certain operations within specific channels require different security measures than the default server-level settings. + +- To accommodate such scenarios, AsyncAPI allows you to use the security property at the operation level. + +- By using the security property at the operation level, you can override the default server-level security and define unique security requirements for individual operations. + +- Gives the flexibility to tailor the security measures to the specific needs of each operation, even if they differ from the broader server-level settings. + +- When you include the security property at the operation level, it takes precedence over the server-level security settings for that particular operation. + +- The security measures specified at the operation level will be applied instead of the default server-level security. + +## 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. +However, you want to enforce OAuth2 authentication specifically for the getUser operation. + +You can achieve this by including the security property at the operation level, as shown in the following example: + +``` +channels: + users: + publish: + summary: Creates a user + operationId: createUser + message: + ... + subscribe: + summary: Retrieves user information + operationId: getUser + message: + ... + security: + - OAuth2: [] +``` + +In this 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. \ No newline at end of file From c2e2fa9bc5bdf287124430148c83104c2c27bb79 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:43:56 +0530 Subject: [PATCH 02/14] Update pages/docs/concepts/asyncapi-document/_section.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/_section.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md index 3873e954ac1b..f01706f4b7dc 100644 --- a/pages/docs/concepts/asyncapi-document/_section.md +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -1,4 +1,4 @@ --- -title: Securing Operations +title: AsyncAPI Document weight: 150 --- From fa01502b7d7ed935a77c8e6a79f478648ece218e Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:44:05 +0530 Subject: [PATCH 03/14] Update pages/docs/concepts/asyncapi-document/_section.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/_section.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md index f01706f4b7dc..390923616acb 100644 --- a/pages/docs/concepts/asyncapi-document/_section.md +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -1,4 +1,4 @@ --- title: AsyncAPI Document -weight: 150 +weight: 50 --- From cd1f0092c05182334faba33b31271626ef68f950 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:44:43 +0530 Subject: [PATCH 04/14] Update pages/docs/concepts/asyncapi-document/securing-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/securing-operations.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index a597e5d145b3..1c4f0db10631 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -1,3 +1,8 @@ +--- +title: 'Securing Operations' +weight: 120 +--- + In an AsyncAPI document, the concept of server security implies that the security measures defined at the server level apply to all operations within all channels by default. ## Features of Security in AsyncAPI Documents From d33fcffb7e8969ebd8a7c95f704b90f7104ba692 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:44:53 +0530 Subject: [PATCH 05/14] Update pages/docs/concepts/asyncapi-document/securing-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/securing-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 1c4f0db10631..5abb1ec87925 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -7,7 +7,7 @@ In an AsyncAPI document, the concept of server security implies that the securit ## Features of Security in AsyncAPI Documents -- The security requirements specified at the server level are enforced consistently across the entire API. +- 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. From 70de11fff6468f46f88839f61dd6b04b79814681 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:45:23 +0530 Subject: [PATCH 06/14] Update pages/docs/concepts/asyncapi-document/securing-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- .../asyncapi-document/securing-operations.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 5abb1ec87925..38fb51c6111a 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -9,17 +9,9 @@ In an AsyncAPI document, the concept of server security implies that the securit - 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. +There may be situations where certain operations within specific channels require different security measures than the default server-level settings. To accommodate for such scenarios, AsyncAPI document allows you to use the `security` property at the `operation` level. -- To accommodate such scenarios, AsyncAPI allows you to use the security property at the operation level. - -- By using the security property at the operation level, you can override the default server-level security and define unique security requirements for individual operations. - -- Gives the flexibility to tailor the security measures to the specific needs of each operation, even if they differ from the broader server-level settings. - -- When you include the security property at the operation level, it takes precedence over the server-level security settings for that particular operation. - -- The security measures specified at the operation level will be applied instead of the default server-level security. +By using the `security` property at the `operation` level, you can override the default server-level security and define unique security requirements for individual operations. Thereby also giving you the flexibility to tailor the security measures to the specific needs of each operation, even if they differ from the broader server-level settings. ## Specifying Security Requirement From 31efa9437d90c4549413be77a9a901449e5a0296 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:45:32 +0530 Subject: [PATCH 07/14] Update pages/docs/concepts/asyncapi-document/securing-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/securing-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 38fb51c6111a..39f62945aefd 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -24,7 +24,7 @@ However, you want to enforce OAuth2 authentication specifically for the getUser You can achieve this by including the security property at the operation level, as shown in the following example: -``` +```yaml channels: users: publish: From 2efe7b5b08fea0553d1f99e7b34d7efc93080cce Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:45:49 +0530 Subject: [PATCH 08/14] Update pages/docs/concepts/asyncapi-document/securing-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/securing-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 39f62945aefd..dcda066525d2 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -15,7 +15,7 @@ By using the `security` property at the `operation` level, you can override the ## Specifying Security Requirement -To specify different security requirements for a specific operation, you can include the security property within the operation's definition. +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. From 3f067e39a335a4bd74d5910982d1d52556470b61 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:46:18 +0530 Subject: [PATCH 09/14] Update pages/docs/concepts/asyncapi-document/securing-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/securing-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index dcda066525d2..8b738ba2095b 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -41,6 +41,6 @@ channels: - OAuth2: [] ``` -In this 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. +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. \ No newline at end of file From 77b8e967f3b28ff3a100379ec284058bacdc3bff Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Thu, 23 Nov 2023 12:07:37 +0530 Subject: [PATCH 10/14] added description on both ways to add security to operations --- .../asyncapi-document/securing-operations.md | 45 +++++++++++++++++-- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 8b738ba2095b..488132e189de 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -7,11 +7,48 @@ In an AsyncAPI document, the concept of server security implies that the securit ## Features of Security in AsyncAPI Documents -- The security requirements specified at the server level are enforced consistently across the entire asyncapi document. +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. -There may be situations where certain operations within specific channels require different security measures than the default server-level settings. To accommodate for such scenarios, AsyncAPI document allows you to use the `security` property at the `operation` level. +- 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. + By using the `security` property at the `operation` level, the user can override the default server-level security and define unique security requirements for individual operations. This also gives the flexibility to tailor the security measures to the specific needs of each operation, even if they differ from the broader server-level settings. -By using the `security` property at the `operation` level, you can override the default server-level security and define unique security requirements for individual operations. Thereby also giving you the flexibility to tailor the security measures to the specific needs of each operation, even if they differ from the broader server-level settings. +```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' +``` ## Specifying Security Requirement @@ -43,4 +80,4 @@ channels: 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. \ No newline at end of file +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 ad971892e5a8f1dd98d2deec687a63a03c922cd2 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Thu, 23 Nov 2023 12:10:22 +0530 Subject: [PATCH 11/14] shortened header as per suggestions --- pages/docs/concepts/asyncapi-document/securing-operations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 488132e189de..9d229cd316b6 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -3,9 +3,9 @@ title: 'Securing Operations' weight: 120 --- -In an AsyncAPI document, the concept of server security implies that the security measures defined at the server level apply to all operations within all channels by default. +The concept of server security implies that the security measures defined at the server level apply to all operations within all channels by default. -## Features of Security in AsyncAPI Documents +## 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. From 96357434ed736f3962963e511c66cddbe6ff1814 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Thu, 23 Nov 2023 12:38:46 +0530 Subject: [PATCH 12/14] replaced v2 examples with v3 ones --- .../asyncapi-document/securing-operations.md | 26 +++++++------------ 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 9d229cd316b6..d0cabc8f3526 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -55,27 +55,21 @@ operations: 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. +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. However, you want to enforce OAuth2 authentication specifically for the getUser operation. -You can achieve this by including the security property at the operation level, as shown in the following example: +The following example explains how to include security requirement for operations definition ```yaml -channels: - users: - publish: - summary: Creates a user - operationId: createUser - message: - ... - subscribe: - summary: Retrieves user information - operationId: getUser - message: - ... - security: - - OAuth2: [] +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. From 559358670bb3632e2ee46b2b11107b17051d3f39 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Thu, 23 Nov 2023 13:12:42 +0530 Subject: [PATCH 13/14] added objects under security in v3 --- .../docs/concepts/asyncapi-document/securing-operations.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index d0cabc8f3526..3a33785518cc 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -10,7 +10,6 @@ The concept of server security implies that the security measures defined at the 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. - By using the `security` property at the `operation` level, the user can override the default server-level security and define unique security requirements for individual operations. This also gives the flexibility to tailor the security measures to the specific needs of each operation, even if they differ from the broader server-level settings. ```yaml channels: @@ -50,6 +49,12 @@ 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. + ## Specifying Security Requirement To specify different security requirements for a specific operation, you can include the `security` property within the operation's definition. From 13ae5ac849ea45de6487912145996386cb5f4aab Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Fri, 24 Nov 2023 10:24:27 +0530 Subject: [PATCH 14/14] removed enforce/override statement --- pages/docs/concepts/asyncapi-document/securing-operations.md | 1 - 1 file changed, 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/securing-operations.md b/pages/docs/concepts/asyncapi-document/securing-operations.md index 3a33785518cc..e0bdbdba35cd 100644 --- a/pages/docs/concepts/asyncapi-document/securing-operations.md +++ b/pages/docs/concepts/asyncapi-document/securing-operations.md @@ -62,7 +62,6 @@ The security property is an array where you can define one or more security requ 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. -However, you want to enforce OAuth2 authentication specifically for the getUser operation. The following example explains how to include security requirement for operations definition