Dynamic Scopes

[janwilmake]

After trying to architect a good way for doing RAR with OAuth2, I stumbled upon the question on how to implement fine-grained access control. How to do this right? My intuition was to add {variableName} in the scope to make it more fine-grained, and document it clearly.

I found these materials that confirmed my strategy:

• Using Dynamic/Parameterized Scopes to generate resource-specific tokens keycloak/keycloak#8486
• Support for "dynamic" authorization scopes #1731
• Example of dynamic scopes: https://distribution.github.io/distribution/spec/auth/scope/
• Why it's not a good idea: https://auth0.com/blog/on-the-nature-of-oauth2-scopes/
• This guy has a lot to say: https://auth0.com/blog/authors/vittorio-bertocci/
• This is useful to gather OpenAPIs stance on this topic: security: access ctrl Permissions and controls distinct from authentication

All in all, it seems that it's possible to create scopes with dynamic parts. Maybe disliked by some developers and authorities (such as Vittorio Bertocci) but definitely possible - and implemented by some people - and not uncompatible with oauth2.

As an example, I will implement my database management and use API like this:

{
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.example.com/oauth/authorize",
            "tokenUrl": "https://auth.example.com/oauth/access_token",
            "x-scopes-parameters": [
              { "name": "projectSlug", "description": "Refers to a project" },
              { "name": "databaseSlug", "description": "Refers to a database" }
            ],
            "scopes": {
              "admin": "Access to managing all projects",
              "user:project:{projectSlug}": "Access to use all databases in a project, with or without user separation.",
              "user:project:{projectSlug}:read": "Access to read all databases in a project, and write to all user-separated databases.",
              "admin:project:{projectSlug}": "Access to manage an entire project",
              "admin:db:{databaseSlug}": "Access to manage a database"
            }
          }
        }
      }
    }
  }
}

To make things clearer, I'll add x-scope-parameters to my openapi specification, as such:

{
  "definitions": {
    "ScopeParameters": {
      "type": "array",
      "description": "OAS extension that specifies the parameters you use in your scopes.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string" },
          "schema": {
            "oneOf": [
              {
                "$ref": "#/definitions/Schema"
              },
              {
                "$ref": "#/definitions/Reference"
              }
            ],
            "description": "Defaults to string, but can be further defined here if it has a specific syntax (using format or regex, for example)"
          },
          "description": { "type": "string" }
        }
      }
    },
    "AuthorizationCodeOAuthFlow": {
      "type": "object",
      "description": "See https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type for a good understanding",
      "required": ["authorizationUrl", "tokenUrl", "scopes"],
      "properties": {
        "authorizationUrl": {
          "type": "string",
          "format": "uri-reference"
        },
        "tokenUrl": {
          "type": "string",
          "format": "uri-reference"
        },
        "refreshUrl": {
          "type": "string",
          "format": "uri-reference"
        },

        "x-scopes-parameters": { "$ref": "#/definitions/ScopeParameters" },
        "scopes": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "patternProperties": {
        "^x-": {}
      },
      "additionalProperties": false
    }
  }
}

Just sharing my research and ADR here. Maybe it helps, and curious to hear others takes on this!

[SensibleWood]

@CodeFromAnywhere I am very keen to evolve how OpenAPI and OAuth metadata/OpenID Discovery metadata work together. The existing approach is used in Security Scheme objects, for me, too brittle right now.

I jotted some thoughts down in a completely unrelated Issue I raised on the 3.2.0 implementation of CIBA: #4106

It might provide some context on where my head is at. If you are up for collaborating on some ideas, let me know. I am keen to take this stuff to FAPI WG to see if there is any appetite from members to evolve the approach. It's all a bit disconnected as things stand.