HTTP Error codes for endpoints using OpenAPI security schemes

[ghobona]

There was discussion about what is the appropriate HTTP error code to return when the request includes an invalid or garbled bearer token; assumption is that the endpoint is expression is using an OpenAPI security scheme for bearer tokens (securityScheme: bearer,oauth2,OpenIDConnect). What should be the error code (400 or 401)?

[securedimensions]

Regarding the responses for an API endpoint, where the OpenAPI description includes a standardized "security scheme" (as here https://swagger.io/docs/specification/authentication/) I would return the response HTTP status code + the information in the response body along the requirements outlined in OpenAPI:

• scheme: "oauth2" (https://swagger.io/docs/specification/authentication/oauth2/) strongly implies that the API endpoint expects an OAuth2 access token. RFC 6750 "The OAuth 2.0 Authorization Framework: Bearer Token Usage" (https://tools.ietf.org/rfc/rfc6750.html) defines the protocol in which OAuth2 Bearer Tokens are to be used. And in section 3.1 (https://tools.ietf.org/rfc/rfc6750.html#page-9) the use of 400, 401 and 403 is defined. => As an application implementer, I'd expect this protocol to be followed.
• scheme: "bearer" (https://swagger.io/docs/specification/authentication/bearer-authentication/) is a more generalized used of OAuth2 Bearer Tokens, but OpenAPI also implies that RFC 6750 is followed. This scheme is more general as it does not require to provide OAuth2 details in the OpenAPI document. => I'd still expect RFC 6750 is followed in terms of error codes.
• scheme: "OpenIDConnect" (https://swagger.io/docs/specification/authentication/openid-connect-discovery/) is a specialization to the OAuth2 scheme that expects the use of user information. Basically, the use of OpenID Connect Discovery is activated so that the application (or a developer) can bootstrap the application based on the information exposed via the .well-known/openid-configuration URL. But still, an OpenID Connect compliant Authorization Server implements - of course - OAuth2. That said, the application would use RFC 6750 to present the Bearer Token to the API endpoint. Therefore, I'd again expect RFC 6750 to be followed.

Additional comment: When the client application has submitted a Bearer Token with the OGC API request, it is aware of the requirement to present a valid token. In case the application was inactive for some time, the bearer token might got expired. To trigger a bearer token refresh in the client, it is essential that the server returns a 401 "WWW-Authenticate" to signal the client application to obtain a fresh / valid token.

=> The HTTP error code for the situation where the request contains a invalid or garbled bearer token should be 401.

[ghobona]

@pvretano @pomakis This topic is now captured in a GitHub issue.

[pomakis]

It's worth noting for the record that the resource request that triggered this discussion isn't for a protected resource. Rather, it's a for public resource that simply provides richer information to certain authenticated users. This case doesn't seem to be adequately covered by the OpenID Connect specifications (or HTTP authentication in general for that matter).

My initial thought on the matter (and therefore my initial implementation) was that if an invalid or expired Bearer token is provided for such a resource, the response should be a generic HTTP 400 error. My reasoning was that returning a HTTP 401 (Unauthorised) response for a resource that everyone is always authorized to get a public representation of seemed wrong.

But @securedimensions has a good point, and I have since adjusted our implementation accordingly.

[securedimensions]

When the request contains a Bearer Token and it is either invalid or expired, status = 401 with error_code=invalid_token https://tools.ietf.org/html/rfc6750#section-3.1

[cmheazel]

One of our operating principles is that we will not second-guess main stream IT. Authentication protocols are defined in standards outside of our direct control. So they are out of scope for this standard. However, if someone wants to write up a discussion of this topic, we can include it in a Users Guide as a suggested practice for implementers.