Download the PHP package uma/psr7-hmac-bundle without Composer

UMAPsr7HmacBundle

Clean integration between the Psr7Hmac authentication library and the Symfony Security Component.

Server setup

Add uma/psr7-hmac-bundle to your composer.json file:

php composer.phar require "uma/psr7-hmac-bundle"

And register the bundle in app/AppKernel.php:

Create your own User entity and implement the HmacApiClientInterface provided by the bundle. Alternatively you can implement the convenience HmacApiUserInterface, which groups Symfony's UserInterface and HmacApiClientInterface together.

The Symfony documentation offers plenty of guidance about how to implement the UserInterface. To implement the HmacApiClientInterface you can base your entity on the following skeleton, or check out the full example from the showcase project.

Finally, configure an hmac firewall in your app/config/security.yml file.

At this point you'll probably want to persist an ApiUser entity to start making your first requests, so make sure that you also have at least one route protected under your new firewall.

Client setup

In order to make an HMAC authenticated request, a client needs to install the Psr7Hmac library (available through Composer) and hold an API key and a shared secret from one of the application users. The lifecycle of an HMAC request goes like this:

Client side

1. The client prepares an instance of PSR-7's RequestInterface as needed. The Guzzle Request object is one such implementation, but Psr7Hmac supports many more.
2. It then sets an Api-Key HTTP header containing the API key.
3. A new instance of Psr7Hmac's Signer class is instantiated with the shared secret, and the resulting request from step 2 is passed to its sign method, which produces a signed request.
4. The signed request is sent to the server, for instance using Guzzle's Client service.

Server side

1. When the server receives the request it extracts its Api-Key header and looks for an ApiUser with a matching key.
2. If it finds one, it retrieves the user from the database and attempts to produce the same signature that was present in the request using his shared secret.
3. If the signatures match the authentication is successful,the request proceeds to the controller and the involved API user will be available through the Controller::getUser() helper and/or Symfony's TokenStorage service.
4. If any of the above 3 steps fails, the bundle arranges an 401 Unauthorized response on behalf of the application and the controller is never reached.

Brief client example

This example assumes:

• That the server (a Symfony application) has the bundle properly set up, as discussed above.
• That it has a persisted ApiUser fixture from which to get an API key and shared secret for the client.
• That the server defines a /hello/{name} like the one that used to be included in the DemoBundle of Symfony's Standard Edition of old.

If you modify the $signedRequest before sending it to the server it will return an HTTP 401 response.

Advanced client example

The use case that the UMAPsr7HmacBundle tries to solve is HMAC authentication between PHP backends communicating over HTTP. In this scenario it may possibly be the case that both the client and server are Symfony projects, and that the ApiUsers actually represent applications consuming some kind of service provided over HTTP by the server.

When that is indeed the case I would advise to leverage the DIC on the client side to do some of the work and build an agnostic "SDK service" that accepts plain PSR-7 requests, tags them with the Api-Key header, signs them, sends them and returns the server response.

This would be the general idea:

Advanced configuration

UMAPsr7HmacBundle sports a couple of knobs to customize it a little further.

Customize the Api-Key header

Set it at apikey_header under the hmac key in your security.yml file. Boom, done.

Customize the error response

By default the bundle will return a laconic 401 Unauthorized response for every authentication error that happens inside an hmac firewall.

However, Symfony's Security Component has a little known feature called entry points that are nothing more than implementations of the AuthenticationEntryPointInterface and let you do just that.

FAQ

I don't like long, random API keys

Well, then just return anything you want in the getApiKey() method from your user, for instance an email or whatever. Just make sure that these "API keys" are unique between all users, maybe even at the database level using UNIQUE constraints.

Shouldn't you store a hash of the shared secret in the server database, like you would do with a regular password?

That'd be kinda nice, but you can't.

The only reason you get to store user passwords as cryptographic hashes is because your application does not actually need their content, rather it just need to check that the stored password is the same that the one received during a login attempt, and to do that you can just compare their hashes. On the other hand the contents of a shared secret are actually needed in order to calculate an HMAC signature.

On a brighter note, machine-generated random shared secrets are not nearly as sensitive as user-provided passwords that are potentially reused all over the internet, so the extra hassle of hashing them may not even be warranted.