What is the appropriate error response for an invalid authentication token?

[bdesham]

The standard currently defines three error responses related to authentication/authorization:

• HTTP 403: "error":"forbidden" - The authenticated user does not have permission to perform this request.
• HTTP 401: "error":"unauthorized" - No access token was provided in the request. Note that this is different from the HTTP 403 response, as the 403 response should only be used when an access token is provided and the user does not have permission to perform the request.
• HTTP 401: "error":"insufficient_scope" - The scope of this token does not meet the requirements for this request. The client may wish to re-authorize the user to obtain the necessary scope. The response MAY include the "scope" attribute with the scope necessary to successfully perform this request.

What if the client did send an Authorization header with an access token but that token is invalid? This case doesn’t seem to be covered by the first response, which refers to “the authenticated user.” The second response assumes there is no token at all. The third response indicates that there is a problem with the scope specifically—this doesn’t seem like it would be an appropriate response if the token were malformed or otherwise invalid.

Does the spec already cover this case and I’m just not seeing it? Or is this not yet addressed? In the latter case, as a strawman proposal, I suggest that the “401 unauthorized” case be expanded as follows:

No access token was provided in the request or the access token is malformed or otherwise invalid. Note that this is different from the HTTP 403 response, as the 403 response should only be used when an access token is provided and the user does not have permission to perform the request.

[jalcine]

I’ve opted for 400 Bad Request in this case as these requests require a valid authentication token. A valid token can fall under a 401 Unauthorized or a 403 Foribbden IMO.

(Originally published at: https://v2.jacky.wtf/post/c6a3f445-5c1c-4a8f-90f2-43e573eab378)

[jamietanna]

My server, which uses Spring Security as a base to handle OAuth2-related goodness responds with the following:

% curl -i https://www-api.staging.jvt.me/micropub -H 'Authorization: Bearer ffff' -d ''
HTTP/1.1 401 Unauthorized
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 82
Date: Sat, 25 Jul 2020 15:28:52 GMT
Expires: 0
Pragma: no-cache
Server: Caddy
Www-Authenticate: Bearer
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Xss-Protection: 1; mode=block
Content-Type: text/plain; charset=utf-8

{"error": "unauthorized", "error_description": "No authentication was provided."}

It responds like so if an empty token is provided:

% curl -i https://www-api.staging.jvt.me/micropub -H 'Authorization: Bearer ' -d ''
HTTP/1.1 401 Unauthorized
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 0
Date: Sat, 25 Jul 2020 15:29:34 GMT
Expires: 0
Pragma: no-cache
Server: Caddy
Www-Authenticate: Bearer error="invalid_token", error_description="Bearer token is malformed", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Xss-Protection: 1; mode=block

And if no authentication is provided at all:

% curl -i https://www-api.staging.jvt.me/micropub -d ''
HTTP/1.1 401 Unauthorized
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 82
Date: Sat, 25 Jul 2020 15:30:11 GMT
Expires: 0
Pragma: no-cache
Server: Caddy
Www-Authenticate: Bearer
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Xss-Protection: 1; mode=block
Content-Type: text/plain; charset=utf-8

{"error": "unauthorized", "error_description": "No authentication was provided."}

https://tools.ietf.org/html/rfc6750#section-3.1 defines:

invalid_request
     The request is missing a required parameter, includes an
     unsupported parameter or parameter value, repeats the same
     parameter, uses more than one method for including an access
     token, or is otherwise malformed.  The resource server SHOULD
     respond with the HTTP 400 (Bad Request) status code.

So Jacky's point could be argued as a suitable alternative, as the request is bad, as no authentication has been provided

[genagurbanguliyev]

• if there is no Token in Header's credentials then use:
  status_code=status.HTTP_401_UNAUTHORIZED, "message"= "Not authenticated"
• if there is Token but if Invalid token or expired token or no access... then use:
  status_code=status.HTTP_403_FORBIDDEN, "message"= "Invalid token or expired token."

---

401 Unauthorized - This means the user isn't not authorized to access a resource. It usually returns when the user isn't authenticated.
403 Forbidden - This means the user is authenticated, but it's not allowed to access a resource.