Library: PropAuth (Property-based policy evaluation)

I’ve been working on a library for a while now that kind of distills down some of the ideas of property-based authorization (like XACML) and makes it a bit more accessible to the average developer. Property-based evaluation can be a little tricky to get your head around if you’re used to the usual RBAC world. Let me introduce it briefly.

Property-based evaluation is more or less what it sounds like: a system checks the properties of an object (or objects) and looks for different kinds of matches. That much is pretty simple but then you get into the “policies” aspect. This is where the real power comes in. With policies you can define the pass/fail requirements for the checks against an object and see if there’s a good enough match. With something like XACML it gets pretty complicated as it defines policies with XML documents (and we all know how “simple” XML is). There’s all sorts of different combining algorithms for the results like “first wins” or “all must match”. These can, of course, be nested and combined themselves leading to pretty complex policies and a mess if you’re not careful.

So, back to PropAuth now. In the work that I’ve been doing I’ve only really seen the need for a more streamlined version of this kind of evaluation. Some of the overall flexibility that XACML provides hasn’t been included in PropAuth, but I haven’t found much of a need for that so far anyway (like nested policies). The PropAuth library provides some of the basic property evaluation handling and policy creation I think could replace a lot of the mish-mash of role-based access control functionality out there and make for much more reusable code.

First off, to install just use Composer:

composer require psecio/propauth

And here’s a simple example of a policy evaluation:

<?php
require_once 'vendor/autoload.php';

$enforcer = new \Psecio\PropAuth\Enforcer();
$myUser = (object)[
    'username' => 'ccornutt'
];

$myPolicy = new \Psecio\PropAuth\Policy();
$myPolicy->hasUsername('ccornutt');

echo 'Result: '.var_export($enforcer->evaluate($myUser, $myPolicy), true);
?>

Here’s a quick summary of what’s happening here: the Enforcer object is the “frontend” that handles most of the work. You pass in a subject for the evaluation and the policy to evaluate against. In this case I’ve used the “hasUsername” check to look at the “username” property on the object and check to see if it matches the “ccornutt” value. The “evaluate” method is then called and a true/false result is returned…in this case true as our “myUser” object has a matching username.

This only scratches the surface of what the PropAuth library can do but it gives you an idea of how the evaluations are set up.

There’s also a simplified interface you can use with the same library to perform an authentication of a user with a system that uses bcrypted passwords (like with the password hashing API):

<?php
require_once 'vendor/autoload.php';

$password = $_POST['password'];

$myUser = (object)[
    'username' => 'ccornutt',
    'password' => password_hash('test1234', PASSWORD_DEFAULT)
];

$gate = new \Psecio\PropAuth\Gateway($myUser);
$subject = $gate->authenticate($password);
?>

If the password matches, you’ll be given an authenticated version of the “subject” back from the “authenticate” call. If not, you’ll get a false back on failure. Naturally, since this is all powered by the same library, you can also throw in policy checks too (warning: a bit more complicated example here):

<?php
require_once 'vendor/autoload.php';

$password = $_POST['password'];

$myUser = (object)[
    'username' => 'ccornutt',
    'password' => password_hash('test1234', PASSWORD_DEFAULT),
    'groups' => ['group1']
];

$policy = Policy::instance()->hasGroups(['group1', 'group2'], Policy::ANY);
$context = new Context([
    'policies' => PolicySet::instance()->add('policy1', $policy)
]);

$gate = new Gateway($myUser, $context);
if ($gate->authenticate($password) !== false && $gate->can('policy1')) {
    echo "They're authenticated and they have one of the required groups in the policy!";
}

?>

There’s a lot more going on here with a Policy Set and some of the “instance” calls but it’s all explained in the PropAuth documentation. I’d be interested in your feedback on the library and if you think it might be useful in your apps.

I’ve also put together a Provider for Laravel 5 applications that makes it simpler to incorporate the checks into both the controllers and your Blade templates, evaluating the policies directly.

There’s also a bit more detailed tutorial on using PropAuth over on the websec.io site with more information.