feat: add security at the operation level #584
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
|
@sekharbans-ebay Hello! Please update the title with following Semantic release to something like: Also I think that this PR is related to the #418 issue. |
|
I did change the title as asked - what would be the next steps please? Not sure if I am missing anything else. Thanks |
|
@sekharbans-ebay I meant to change the issue title 😅
Discussion with core team and community, the best place will be here. You should also inform about your PR and point to the mentioned issue in our slack. By this more people will be interested/involved in this topic. I am not the person who can single-handedly approve your changes, so you must wait for the other people :) |
magicmatatjahu
changed the title
There was a problem hiding this comment.
@sekharbans-ebay could you provide some fixes here in the PR?
- look at a failing check, there is an error with PR title
- update PR title that should talk only about operation, not channel
- please extend operation object examples with the new proposed security key
- clarify how should it work if someone provides security on a server object too, what has priority
- I think the operation traits object also needs to be extended
sekharbans-ebay
changed the title
Apologies for the delay in responding - all of the review comments have been incorporated except for the 'operation object example' part. I have followed the approach that 'Server' has - where the examples on Security are referenced and provided in great details in an independent section on Security. The Security aspects are complex and require an independent treatment. Trust that is acceptable. |
sekharbans-ebay
changed the title
|
@sekharbans-ebay I like that you choose the path of being consistent with the spec. In this case though the problem is that we are actually missing an example of security on the server, not a patter that we should follow. To actually find a good example of usage of |
Question on security examples - Since there are different security mechanisms involved, the Security Requirements in the examples can either be repeated for each of oauth, password or api_key else it seems incomplete. As a reader of the specs , I like what you have for server - i.e. pointer to the relevant security part of the specs. If it is acceptable I can add - say only oauth as an example(both json/yaml). For example: |
|
@sekharbans-ebay it is ok to add example for just one security req, oauth is the best example I think |
Thank you. Done. |
|
Kudos, SonarCloud Quality Gate passed!
|
|
@fmvilas have a look. I think we can label it properly and start pinging community for review |
|
Yes, let's start pinging the community for review. I like this idea a lot, @sekharbans-ebay 🙌 |
|
Proposal shared with the wider community:
|
spec/asyncapi.md
Outdated
| @@ -663,7 +663,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 need to be satisfied to authorize an operation. In cases where Server Security also applies, it is expected the security mechanisms specified at the operation level would take priority and ideally should match or be a subset of that required by the server. | |||
There was a problem hiding this comment.
the security mechanisms specified at the operation level would take priority and ideally should match or be a subset of that required by the server
because this is a spec and we need to be super precise, I have to say ideally is not the best word to use here. I think this must be a requirement, that security mechanism on operation level must match one of the security mechanisms on the server level. Then we can have a proper validation in place. Thoughts?
There was a problem hiding this comment.
Suggest rewording to simply: " the security mechanisms specified at the operation level would take priority." and omitting the recommendation on the subset altogether. If the invoker does not have access to the operation any component that the operation relies on is automatically shielded.
In some topologies - the operations can use a completely different set of authentication scopes to talk to the broker. For example operation A is exposed with an auth scope a. However the operation could interact with the broker using a different auth scope (defined at the server level) - lets say from an internal set of allowed scopes say 'b' that is granted to the operational component(s) authorized to interact with the broker).
There was a problem hiding this comment.
so we are basically dropping and ideally should match or be a subset of that required by the server? which is much clearer and better for me. Sounds good
|
@fmvilas I'm in a position that we should go forward with this PR to @sekharbans-ebay please enrich this PR with some official example that could land in the @Felix200521 I see you approved this PR. Can you share a comment on why you like this proposal, what is your use case? It will help us to get a better understanding of why this proposal makes sense for a wider audience. |
|
> @sekharbans-ebay please enrich this PR with some official example that could land in the Hi @derberg - I have made the alterations to reword the section. The asyncapi.md does include examples in this PR (relevant section(s) of the specification). |
derberg
added
📄 Draft (RFC 2)
|
The rest of the PR's have been merged now:
Moving with the merge of this one as approvals from all Code Owners are present. |
|
/rtm |
|
Hello, @smoya! 👋🏼 |
|
/au |
|
/rtm |
|
Hello, @smoya! 👋🏼 |
|
I don't really understand the flow of the bots :( |
|
the bot that talks to you now is an old bug in a workflow, that was fixed on
I see you merged both related PRs but problem is that the parser PR do not use |
|
Thanks for the answer @derberg!
This wasn't working. I think since the latest changes on the bot, now I opened the following PR changing
I created a PR in the parser for pointing specs package to the latest release candidate. However, wondering if I could use some wildcard to not having to do this change every time we wanna merge a change. |
derberg
added
🏁 Accepted (RFC 3)
|
🎉 This PR is included in version 2.4.0-2022-04-release.1 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
| 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` |
There was a problem hiding this comment.
@sekharbans-ebay I just noticed there is a typo here. It should be: test_oauth
| # 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 |
There was a problem hiding this comment.
Now that I'm writing the release notes, this comment seems confusing to me.
The spec says:
In cases where Server Security also applies, it MUST also be satisfied.
However, by reading this comment, I understand that only one (the server or rather the operation) security requirement should be satisfied.
Would you mind clarifying this @sekharbans-ebay? Also pinging Code Owners @derberg @fmvilas @dalelane
There was a problem hiding this comment.
Now that I'm writing the release notes, this comment seems confusing to me.
The spec says:
In cases where Server Security also applies, it MUST also be satisfied.
However, by reading this comment, I understand that only one (the server or rather the operation) security requirement should be satisfied.
Would you mind clarifying this @sekharbans-ebay? Also pinging Code Owners @derberg @fmvilas @dalelane
The example text is poorly worded - will reword this. My intention was to state that you could still operate on the channel using security credentials supported at the server level perhaps thru a different operation. Is this okay:
_# This operation level security implies the ability to send a message to
# `smartylighting.streetlights.1.0.action.{streetlightId}.turn.on` with Authorization headers
# that have `streetlights:read` scope. Note that the operation level security must still satisfy
# security options specified at the server level._
There was a problem hiding this comment.
Would you mind creating a PR against 2022-04-release branch with such a fix (and the others I mentioned in other comments) @sekharbans-ebay ?
There was a problem hiding this comment.
Would you mind creating a PR against
2022-04-releasebranch with such a fix (and the others I mentioned in other comments) @sekharbans-ebay ?
Done. Please review:
#768
| security: | ||
| streetlights_auth: | ||
| - streetlights:write | ||
| smartylighting.streetlights.1.0.action.{streetlightId}.turn.on: |
There was a problem hiding this comment.
@sekharbans-ebay Would it make sense to link the channel to a server(s)?
You can do this by adding servers field. For example:
servers:
- test_oauth
|
🎉 This PR is included in version 2.4.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
feat: Add security at the channel/operation level
Description:
We are using AsyncAPI specifications for publishing the subscriber specific details of our topics and associated payloads for our HTTP push use cases.
Our subscribable channels(or topics) are protected by a set of oauth scopes (authorization code or client credentials) - that a potential subscriber needs to be aware of.
Here is a sample contract.
We are able to accommodate almost every detail of interest to an integrator/subscriber (THANK YOU) - with the exception of being able to call out the oauth scopes necessary for the subscription to the topic - i.e. the security aspect at the channel or rather channel/operation level.
The current specification is perhaps more aligned with a broker based topology - but ours is a pure push use case (to registered webhooks) and we need an ability to call out any security aspects at the channel operation level.