How to inform OAuth2 API clients about missing credentials?

Question

I build a REST API using Vert.x and would like to add OAuth2 authentication.

In my current setup unauthenticated requests will automatically be redirected to the OAuth2 server (keycloak) login page. This seems wrong when dealing with a REST API. Instead I would expect my REST API server to return a 401 and thus let the client deal with the process of getting the access token.

Is there a best practice for this use case? How should unauthenticated requests to protected resources be handled?

Hans Z. Hans Z. · Accepted Answer · 2018-05-09T16:14:18

When a access token is missing you should return an HTTP 400. If the token is invalid it would have to be HTTP 401 as shown in https://www.rfc-editor.org/rfc/rfc6750#section-3.1:

3.1. Error Codes

When a request fails, the resource server responds using the
appropriate HTTP status code (typically, 400, 401, 403, or 405) and
includes one of the following error codes in the response:

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.
invalid_token
     The access token provided is expired, revoked, malformed, or
     invalid for other reasons.  The resource SHOULD respond with
     the HTTP 401 (Unauthorized) status code.  The client MAY
     request a new access token and retry the protected resource
     request.
insufficient_scope
     The request requires higher privileges than provided by the
     access token.  The resource server SHOULD respond with the HTTP
     403 (Forbidden) status code and MAY include the "scope"
     attribute with the scope necessary to access the protected
     resource.
If the request lacks any authentication information (e.g., the client was unaware that authentication is necessary or attempted using an unsupported authentication method), the resource server SHOULD NOT include an error code or other error information.

For example:
 HTTP/1.1 401 Unauthorized
 WWW-Authenticate: Bearer realm="example"

How to inform OAuth2 API clients about missing credentials?

1 Answers