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.
Request Signing
1 2 3 4 5 6 7 8 9 10 11 12 |
|
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Server::validateSignature()
will return either true or false. It might also
throw one of three exceptions:
MaximumDriftExceededException
: If timestamp is too far in the futureMinimumDriftExceededException
: It timestamp is too far in the pastSignatureMissingException
: 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()
.
Key Generation
You can generate API keys and secrets in the following manner.
1 2 3 4 5 6 7 8 9 |
|
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
Signing a GET Request
Signing a request is now extremely clean and simple. Here’s the GET
example from
the sample implementation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
Sample Request and Response
The code above produces the below request and response:
Request
1 2 3 |
|
Response
1 2 3 4 5 6 7 8 |
|
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 :-)