indicate at least one scope of a list is required [problems/missingScope]

[pvdbosch]

An API designer can allow access (specified in OpenAPI) to an operation if:

• all of multiple scopes is present in JWT
• one of multiple scopes is present
• any combination of the above

The missingScope problem type only allows for the first case: "The requiredScopes property lists the required scopes." Can we extend the problem type structure to also allow for the other cases?

OpenAPI even allows security requirements listing a mix of mechanisms, e.g.:

"security": [
 { "oauth-authorizationCode": ["scope1"] },
 { "oauth-authorizationCode": ["scope2"], "httpBasicAuth": "" },
 { "oauth-clientCredentials": ["scope2"], "mutualTLSAuth": "" }
]

note: mutualTLS will be supported only in OAS3.1.

[jpraet]

Related to this:

According to the spec, logical "AND" and "OR" for scopes can be expressed as follows

# User needs scopes A AND B
security:
  - oauth2:
    - A
    - B

# User needs scope A OR B
security:
  - oauth2:
    - A
  - oauth2:
    - B

# User needs scope (A AND B) OR C
security:
  - oauth2:
    - A
    - B
  - oauth2:
    - C

But the Smals API Deployer tool fails on this:

# User needs scope A OR B
security:
  - oauth2:
    - A
  - oauth2:
    - B

With exception "java.lang.IllegalArgumentException: For operation getCard the scopes in each security requirements must be equal"

Instead, we need to configure a custom vendor-specific extension:

# User needs scope A OR B
security:
  - oauth2:
    - A
    - B
x-oauth2-required-scopes: any

[pvdbosch]

That's rather an internal Smals issue than a REST guide one. IMO, the Smals tool should be changed to support the standard where possible, so clients don't need to interpret a custom extension. I believe I opened an issue for this long ago.

[jpraet]

Ok, we'll try to revive that Smals tooling issue.

More on topic then is how to represent that scope A or B is required.

Current https://www.belgif.be/specification/rest/api-guide/#missing-scope has a requiredScopes array property that "lists the required scopes". So "requiredScopes": ["A", "B"] currently seems to imply that A and B are required.

Could it be represented like this?

• "requiredScopes": ["A", "B"] --> User needs scopes A OR B
• "requiredScopes": [[ "A", "B"]] --> User needs scopes A AND B
• "requiredScopes": [[ "A", "B"], "C"] --> User needs scope (A AND B) OR C