search

belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
24 stars 4 forks source link

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

Open pvdbosch opened 3 years ago

pvdbosch commented 3 years ago

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

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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?