Authorization

Table of Contents

1. Introduction
2. Roles
   1. Creating Roles
   2. Deleting Roles
   3. Assigning Roles
   4. Revoking Roles
   5. Getting Subjects by Role
3. Permissions
   1. Registering a Permission with a Role
   2. Registering a Callback
   3. Registering an Overriding Callback
4. Authority
   1. Checking Permissions

Introduction

The authorization library simplifies how you check if a user should have access to resources. It provides many models that are common to most authorization schemes. It is meant to be used in conjunction with standards like OAuth2. With community help, it is possible for full OAuth2 support to eventually be provided out of the box.

Roles

A role is a way of describing what a subject is. Usually, roles, such as "editor" or "administrator" also have permissions. Rather than having to assign a permission to each subject, you can group those users by roles, and then assign a permission to that role.

To use Opulence's authorization library, you must implement:

• Opulence\Authorization\Roles\Orm\IRoleMembershipRepository
  • Stores and retrieves subjects' memberships to certain roles
• Opulence\Authorization\Roles\Orm\IRoleRepository
  • Stores and retrieves roles

The heart of roles is Opulence\Authorization\Roles\Roles. It can create roles, delete roles, assign roles to subjects, and retrieve subjects by role. It simply requires the two repositories above.

use Opulence\Authorization\Roles\Orm\IRoleMembershipRepository;
use Opulence\Authorization\Roles\Orm\IRoleRepository;
use Opulence\Authorization\Roles\Roles;

// Assume $roleMembershipRepository and $roleRepository were previously set
$roles = new Roles($roleMembershipRepository, $roleRepository);

Creating Roles

$roles->createRole('new-role'); // Returns the new Role object

Deleting Roles

$roles->deleteRole('role-to-delete');

Assigning Roles

// The Id of the subject that is getting this role
$subjectId = 123;
// You can also pass in an array of role names to assign
$roles->assignRoles($subjectId, 'new-role');

Revoking Roles

You can revoke a single role from a subject:

// The Id of the subject whose role is being revoked
$subjectId = 123;
// You can also pass in an array of role names to revoke
$roles->removeRolesFromSubject($subjectId, 'revoked-role');

You can also revoke all roles from a subject:

// The Id of the subject whose roles are being revoked
$subjectId = 123;
$roles->removeAllRolesFromSubject($subjectId);

Getting Subjects by Role

$subjectIdsWithRole = $roles->getSubjectIdsWithRole('search-role');

Permissions

Permissions are privileges granted to roles. Opulence provides Opulence\Authorization\Permissions\PermissionRegistry as a class to store the mapping of roles to permissions.

use Opulence\Authorization\Permissions\PermissionRegistry;

$registry = new PermissionRegistry();

Registering a Permission with a Role

$registry->registerRoles('create-posts', ['editor', 'author']);

Registering a Callback

If your permission logic is a bit more involved, you can register a callback to evaluate if a subject has a permission:

// Must accept the subject Id as a parameter
// Must return true if the role has the permission, otherwise false
// Assume $userRepository is some user repository
$callback = function ($subjectId) use ($userRepository) {
    $user = $userRepository->getById($subjectId);

    return $user->isACoolGuy();
};
$registry->registerCallback('create-users', $callback);

Registering an Overriding Callback

If you would like to short-circuit the permission checks, you may register what's called an "overriding callback". This is most useful in the case of admins who have access to all permissions.

$callback = function ($subjectId, string $permission) {
    // Let's say that subject with Id 1 is the admin
    return $subjectId === 1;
};
$registry->registerOverridingCallback($callback);

Authority

Opulence\Authorization\Authority provides the ability to check if a user has certain permissions.

use Opulence\Authorization\Authority;
use Opulence\Authorization\Permissions\PermissionRegistry;
use Opulence\Authorization\Roles\Roles;

$permissionRegistry = new PermissionRegistry();

// Set up the permission registry...

$authority = new Authority(
    $subjectId,
    $roles->getRolesForSubject($subjectId),
    $permissionRegistry
);

Checking Permissions

if ($authority->can('create-posts')) {
    $postRepository->save();
}

You can also check if a subject does not have a permission:

if ($authority->cannot('create-posts')) {
    die('You do not have permission to create posts');
}

If you'd like to check permissions on another subject, you may do so:

if ($authority->forSubject($subjectId, $subjectRoles)->can('delete-posts')) {
    $postRepository->save();
}