Git Product home page Git Product logo

http-hmac-php's Introduction

HTTP HMAC Signer for PHP

Build Status Total Downloads Latest Stable Version License

This library implements version 2.0 of the HTTP HMAC Spec to sign and verify RESTful Web API requests. It integrates with popular frameworks and libraries, like Symfony and Guzzle, and can be used on both the server and client.

Installation

Use Composer and add it as a dependency to your project's composer.json file:

{
    "require": {
        "acquia/http-hmac-php": "^5.0"
    }
}

Please refer to Composer's documentation for more detailed installation and usage instructions.

Usage

Sign an API request sent via Guzzle

require_once 'vendor/autoload.php';

use Acquia\Hmac\Guzzle\HmacAuthMiddleware;
use Acquia\Hmac\Key;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

// Create the HTTP HMAC key.
// A key consists of and ID and a Base64-encoded shared secret.
// Note: the API provider may have already encoded the secret. In this case, it should not be re-encoded.
$key_id = 'e7fe97fa-a0c8-4a42-ab8e-2c26d52df059';
$key_secret = base64_encode('secret');
$key = new Key($key_id, $key_secret);

// Optionally, you can provide additional headers when generating the signature.
// The header keys need to be provided to the middleware below.
$headers = [
    'X-Custom-1' => 'value1',
    'X-Custom-2' => 'value2',
];

// Specify the API's realm.
// Consult the API documentation for this value.
$realm = 'Acquia';

// Create a Guzzle middleware to handle authentication during all requests.
// Provide your key, realm and the names of any additional custom headers.
$middleware = new HmacAuthMiddleware($key, $realm, array_keys($headers));

// Register the middleware.
$stack = HandlerStack::create();
$stack->push($middleware);

// Create a client.
$client = new Client([
    'handler' => $stack,
]);

// Request.
try {
    $result = $client->get('https://service.acquia.io/api/v1/widget', [
        'headers' => $headers,
    ]);
} catch (ClientException $e) {
    print $e->getMessage();
    $response = $e->getResponse();
}
  
print $response->getBody();

Authenticate the request using PSR-7-compatible requests

use Acquia\Hmac\RequestAuthenticator;
use Acquia\Hmac\ResponseSigner;

// $keyLoader implements \Acquia\Hmac\KeyLoaderInterface
$authenticator = new RequestAuthenticator($keyLoader);

// $request implements PSR-7's \Psr\Http\Message\RequestInterface
// An exception will be thrown if it cannot authenticate.
$key = $authenticator->authenticate($request);

$signer = new ResponseSigner($key, $request);
$signedResponse = $signer->signResponse($response);

Authenticate using Symfony's Security component

In order to use the provided Symfony integration, you will need to include the following optional libraries in your project's composer.json

{
    "require": {
        "symfony/psr-http-message-bridge": "~0.1",
        "symfony/security": "~3.0",
        "zendframework/zend-diactoros": "~1.3.5"
    }
}

Sample implementation:

# app/config/parameters.yml
parameters:
   hmac_keys: {"key": "secret"}

# app/config/services.yml
services:
    hmac.keyloader:
        class: Acquia\Hmac\KeyLoader
        arguments:
            $keys: '%hmac_keys%'

    hmac.request.authenticator:
        class: Acquia\Hmac\RequestAuthenticator
        arguments:
         - '@hmac.keyloader'
        public: false
        
    hmac.response.signer:
        class: Acquia\Hmac\Symfony\HmacResponseListener
        tags:
          - { name: kernel.event_listener, event: kernel.response, method: onKernelResponse }
          
    hmac.entry-point:
        class: Acquia\Hmac\Symfony\HmacAuthenticationEntryPoint

    hmac.security.authentication.provider:
        class: Acquia\Hmac\Symfony\HmacAuthenticationProvider
        arguments:
            - '@hmac.request.authenticator'
        public: false

    hmac.security.authentication.listener:
        class: Acquia\Hmac\Symfony\HmacAuthenticationListener
        arguments: ['@security.token_storage', '@security.authentication.manager', '@hmac.entry-point']
        public: false

# app/config/security.yml
security:
    # ...

    firewalls:
        hmac_auth:
            pattern:   ^/api/
            stateless: true
            hmac_auth: true
// src/AppBundle/AppBundle.php
namespace AppBundle;

use Acquia\Hmac\Symfony\HmacFactory;
use Symfony\Component\HttpKernel\Bundle\Bundle;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class AppBundle extends Bundle
{
    public function build(ContainerBuilder $container)
    {
        parent::build($container);
        $extension = $container->getExtension('security');
        $extension->addSecurityListenerFactory(new HmacFactory());
    }
}

PHPUnit testing a controller using HMAC HTTP authentication in Symfony:

  1. Add the service declaration:
# app/config/parameters_test.yml

services:
    test.client.hmac:
        class: Acquia\Hmac\Test\Mocks\Symfony\HmacClient
        arguments: ['@kernel', '%test.client.parameters%', '@test.client.history', '@test.client.cookiejar']
// src/AppBundle/Tests/HmacTestCase.php

namespace MyApp\Bundle\AppBundle\Tests;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Bundle\FrameworkBundle\Client;
use Acquia\Hmac\Key;

class HmacTestCase extends WebTestCase
{
    /**
     * @var Client
     */
    private $client;

    protected static function createClient(array $options = array(), array $server = array())
    {
        $kernel = static::bootKernel($options);

        $client = $kernel->getContainer()->get('test.client.hmac');
        $client->setServerParameters($server);

        return $client;
    }

    protected function setUp()
    {
        $this->client = static::createClient();

        $this->client->setKey(new Key('my-key', 'my-not-really-secret'));
    }

Contributing and Development

GNU Make and Composer are used to manage development dependencies and testing:

# Install depdendencies
make install

# Run test suite
make test

All code should adhere to the following standards:

Submit changes using GitHub's standard pull request workflow.

http-hmac-php's People

Contributors

charuag avatar cookieguru avatar cpliakas avatar eduardoweiland avatar gaitholabi avatar galphanet avatar itafroma avatar japerry avatar jeichorn avatar kevinhankens avatar mansinahar avatar mhouriet avatar miromichalicka avatar ndelrossi avatar peter279k avatar scrutinizer-auto-fixer avatar smatyas avatar steveedwardsacquia avatar svolpe43 avatar wadjeroudi avatar ynx avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.