README

A php implementation of Macaroons: Cookies with Contextual Caveats for Decentralized Authorization

Specification

• https://research.google.com/pubs/pub41892.html
• https://github.com/rescrv/libmacaroons

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

Installation

Requirements

• php >= 7.0
• libsodium-php >= 1.0

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.

Installation

Add the library as a requirement in your composer.json

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

or with command line

$ composer require mvieira/macaroons

Documentation

Here is a simple example with a third party macaroon:

On the target service server, produce the macaroon authorizing the user to access the service.

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

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

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/

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

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

$ php ./examples/3-verification.php

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see LICENSE for more information.