Authorization in RESTful HTTP API, 401 WWW-Authenticate

Question

I'm creating a RESTful service to provide data to a web application. I have two related questions about this.

1. How to deal with unauthorized requests?

I'm intending to respond to requests with the following codes:

• Is the resource open and found? 200 OK
• Do you need to be authenticated to access the resources? 401 Unauthorized
• Don't you have access to a category of resources? 403 Forbidden
• Do you have access to a category of resources, but not to this specific resource? 404 Not Found to prevent people from getting to know the existance of a resource they do not have access to.
• Doesn't the resource exist? 404 Not Found

Is this a recommended way for a RESTful service to behave?

2. What WWW-Authenticate header should 401 responses supply?

I read on Wikipedia (probably not the most accurate resource, but it works for me) that a 401 response must include a WWW-Authenticate header, however upon further searching I couldn't really find any resource that stated what this value means and what it should be.

I found several SO questions and forum topics about this header and they all seem to be about OAuth, suggest against using 401 status codes or say you can just make something up.

What is the correct value this header should contain?

Solution

To answer your questions:

How to deal with unauthorized requests?

The way you described it is pretty much the recommended way for a RESTful service. As far as I can see there is absolutely nothing wrong with that.

What WWW-Authenticate header should 401 responses supply?

In general the WWW-Authenticate header tells the client what kind of authentication the server will accept. If the client makes an unauthorized request, which means he is sending a request with a missing or invalid Authorization header, the server will use WWW-Authenticate to tell the client what authentication scheme he will accept (i.e. Basic, Digest or OAuth) and for what realm.

Imagine it like some kind of identification question or challenge on the part of the server, i.e. something like "Who are you?" or "Prove who you are by providing credentials in the following way!".

For Example: WWW-Authenticate: Basic realm="My App"

Here the server tells the client that he uses an authentication scheme named Basic. The realm is nothing more than some string that identifies a protected space on the server.

Comments

[Aidiakapi]

So in the scenario that I have a web service providing data for a web application, what'd the header look like? Something in terms of Forms realm="http://my.domain.com/"?

[benjiman]

Yes it could look like this. The realm doesn't need to be the domain name. It can be any string. The value just identifies a bunch of resources that share credentials. This way you can group protected resources on a server into multiple protection spaces, each with its own authentication scheme and/or authorization database.

[Julian Reschke]

New schemes are supposed to be registered.

[sigi]

@JulianReschke do you have any information how to do that? Or where you found those information (propbably some rfc page?)? How would you do it on a REST API?

[Julian Reschke]

It's all described in RFC 7235.

[Sam Watkins]

Considering that Microsoft just makes up their own bogus status codes, it's a relatively minor crime for us to make up our own WWW-Authenticate schemes. Forms-based login might not be defined in HTTP, but it is the most common type of login on the web as far as I can tell. The HTTP people could potentially save some bother by specifying what would be the sensible thing to do.