How Clients Authenticate

Introduction

Clients authenticate passing credentials via the standard basic authentication, a standard method for an HTTP user agent to provide a username and password when making a request.

RESTHeart is stateless: there isn’t any authentication session and credentials must be sent on every request.

Some examples

With httpie use the -a option:

 http -a userid:password GET 127.0.0.1:8080/

With curl, use the –user options

curl -i --user userid:password -X GET 127.0.0.1:8080/

Basic Authentication for dummies

Basic Authentication requires the client to send its credentials with the Authorization request header.

The value of the Authorization request header must be: Basic base64(<userid> + ‘:’ + <password>)

In other words:

1. userid and password are combined into a string “userid:password”. Note the colon between userid and password (userid cannot contain the “:” character).
2. The resulting string is base 64 encoded
3. The string “Basic “ (note the space) is then put before the encoded string.

Authentication Token

If a request is successfully authenticated, an authentication token is generated by RESTHeart and included in every subsequent responses.

Following requests can either use the password or the auth token.

Authentication Token

The authentication token is used as a temporary password in the basic authentication scheme. This means that the Authorization request header can either be calculated from the password and the Auth-Token itself:

Authorization: Basic base64(<userid> + ':' + <password>) or Authorization: Basic base64(<userid> + ':' + <auth-token>)

Auth token information are passed in the following response headers:

Auth-Token: 6a81d622-5e24-4d9e-adc0-e3f7f2d93ac7
Auth-Token-Location: /_authtokens/user@si.com
Auth-Token-Valid-Until: 2015-04-16T13:28:10.749Z

Note the URI in the Auth-Token-Location header: the client can issue a GET request to obtain information about token or a DELETE request to invalidate it. Of course clients can only request their own tokens (otherwise response code will be 403 Forbidden).

The Authentication Token is a very important feature when you are developing a web application. Since every request needs to include the credentials, you need to store them either in a cookie or (better) in the session storage. The sign-in form can check the credentials using the actual password; if it succeeds, the auth token can be stored and used.

Pay attention to the authentication token in case of multi-node deployments (horizontal scalability). In this case, you need to either disable it or use a load balancer with the sticky session option or use a distributed auth token cache implementation (not yet available in the current version but you can ask for support).

The auth token are controlled by the following configuration options:

auth-token-enabled: true
auth-token-ttl: 15 # time to live after last read, in minutes

Suggested way to check credentials and obtain user’s roles

The default configuration file sets up the useful GetRoleHandler, bound to /_logic/roles/<userid>

The possible response codes of the request GET /_logic/roles/<userid> are:

• 401 Unauthorized => missing or wrong credentials
• 403 Forbidden, the userid in the URL does not match the one in the Authorization header
• 200 OK credentials match; the following response document is sent back:

 {
    "_embedded": {}, 
    "_links": {
        "self": {
            "href": "/_logic/roles/user@si.com"
        }
    }, 
    "authenticated": true, 
    "roles": [
        "USER"
    ]
}

Of course, if the request succeeds, the client gets back the auth token as well.

It is easy to check the user credentials from a login form with this handler: in case the client gets back 200, they match and the auth token can be stored for further request; otherwise passed credentials are wrong.

How to avoid the basic authentication popup in browsers

With basic authentication, browsers can show a awful login popup window and this is not what you usually want.

What happens behind the scene, is that the server sends the WWW-Authenticate response header that actually leads to it. 

You can avoid RESTHeart to actually send this header avoiding the popup login window altogether, either specifying the No-Auth-Challenge request header or using the noauthchallenge query parameter. In this case, RESTHeart will just respond with 401 Unauthorized in case of missing or wrong credentials.

This feature together with the authentication token, allows you to implement a form based authentication experience on top of the simple and effective basic authentication mechanism. You can refer to the blog example application for an example of such implementation.