Using HTTP Authentication

Question

I am building a REST API in PHP to work with a JavaScript based app. All requests are handled as JSON and some requests require authentication.

An example request would be:

$.ajax({
    type: 'GET',
    url: 'http://domain.com/api/posts/recent.json',
    headers: {
        Authorization: 'X-TRUEREST ' + $.param({
            username: 'johndoe',
            password: '********'
        })
    },
    success: function(response){
            // Handle response here (includes auth errors too)
    },
    error: function(a,b,c) {

    }   
});

I have based the use of HTTP Authentication headers on the code in this plugin: https://github.com/kvz/cakephp-rest-plugin/blob/master/Controller/Component/RestComponent.php#L532

As you can see they take passed parameters with the header and then they are used to log a user into the system if they are not already. From what I can tell they expect the auth credentials to be passed WITH the request for data.

An example of this is (note not using CakePHP in my example app):

if ( $loggedIn ) { // logged in is true of false based on session existing

    // Then return the JSON as normal

} else {

    // Grab HEADERS INFO

    $headers = $_SERVER['HTTP_AUTHORIZATION'];
    $parts = explode(' ', $_SERVER['HTTP_AUTHORIZATION']);

    // Then use the parts to find a user in the DB... and populate $user

    if($user){

        $this->Auth->login($user); // login the user with our authentication code

        // Then return JSON as normal

    } else {
        print json_encode(array('auth'=>false))
    }

}

A few questions that I have though:

Question 1: Why use the HTTP Authentication and headers? As as far as I can tell, they are not offering me anything unless I am using them incorrectly? Why not just pass the username and password in the data param of the JS?

Question 2: As stated earlier I have based my API design on the Cake plugin above, but from what I can see they ALWAYS pass the username and password with every request and then decide to use it or not if the user is logged in. Is this correct? To me, it seems more likely that authentication and requests for data should be handled separately. Otherwise I would have to store the username and password in my JavaScript somewhere so that I can send it with each request.

Which brings me to the next question...

Question 3: How do I know if a user is logged in? I could set a variable to true and then pass that as part of my JSON with every request, but can a session work with an external device?

most RestAPIs use a token or a key. I'm building one that requires an authentication and then a token is generated for a user. Functions much like a cookie. There's nothing that says you have to use a header. You could use a header, a cookie or a parameter to GET or POST — Cfreak, Jan 31 '13 at 20:58
@Cameron, What do you mean with external device and why wouldn't it work with sessions? — Yoggi, Jan 31 '13 at 21:24
@Yoggi External as in the session is being set by the server but the request was from somewhere else unlike a normal HTTP request. I'm not saying it wouldn't work, just querying the different ways this could be done and what the HTTP Auth offers over just passing the credentials via the data params. — Cameron, Jan 31 '13 at 21:29
The way Amazon AWS does this is my preference. They use a private-public key pair with sha1 signing of the request. There is no "session". It should be the responsibility of the website to make state, not an API. Transloadit does this very same thing as well. I can give you much more details in an answer if you will consider my comment as a possible path. I've developed this methodology in my companies kitgui.com (cloud cms api) and emeraldcode.com (cloud ecommerce api) but with using a wildcard domain and mapping to each client with subdomain lookup as additional. — King Friday, Feb 03 '13 at 20:50
IMHO from a security point-of-view resuming user authentication to a Boolean is not enough to protect against replay attack. — happy, Feb 06 '13 at 02:41

score 22 · Answer 1 · answered Feb 03 '13 at 20:47

If you are designing a REST api, you should adhere to REST principles. There are two important ones to highlight for authentication:

Identification of resources through URIs
State transitions through server-supplied links.

To adhere to principle 1, you need to keep your authentication out of your URI. http://example.org/list-of-stuff?auth-token=12345 is not a different resource from http://example.org/list-of-stuff?auth-token=67890, so it should not have a different URI. Having different URIs also makes it impossible to cache the resource across different users.

In general, if the resource would be different depending on some condition, that condition needs to be in the URI. For example, many websites have a /profile url, but what profile you see depends on the invisible "who is logged in" state. This is not RESTful. Instead the url should contain the user, e.g. /profiles/username. Whether you actually get to see that resource depends on whether you are authorized to see it, which depends on whether you are authenticated as a user that is authorized. Authentication is a separate layer from resource identification. (For example, suppose you have an admin user which can see other people's profiles. If you have just a /profile url, how would you architect a method for him to see other profiles? Clearly the presence of a resource is something different from the ability to see it and from who is looking at it.)

So we have established that authentication should not be via parameters in the URI. Since we are using HTTP, we can either provide it in a header, or provide it outside HTTP itself.

Although it's not very common, some REST apis handle authentication at the SSL layer using client certificates. This is great from a technical standpoint, but the user experience is baffling and terrible. Although this article is from 2008, nothing has improved. This approach is also not easily scriptable from browser JS, and even outside the browser it's cumbersome to write an application that has to provide client certificates. Development on the server side is difficult, too, because most web scripting environments do not give you easy access to SSL-layer stuff at all, let alone more esoteric SSL features like client-certificates. Your application may not be able to know what certificate identity was provided with the request.

So that leaves HTTP in the header. We can either use a traditional cookie-based auth, where we "log in" at a special url and get a token back, or HTTP authentication which is natively supported by HTTP.

HTTP authentication is far superior in terms of RESTful principles because it is stateless. (This makes your third question nonsensical--there is no "logged in" or "logged out" state--you either provided the right credentials for the request or you didn't!) You don't need to ensure you first visited a special url and got a magic token you need to save (which might suddenly expire), you just issue a request with your credentials every time. If you are not authorized to access a resource, there's a specific HTTP response code (401) and header (WWW-Authenticate, Authorization) and set of well-defined behaviors. It's also extensible with different authorization methods. There's a fair amount of javascript support too, at least if you stick to XmlHTTPRequest. (Heck, jQuery 1.7.2 even has username and password options, so you don't even need to base64-encode it yourself!)

The downside is that the only HTTP auth methods that are in common use and well supported are Basic and Digest, and both of them are not very secure. They're probably fine if you only use https, but otherwise they are terrible.

Also HTTP auth is useless for normal browser use by humans: no custom login pages, no way to present "forgot password" functionality or other authentication customizations, and still browser makers have provided no easy way to "log out" (i.e., forget the credentials for the current realm)!

Cookie-based auth provides you the most control, but you need to keep server- and client-side authentication state and worry about a whole host of other security issues, such as session fixation or even what constitutes a session! Is it IP address, user agent, some combination? How long should an authenticated session be valid before we expire it? What if there's a proxy involved and the IP address changes frequently? What should we do when the magic token expires? What should we do when the user is not authorized? (You can't use an HTTP 401 response--you need to define your own method specific to your site.) In essence, you need to define your own complex session and authentication protocol or adopt someone else's. At least with HTTP auth, the only thing you need to worry about is an attacker reading your Authenticate headers, and using SSL solves that problem.

score 8 · Answer 2 · edited May 23 '17 at 12:22

Question 1: Why use the HTTP Authentication and headers? As as far as I can tell, they are not offering me anything unless I am using them incorrectly? Why not just pass the username and password in the data param of the JS?

HTTP Authentication here appears to be a personal choice of the developer. You could use OpenID. You could use a token. You could use HTTP Header Authentication. You could use sessions/cookies. Heck, you could even use RSA Key Authentication or SSL Client Certificates if you liked.

Question 2: As stated earlier I have based my API design on the Cake plugin above, but from what I can see they ALWAYS pass the username and password with every request and then decide to use it or not if the user is logged in. Is this correct? To me, it seems more likely that authentication and requests for data should be handled separately. Otherwise I would have to store the username and password in my JavaScript somewhere so that I can send it with each request.

You shouldn't expose the username and password of anything in plaintext, ever (technically you shouldn't even store it as such, but that's not what the question is about). Use a public token with an API, or a unique cookie ID. Personally, I use $_SESSION["id"] to see if a user is logged into anything. Let the AJAX submit and then map the ID to a token internally, if you have to.

Question 3: How do I know if a user is logged in? I could set a variable to true and then pass that as part of my JSON with every request, but can a session work with an external device?

I have a function I use for this linked in this answer. You should ideally check for a valid login using a session and setting the value of an index (such as $_SESSION["id"]) to a value that is unique to that account (usually, this is their database ID).

Edit: after reading the comments on the OP, you would have to make sure the session cookie was on any device that was logged in before making the request

Do not take a value: true field to be a login, as this is a security vulnerability.

score 4 · Answer 3 · edited May 23 '17 at 10:26

I think you are mixing (perhaps on purpose) between passing information to the REST api using the URI and authorizing access to the specific server with http simple Authentication.

HTTP authentication can also be used to handle users, but It wouldn't be a very good choice (as elobrated in other answers). users, sessions, security tokens etc should be handled by the app logic while api access can also be safe guarded by the server (with http simple or digest security, NTLM, IP filtering or whatever). letting the web server take some of the security burden/seperating concerns/some kind of testing site/etc'.

an example scenerio is handling http security to protected server access in a Testing zone server, while the app REST api would accept and handle different users, tokens, permission levels etc to everyone who passed the server security checks.

look for this question for more reference

score 1 · Answer 4 · answered Oct 06 '15 at 15:28

Question 1: Why use the HTTP Authentication and headers? As as far as I can tell, they are not offering me anything unless I am using them incorrectly? Why not just pass the username and password in the data param of the JS?

The query string is part of the URI. The URI is a resource identifier by REST, so it is part of the resource state. The identity, credentials, etc... of the user is part of the client state. Mixing the client state and the resource state by adding client state to the URI would be a violation of the stateless constraint of REST. The data part of other requests, like POST, PUT, DELETE is for describing resource representations, so you should not send auth data with it. Sending headers is the best approach and since HTTP has a dedicated Authorization header, you should use that.

Question 2: As stated earlier I have based my API design on the Cake plugin above, but from what I can see they ALWAYS pass the username and password with every request and then decide to use it or not if the user is logged in. Is this correct? To me, it seems more likely that authentication and requests for data should be handled separately. Otherwise I would have to store the username and password in my JavaScript somewhere so that I can send it with each request.

Your server should authenticate every request, in order to stay stateless. I am not sure about the logic of this lib, I think login is the wrong term to describe what happens, but from REST perspective the implementation details does not matter as long as it uses the HTTP standard properly, and the communication is stateless. The code has changed since you asked your question.

Question 3: How do I know if a user is logged in? I could set a variable to true and then pass that as part of my JSON with every request, but can a session work with an external device?

The server does not care whether the client is logged in, since it is client state. If you send a request that requires permissions, then you have to send the data necessary to authenticate the user.

Using HTTP Authentication

4 Answers4