- Notifications
You must be signed in to change notification settings - Fork43
Description
In its current wording, I interpretRFC 7231 §6.5.3 to allow403 Forbidden to be used in the following two situations:
- The requested operation is forbidden in the current state of the resource.
- The requested operation is forbidden (for the user identified) by the provided authentication credentials.
This ambiguity is established in the following paragraph:
If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials.
The ambiguity is somewhat lifted (but not entirely) by the last sentence:
However, a request might be forbidden for reasons unrelated to the credentials.
However, I believe the ambiguity exists and causes a lot of developers to believe that403 Forbidden is only applicable to authorization errors. I think the wording in the previous paragraph:
The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any).
…the example given inRFC 7807:
HTTP/1.1 403 ForbiddenContent-Type: application/problem+jsonContent-Language: en{"type":"https://example.com/probs/out-of-credit","title":"You do not have enough credit.","detail":"Your current balance is 30, but that costs 50.","instance":"/account/12345/msgs/abc","balance":30,"accounts": ["/account/12345","/account/67890"]}
…and the wording inRFC 7807 §4:
For example, a "write access disallowed" problem is probably unnecessary, since a 403 Forbidden status code in response to a PUT request is self-explanatory.
…as well as existing practice establishes that403 Forbidden is the correct status code to respond with when the requested operation is not allowed in the current state of the application (use-case 1 above), regardless of theAuthorization header provided.
Introducing the ambiguity of403 only being applicable to the provided authorization when authorization is available makes the status code harder to reason about and therefore harder to use in practice. Would it be possible to remove this ambiguity somehow? Here's some suggested wording:
If authentication credentials were provided in the request, the server might consider them insufficient to grant access to the requested resource. In that case, the client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials. For request methods other than HEAD, the server SHOULD generate a payload indicating why the request was forbidden.