API Query Authentication With Query Auth

Aug13th, 201312:57 pm

Most APIs require some sort of query authentication: a method of signing API
requests with an API key and signature. The signature is usually generated
using a shared secret. When you’re consuming an API, there are (hopefully) easy
to follow steps to create signatures. When you’re writing your own API, you
have to whip up both server-side signature validation and a client-side
signature creation strategy. Query Auth
endeavors to handle both of those tasks; signature creation and signature validation.

Philosophy

Query Auth is intended to be – and is written as – a bare bones library. Many of
niceties and abstractions you’d find in a fully featured API library or SDK are
absent. The point of the library is to provide you with the ability to
focus on writing the meat of your API while offloading the authentication bits.

What’s Included?

There are three components to Query Auth: request signing for API consumers
and creators, request signature validation for API creators, and API key and
API secret generation.

Client::getSignedRequestParams() returns an array of parameters to send via
the querystring (for GET requests) or the request body. The parameters are
those provided to the method (if any), plus timestamp, key, and signature.

Signature Validation

1234567891011121314

$collection=newQueryAuth\NormalizedParameterCollection();$signer=newQueryAuth\Signer($collection);$server=newQueryAuth\Server($signer);$secret='API_SECRET_FROM_PERSISTENCE_LAYER';$method='GET';$host='api.example.com';$path='/resources';// querystring params or request body as an array,// which includes timestamp, key, and signature params from the client's// getSignedRequestParams method$params='PARAMS_FROM_REQUEST';$isValid=$server->validateSignature($secret,$method,$host,$path,$params);

Server::validateSignature() will return either true or false. It might also
throw one of three exceptions:

MaximumDriftExceededException: If timestamp is too far in the future

MinimumDriftExceededException: It timestamp is too far in the past

SignatureMissingException: If signature is missing from request params

Drift defaults to 15 seconds, meaning there is a 30 second window during which the
request is valid. The default value can be modified using Server::setDrift().

Both key and secret are generated using Anthony Ferrara’s RandomLib
random string generator.

That’s Kinda Ugly, Dude

As I pointed out, the Query Auth library is pretty bare bones. There are a lot
of opportunities for abstraction that would make the library much easier to use
and much nicer to look at. If I added them to Query Auth, however, that
would lock library users into whichever HTTP client I chose to use. The same
concern would go for whatever other abstractions I decided on. The point here is
to offload query authentication, and only query authentication, to the Query Auth
library.

Sample Implementation

In order to demonstrate how one might implement the Query Auth library, I’ve whipped
up a sample implementation for you.

The sample uses Vagrant and VirtualBox
to allow you to see the whole thing in action. Slim Framework
runs the API, Guzzle is used to make requests to the API,
and both a GET and POST request are implemented. JSend,
Jamie Schembri’s PHP implementation of the
OmniTI JSend specifiction, is used to send
messages back from the API, and Parsedown PHP,
Emanuil Rusev’s Markdown parser for PHP, is used to render the sample implementation’s
documentation.

Request Signing

In the sample implementation, request signing has been abstracted in the
Example\ApiRequestSigner class. Signing requests is now as simple as passing
the request object and credentials object to the signRequest method:

Signature Validation

In the sample implementation, signature validation has been abstracted in the
Example\ApiRequestValidator class. Validating request signatures is now as
simple as passing the request object and credentials object to the isValid
method:

Signing a GET Request

Signing a request is now extremely clean and simple. Here’s the GET example from
the sample implementation.

12345678910111213141516

/** * Sends a signed GET request which returns a famous mangled phrase */$app->get('/get-example',function()use($app,$credentials,$requestSigner){// Create request$guzzle=newGuzzleClient('http://query-auth.dev');$request=$guzzle->get('/api/get-example');// Sign request$requestSigner->signRequest($request,$credentials);$response=$request->send();$app->render('get.html',array('request'=>(string)$request,'response'=>(string)$response));});

Validating a GET Request

Validating a GET request is equally clean and simple. Note the try/catch that
handles possible exceptions from the validation class.

1234567891011121314151617181920212223242526

/** * Validates a signed GET request and, if the request is valid, returns a * famous mangled phrase */$app->get('/api/get-example',function()use($app,$credentials,$requestValidator){try{// Validate the request signature$isValid=$requestValidator->isValid($app->request(),$credentials);if($isValid){$mistakes=array('necktie','neckturn','nickle','noodle');$format='Klaatu... barada... n... %s!';$data=array('message'=>sprintf($format,$mistakes[array_rand($mistakes)]));$jsend=newJSendResponse('success',$data);}else{$jsend=newJSendResponse('fail',array('message'=>'Invalid signature'));}}catch(\Exception$e){$jsend=newJSendResponse('error',array(),$e->getMessage());}$response=$app->response();$response['Content-Type']='application/json';echo$jsend->encode();});

Wrapping Up

So there you have it: QueryAuth
to sign and validate API requests (and generate keys and secrets!) and a
sample implementation to
get you going. If you find this helpful, or have any questions or comments,
please let me know. If you find any horrible mistakes, please feel free to
submit an issue or a
pull request, or you can
always submit the offending code to CSI: PHP :-)