A php implementation of Macaroons: Cookies with Contextual Caveats for Decentralized Authorization
Specification
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
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 incomposer.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
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 are available in the directory ./examples/
$ php ./examples/1-target-service.php
$ php ./examples/2-identity-provider.php
$ php ./examples/3-verification.php
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see LICENSE for more information.