OAI / OAI/sig-security

Support for "dynamic" authorization scopes

Open
#18 8 comments 9 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
6
Forks
3
Avg merge
1h 54m
Merged PRs (30d)
1

Description

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 ;-)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the OpenAPI security and securitySchemes definitions and the Swagger-UI Try it out flow described in the issue. Review the linked OAuth scope and Docker resource-scope references, then define how endpoint-dependent scopes and the proposed OR semantics should be represented. Done means the representation and interactive authorization behavior are settled.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, authentication, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.