What HTTP code should I use for a third party authentication failure?

Question

I'm creating an application that has integrations with third party applications.

To do this, the logged in user submits an API key for the third party integration.

In the case that the API key they submitted is invalid - (and returns a 401 from the third party), which HTTP response should I return?

Returning a 401 from my application sounds confusing because from the frontend's point of view, it's unclear whether they're unauthenticated by my application, or the third party application.

I'm tempted to just give it a 400 - as if they'd submitted a form with an invalid email address etc.

Corvus

Answer 1

The question seems to imply the authentication failure is the fault of the client making the request. In that case, if I had to pick a code, I would probably choose to return 403 Forbidden.

RFC 7231 §6.5.3 describes the 403 code as follows:

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).

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. However, a request might be forbidden for reasons unrelated to the credentials.

An origin server that wishes to "hide" the current existence of a forbidden target resource MAY instead respond with a status code of 404 (Not Found).

This status code is commonly used as a generic 'authentication failed' response and isn't likely to trigger any specific authentication mechanism, like 401 can compel a browser to show a username/password prompt. The specific reason why authentication failed can be described in the response body, either in a machine-readable form (e.g. JSON or XML), or as a human-readable document (e.g. HTML).

Code 400 isn't the worst possible choice here, but it's rather generic.

Scabbard

Answer 2

You can use status code HTTP status code - 407 (Proxy Authentication Required). From Mozilla Developers Reference:

The HTTP 407 Proxy Authentication Required client error status response code indicates that the request has not been applied because it lacks valid authentication credentials for a proxy server that is between the browser and the server that can access the requested resource.

Your backend-application is acting like a proxy to 3rd party API, so it is OK to use 407 in this case.

Bhili

The very same page states: 'This status is sent with a Proxy-Authenticate header that contains information on how to authorize correctly.' What do you think should be put in it? RFC 7235 also says 'The client MAY repeat the request with a new or replaced Proxy-Authorization header field', so it looks like it's part of a very specific mechanism that doesn't apply to the asker's situation. – Scabbard

"...a proxy server that is between the browser and the server that can access the requested resource" not quite the same situation the OP is describing. This would apply if the OP's own service would fail to authenticate the user requesting a resource from the 3rd party service... – Jaenicke

Answer 3

407 is not correct. In this case, your code is the proxy and it is authenticated. It is a foreign system that is not authenticated.

401 is reasonable but it is misleading about what is not authenticated since the client is authenticated to your system. This also does not work if your foreign auth is deferred until after a 100Continue.

400 is not correct since the request was valid in format but the auth failed at the foreign agent.

All the other 4xx responses are easily dismissed as not applicable here.

So, that leaves 403 Forbidden which in my opinion is your only real option in this case:

403 Forbidden The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. Responding also with a status message that indicates "root cause" of failure may be suitable in this case too. It really depends on the security disposition of your application.

My $.02

Succulent

Answer 4

The 424 - Failed Dependency suits quite well in this case.

The 424 (Failed Dependency) status code means that the method could not be performed on the resource because the requested action depended on another action and that action failed.

Asteriated

It's from RFC4918 tools.ietf.org/html/rfc4918. 11.4 page 78 – Grossman

Answer 5

I'd go with 400, it meets the semantic requirement. The user supplied some bad data. As you say a 401 / 403 implies an issue between the user and your site, not your site and some other application.

Section 1 of the HTTP 1.1 RFC states:

Introduction

Each Hypertext Transfer Protocol (HTTP) message is either a request or a response. A server listens on a connection for a request, parses each message received, interprets the message semantics in relation to the identified request target, and responds to that request with one or more response messages. A client constructs request messages to communicate specific intentions, examines received responses to see if the intentions were carried out, and determines how to interpret the results. This document defines HTTP/1.1 request and response semantics in terms of the architecture defined in [RFC7230].

Ergo the definition of status codes are between a client and a server. To me that means pick the one that makes the best sense for other (server to server, backend, etc) interactions.

All the other exotics offered here are just going to confuse the consumer of the service.

Adsorbent

Answer 6

Its always good to send 403

but if needed you can addition json info-

[Serializable]
[DataContract]
class Response
{
    [DataMember]
    public bool IsSuccess { get; set; }
    [DataMember]
    public string Message { get; set; }
    [DataMember]
    public object ResponseData { get; set; }

    public Response(bool status, string message, object data)
    {
        IsSuccess = status;
        Message = message;
        ResponseData = data;
    }
}

And then in the response add the following info too

 return Json(new Response(false, "Login Failed, The user name or password provided is incorrect.", null));

when a request is made you can disable the login button - and only when an update is made the button can be enabled - client side logic.

Nalda

Answer 7

I'll lean towards 407. 407 Proxy Authentication Required This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy. The proxy MUST return a Proxy-Authenticate header field (section 14.33) containing a challenge applicable to the proxy for the requested resource. The client MAY repeat the request with a suitable Proxy-Authorization header field (section 14.34). HTTP access authentication is explained in "HTTP Authentication: Basic and Digest Access Authentication". as Iskander mentioned.

It hints best the user about what the problem could be. Also you could go forward and implement the proxy-authorization header to be fully consistent with the specs.

Using 400 would make your client scratch his head looking for what he is doing wrong when building the request.

Using 401 or 403 makes more sense to keep them for your own API authentication and authorization.

502 hints the user that the problem is upstream, so he could be left hanging until you fix it.

Burke

Answer 8

I would stand with 401 . The 401 Unauthorized error is an HTTP status code that means the page the user was trying to access cannot be loaded until the user first log in with a valid user ID and password. If the user just logged in and received the 401 Unauthorized error, it means that the credentials the user entered was invalid for some reason. In our case the API key they submitted was invalid. There is an activity diagram which i was using when i have a confusion with the error codes.

Here below is the link for the same :

https://i.sstatic.net/ppsbq.jpg

Clower

Answer 9

Using HTTP 403 for expired authentication tokens can be misleading, implying an authorization issue within your application rather than with the third-party API (which utilizes a user-provided API key). For a more precise indication of a dependency failure, opt for HTTP 424 (Failed Dependency). This choice ensures clarity, preventing any confusion about the source of the problem.

You could also see another SO discussion here regarding HTTP codes for third-party dependencies.

In your case, returning a 403 might be misinterpreted as a refusal to serve the user, whereas using 424 communicates the dependency failure more accurately.

Tristatristam

Answer 10

In this case, the intermediating server has been successfully logged, and the upstream server refuses to accomplish the authentication by virtue of the invalid key. It seems the 502 code (Bad Gateway) fits for this situation, since this code stands for a server that is acting as a gateway (Yours) and is receiving an invalid response from the upstream server (third party).

Providential

A 5xx is definitely not the right answer here. This is a user error, not a server error. – Corvus