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.
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.
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.
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
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 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
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.
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
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
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
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
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
GET request is equally clean and simple. Note the
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:
1 2 3
1 2 3 4 5 6 7 8
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 :–)