Support for "dynamic" authorization scopes

[aparamon]

According to https://swagger.io/docs/specification/authentication/#scopes,

• In case of OAuth 2, the scopes used in security must be previously defined in securitySchemes.
• In case of OpenID Connect Discovery, possible scopes are listed in the discovery endpoint specified by openIdConnectUrl.

This is limiting though, as application may want to provide "dynamic" scopes which depend on the endpoint. Consider e.g.

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            pets:read: Grants pet read access
            pets:write: Grants pet write access
paths:
  /pets/{id}/color:
    get:
      summary: Get pet color
      security:
        - OAuth2: [pets:{id}:read]

In this case, the fine-grained pets:{id}:read scopes are used for accessing particular pet's color. For example, /pets/felix/color is accessible with scope pets:felix:read. However, it's impossible to pre-define all pet scopes in securitySchemes, as they depend on path and application state. See also https://docs.docker.com/registry/spec/auth/scope/#resource-scope-grammar for example of really complex dynamic scope names.

To support interactive "Try it out" in Swagger-UI, the following approach might prove helpful:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            pets:read: Grants pet read access
            pets:write: Grants pet write access
paths:
  /pets/{id}/color:
    get:
      summary: Get pet color
      security:
        - OAuth2: [pets:read OR pets:{id}:read]

This way, if coarse-grained pets:read scope is selected in Swagger-UI, the lock icon status corresponding to /pets/{id}/color could be correctly updated. In the actual API client, any of coarse-grained pets:read and fine-grained pets:{id}:read (e.g. pets:felix:read) could be requested and used.

How to properly implement OR operator in YAML is a technical exercise ;-)

[MikeRalphson]

@aparamon Thanks for the link to the concrete example. Very useful.

[sigalmaya]

What is the status of that issue? is it going to be supported soon?

[vanillajonathan]

Here is an interesting blog post on why "dynamic scopes" is a misuse of of the scope claims. On The Nature of OAuth2’s Scopes by Vittorio Bertocci, principal architect at Auth0

[hbusul]

Here is an interesting blog post on why "dynamic scopes" is a misuse of of the scope claims. On The Nature of OAuth2’s Scopes by Vittorio Bertocci, principal architect at Auth0

I read this article as well. I believe this does not say against using "dynamic scopes". Because I can have a token that says "Access to mailbox A" but the API still needs to verify me if I can actually access this. Dynamic or not scopes are limiting factors, they should not be used to give more permissions to users but rather limit. So I don't see the argument why having a dynamic field in scopes would not work. You can have any mailbox id in the scope, API will always validate it so it does not matter. But the fact that you can have specific inbox ids make everything sweeter IMO because now I can delegate only inbox A to a specific application instead of giving my every inbox.

[jonasandero]

Yes, the problem with that post is that isn't clear about the difference between API security and content security.

The purpose of auth scopes is to restrict API access to a subset of endpoints.

Whether a resource can be accessed depends on more things than API security. A token with a claim for inbox:read may let you access /inbox/{inbox-id}, but only if it's your inbox.

[levilugato]

any updates on that ?

[handrews]

@levilugato we're currently working on scoping OAS 3.2 (which will be very near-term and limited in scope) and 3.3 (which will be longer and a bit more ambitious, although still a true minor release, with 3.1, 3.2, and 3.3. all strictly compatible). You can see that discussion in #4210 , and notice that this is in the set of security requests that I need a bit of help scoping.

Please note that whether something goes into 3.2 vs 3.3 has nothing to do with how valuable it would be or how much demand exists for it, and everything to do with how long it will take to figure out. We will begin working on 3.3 immediately after shipping 3.2, and the point of 3.2 is to ship quickly. Some things will get punted out of both, and that might have to do with prioritizing demand.

There is no fixed schedule for these because most of the labor is volunteer, but I'm hoping to get 3.2 out the door in Q1 2025.

[handrews]

Reading over this, I think the distinction between API security and content security is worth exploring, but is also rather fuzzy. In the example, the template variable in the scope matches a template variable in the path. So, really, this is working at the endpoint level: It's just that the path template defines a set of endpoints, not a single endpoint. And these templated scopes correlate such that each endpoint in the set requires its own scope.

Is this a good design? I have no clue. But it does not violate the "endpoint-level authorization" principle. An example where the template variables are independent, however, would.

I'm not quite sure where to go with this, but restricting to templates that match path templates might make it a bit more manageable to solve.