[Feature Request] Document permissions needed to call APIs

[heaths]

Is your feature request related to a problem? Please describe. Many APIs require the caller to have different permissions e.g., RBAC actions or data actions, to call. We should document these both in REST API documentation, as well as client library documentation. See Azure/azure-sdk-for-net#8992 for more context.

Describe the solution you'd like Define a @permissions(...permissions: valueof string[]) decorator that documents the permissions required to call the API.

Describe alternatives you've considered Some APIs like Key Vault already document these in their API docs e.g., @doc("... Requires secrets/get permissions.") but this is neither consistent across APIs or easily discernable in a way that APIs can call out explicitly. We should do this in a more general way and drive usage across APIs as appropriate. All language generators can then emit information in an idiomatic way. .NET docs used to list Code Access Security (CAS) required permissions in a separate section, for example.

[markcowl]

I think this is mainly generating documentation and requirements around usage of this operation-level security feature: https://github.com/microsoft/typespec/issues/2624

[markcowl]

@heaths Let me know if generating documentation around operation-level authorization requirements as outlined above would resolve this issue, or if there is additional information we need to encoded.

[heaths]

That is not the same. That deals with scopes required by an authentication token. What I'm talking about is what RBAC permissions are required, which are separately.

Now, conceptually these could be used the same, but I worry overloading them may paint us in a corner.

For example, Key Vault has a single token scope, but a dozen or two RBAC permissions (and just as many legacy custom permissions that don't rely on RBAC). @useAuth seems tie too closely to OAuth scopes. /cc @timotheeguerin @schaabs

[heaths]

For context, I'm talking about something that can more consistently emit something like what Key Vault has been doing with their legacy permissions:

https://learn.microsoft.com/en-us/rest/api/keyvault/keys/get-key/get-key?view=rest-keyvault-keys-7.4&tabs=HTTP#:~:text=This%20operation%20requires%20the%20keys/get%20permission.