mvieira/macaroons

Macaroons

, _(*1)

A php implementation of Macaroons: Cookies with Contextual Caveats for Decentralized Authorization, _(*2)

Specification - https://research.google.com/pubs/pub41892.html - https://github.com/rescrv/libmacaroons, _(*3)

Resources - http://hackingdistributed.com/2014/05/21/my-first-macaroon/ - https://air.mozilla.org/macaroons-cookies-with-contextual-caveats-for-decentralized-authorization-in-the-cloud/ - https://evancordell.com/2015/09/27/macaroons-101-contextual-confinement.html, _(*4)

Installation

Requirements - php >= 7.0 - libsodium-php >= 1.0, _(*5)

About libsodium - The libsodium library will be distributed with PHP >= 7.2) - The libsodium library is not required in composer.json because the versions 1 (ext-libsodium) and 2 (ext-sodium) have different names. Nevertheless, this package should work with both once installed., _(*6)

Installation, _(*7)

Add the library as a requirement in your composer.json, _(*8)

{
    "require": {
        "mvieira/macaroons": "dev-master"
    }
}

or with command line, _(*9)

$ composer require mvieira/macaroons

Documentation

Here is a simple example with a third party macaroon:, _(*10)

On the target service server, produce the macaroon authorizing the user to access the service., _(*11)

use Macaroons\Macaroon;

use function Macaroons\Crypto\crypto_gen_nonce;

$macaroon = Macaroon::create('secret random number', crypto_gen_nonce(), 'https://unicorn.co');
$macaroon = $macaroon
    ->withThirdPartyCaveat('third party secret', 'user_auth', 'https://auth.unicorn.co');

On the identification provider server, produce the discharge macaroon that will verified the third party caveat, _(*12)

use Macaroons\Macaroon;

// user login happens beforehand...
// once the user manages to log in to the service

// Deserialize the root macaroon
$macaroon  = Macaroon::deserialize('@#!?$');

// prepare the discharge macaroon that will satisfied the third party caveat
$discharge = Macaroon::create('third party secret', 'user_auth', 'https://auth.unicorn.co')
    ->withFirstPartyCaveat('user_id = 12345678'); // add the requested first party caveat

// bind the discharge macaroon to the root macaroon
$discharge = $macaroon->bind($discharge);

Back on the target service server, _(*13)

use Macaroons\Macaroon;
use Macaroons\Verifier;
use Macaroons\Serialization\V1\Serializer;

// deserialize both macaroons
$macaroon  = Macaroon::deserialize('@#!?$', new Serializer());
$discharge = Macaroon::deserialize('#?@$!', new Serializer());

// prepare the verifier
$verifier = (new Verifier())
    ->satisfyExact('user_id = 12345678')
    ->withDischargeMacaroon($discharge);


try {
    $verified = $macaroon->verify('secret random number', $verifier);
} catch (\DomainException $e) {
    // Catch verification errors
    echo $e->getMessage() . "\n";
}

Examples

Examples are available in the directory ./examples/, _(*14)

$ php ./examples/1-target-service.php

$ php ./examples/2-identity-provider.php

$ php ./examples/3-verification.php

Contributing

Please see CONTRIBUTING for details., _(*15)

License

The MIT License (MIT). Please see LICENSE for more information., _(*16)