Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News RESTful API Authentication Schemes

RESTful API Authentication Schemes

Leia em Português

This item in japanese

Lire ce contenu en français

Everyone feels the need to write a custom authentication protocolsays George Reese, which he claims is one of the things he learnt working on a programming API for cloud providers and Saas Vendors. In a post George proposes a set of standards for any REST authentication need.

George who has developed against myraid web service API’s, observes that each one requires a different authentication mechanism.

I'm tired of wasting brain cycles figuring out whether vendor A requires you to sign your query before or after you URL encode your parameters and I am fed up with vendors who insist on using interactive user credentials to authenticate API calls.

He outlines the rules for designing authentication schemes for REST API’s. “Let's just be blunt: if you aren't encrypting your API calls, you aren't even pretending to be secure”, He says,

1. All REST API calls must take place over HTTPS with a certificate signed by a trusted CA. All clients must validate the certificate before interacting with the server.

Through the use of certificates signed by a trusted authority, SSL also protects you against "man-in-the-middle" attacks in which an agent inserts itself between client and server and sniffs the "encrypted" traffic.

If you are not validating the SSL certificate of the server, you don't know who is receiving your REST queries.

2. All REST API calls should occur through dedicated API keys consisting of an identifying component and a shared, private secret. Systems must allow a given customer to have multiple active API keys and de-activate individual keys easily.

The first important thing is that a system making a REST query is NOT an interactive user. […] REST is authenticating a program and not person, it allows for stronger authentication than human user ID/password schemes allow.

The second part says that each REST server should support multiple API keys for each customer. This requirement makes it simpler to isolate potential compromises and address them when they happen. […] When an application is compromised, you also need an elegant way to roll out replacement API keys.

3. All REST queries must be authenticated by signing the query parameters sorted in lower-case, alphabetical order using the private credential as the signing token. Signing should occur before URL encoding the query string.

In other words, you don't pass the shared secret component of the API key as part of the query, but instead use it to sign the query. Your queries end up looking like this:

GET /object?timestamp=1261496500&apiKey=Qwerty2010&signature=abcdef0123456789

The string being signed is "/object?apikey=Qwerty2010&timestamp=1261496500" and the signature is the HMAC-SHA256 hash of that string using the private component of the API key.

He admits that in most RESTlike and RESTFul API solutions that authentication is most certainly a secondary consideration. However, in the conclusion of his article he urges readers "to follow someone else's example and not roll your own authentication scheme”.

Be sure to weigh in on the recommendations. The original post can be found at the O’Rielly community blogs.

Rate this Article