Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: added content for securing operations #2172

Closed
wants to merge 14 commits into from
Closed
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions pages/docs/concepts/asyncapi-document/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: AsyncAPI Document
weight: 50
---
46 changes: 46 additions & 0 deletions pages/docs/concepts/asyncapi-document/securing-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
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.
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved

## Features of Security in AsyncAPI Documents
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved

- 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 for such scenarios, AsyncAPI document allows you to use the `security` property at the `operation` level.
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved

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.
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved

## 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.
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved
The server-level security is set to use API key authentication for all operations within all channels.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you cannot enforce as it is not about overriding,

it is like providing alternative for what is already in the server. Of course you can do a server without security, then have different operations and channels on the same server, each operation with different security - still, it is not overriding/enforcing if you know what I mean

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am unable to understand how to improve the content as per your suggestions.
could you please attach some examples or maybe give me a bit more info about the same?

Copy link
Collaborator Author

@BhaswatiRoy BhaswatiRoy Nov 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you cannot enforce as it is not about overriding,

it is like providing alternative for what is already in the server. Of course you can do a server without security, then have different operations and channels on the same server, each operation with different security - still, it is not overriding/enforcing if you know what I mean

I have removed the line that stated about enforcing/overriding, though not sure if I still was able to resolved the suggestion.

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:

```yaml
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved
channels:
users:
publish:
summary: Creates a user
operationId: createUser
message:
...
subscribe:
summary: Retrieves user information
operationId: getUser
message:
...
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.