CakePHP Authorization

https://github.com/cakephp/authorization
Admin
CakePHP Authorization is a plugin that provides authorization and access control for CakePHP...
Tokens:17,157
Snippets:171
Trust Score:9.3
License:MIT
Update:8 hours ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/cakephp/authorization/blob/3.x/readme.md

Use this command to install the cakephp/authorization plugin via Composer.

```bash
composer require cakephp/authorization
```

--------------------------------

### Example usage of applyScope, authorize, and authorizeModel

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Shows typical usage in controller actions: applying a scope to a query, authorizing an entity, and authorizing the model.

```php
public function index()
{
    $query = $this->Articles->find();
    $this->Authorization->applyScope($query);
}

public function delete($id)
{
    $article = $this->Articles->get($id);
    $this->Authorization->authorize($article);
}

public function add()
{
    $this->Authorization->authorizeModel();
}
```

--------------------------------

### Install with Composer

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Run this command in your CakePHP project root to install the plugin. Requires Composer.

```bash
php composer.phar require "cakephp/authorization:^3.0"
```

--------------------------------

### Implement BeforePolicyInterface for common checks

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

The before() hook can return true to allow, false to deny, or null to let the normal method run. This example allows admins immediately.

```php
namespace App\Policy;

use Authorization\IdentityInterface;
use Authorization\Policy\BeforePolicyInterface;
use Authorization\Policy\ResultInterface;

class ArticlesPolicy implements BeforePolicyInterface
{
    public function before(?IdentityInterface $identity, mixed $resource, string $action): ResultInterface|bool|null
    {
        if ($identity->getOriginalData()->is_admin) {
            return true;
        }

        return null;
    }
}
```

--------------------------------

### Create an empty ArticlePolicy class

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

Policies are classes in src/Policy that do not need to extend a base class. This example shows the basic structure for an entity policy.

```php
<?php
namespace App\Policy;

use App\Model\Entity\Article;
use Authorization\IdentityInterface;

class ArticlePolicy
{
}
```

--------------------------------

### Configure AuthorizationMiddleware with CustomRedirect handler

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Reference the custom handler in the middleware configuration by setting 'className' to 'CustomRedirect'. Additional handler configuration is passed through the 'options' array and is available in the handle() method. The example includes exception classes and a custom parameter.

```php
use Authorization\Exception\ForbiddenException;
use Authorization\Exception\MissingIdentityException;

$middlewareQueue->add(new AuthorizationMiddleware($this, [
    'unauthorizedHandler' => [
        'className' => 'CustomRedirect',
        'url' => '/users/login',
        'queryParam' => 'redirectUrl',
        'exceptions' => [
            MissingIdentityException::class,
            ForbiddenException::class,
        ],
        'custom_param' => true,
    ],
]));
```

--------------------------------

### Get Authorization Service

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Implement this method in Application.php to return the authorization service using the OrmResolver.

```php
public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface
{
    $resolver = new OrmResolver();

    return new AuthorizationService($resolver);
}
```

--------------------------------

### Define a policy scope to restrict list views

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

Scopes modify another object with authorization conditions. This example restricts a query to the current user's articles.

```php
namespace App\Policy;

class ArticlesTablePolicy
{
    public function scopeIndex($user, $query)
    {
        return $query->where(['Articles.user_id' => $user->getIdentifier()]);
    }
}
```

--------------------------------

### MapResolver usage with classname, instance, and callable

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policy-resolvers.md

Shows how to map resource classes to policy classnames, instances, or factory callables using MapResolver.

```php
use Authorization\Policy\MapResolver;

$mapResolver = new MapResolver();

// Map a resource class to a policy classname
$mapResolver->map(Article::class, ArticlePolicy::class);

// Map a resource class to a policy instance
$mapResolver->map(Article::class, new ArticlePolicy());

// Map a resource class to a factory callable
$mapResolver->map(Article::class, function ($resource, $mapResolver) {
    // Return a policy object.
});
```

--------------------------------

### Load Authorization Component

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Add this to AppController::initialize() to load the component.

```php
public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('Authorization.Authorization');
}
```

--------------------------------

### Load Plugin in Application.php

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Add this line in the Application class to load the plugin.

```php
$this->addPlugin('Authorization');
```

--------------------------------

### OrmResolver constructor customization

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policy-resolvers.md

Shows how to customize OrmResolver with an app namespace and policy class name overrides.

```php
use Authorization\Policy\OrmResolver;

$appNamespace = 'App';
$overrides = [
    'Blog' => 'Cms',
];

$resolver = new OrmResolver($appNamespace, $overrides);
```

--------------------------------

### Load RequestAuthorizationMiddleware after AuthorizationMiddleware

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/request-authorization-middleware.md

Adds both middleware instances to the middleware queue in the correct order.

```php
public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    $middlewareQueue->add(new AuthorizationMiddleware($this));
    $middlewareQueue->add(new RequestAuthorizationMiddleware());

    return $middlewareQueue;
}
```

--------------------------------

### Generate ORM policy classes with Bake

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

Use these commands to generate empty entity and table policy classes.

```bash
# Create an entity policy
bin/cake bake policy --type entity Article

# Create a table policy
bin/cake bake policy --type table Articles
```

--------------------------------

### Register Authorization Middleware

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Add the AuthorizationMiddleware to the middleware queue. Must be added after authentication.

```php
public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    $middlewareQueue->add(new ErrorHandlerMiddleware(Configure::read('Error')))
        ->add(new AssetMiddleware())
        ->add(new RoutingMiddleware($this))
        ->add(new BodyParserMiddleware())

        // If you use Authentication it must come before Authorization.
        ->add(new AuthenticationMiddleware($this))

        // Add Authorization after routing, body parsing, and authentication.
        ->add(new AuthorizationMiddleware($this));

    return $middlewareQueue;
}
```

--------------------------------

### Apply policy scope with applyScope()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Applies a policy scope to a query. Raises MissingIdentityException if there is no logged-in user.

```php
$query = $this->Authorization->applyScope($this->Articles->find());
```

--------------------------------

### Map actions to policy method names with mapActions() and mapAction()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Maps controller actions to different policy method names. Both array and fluent interface usage are shown.

```php
$this->Authorization->mapActions([
    'index' => 'list',
    'delete' => 'remove',
    'add' => 'insert',
]);

$this->Authorization
    ->mapAction('index', 'list')
    ->mapAction('delete', 'remove')
    ->mapAction('add', 'insert');
```

--------------------------------

### Implement AuthorizationServiceProviderInterface in Application

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Adds the AuthorizationMiddleware to the middleware queue and provides the authorization service with an OrmResolver. Required to use the middleware.

```php
namespace App;

use Authorization\AuthorizationService;
use Authorization\AuthorizationServiceInterface;
use Authorization\AuthorizationServiceProviderInterface;
use Authorization\Middleware\AuthorizationMiddleware;
use Authorization\Policy\OrmResolver;
use Cake\Http\BaseApplication;
use Psr\Http\Message\ServerRequestInterface;

class Application extends BaseApplication implements AuthorizationServiceProviderInterface
{
    public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface
    {
        $resolver = new OrmResolver();

        return new AuthorizationService($resolver);
    }

    public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
    {
        $middlewareQueue->add(new AuthorizationMiddleware($this));

        return $middlewareQueue;
    }
}
```

--------------------------------

### Load the plugin

Source: https://github.com/cakephp/authorization/blob/3.x/readme.md

Use this command to load the Authorization plugin into your CakePHP application.

```bash
bin/cake plugin load Authorization
```

--------------------------------

### Implement AuthorizationServiceProviderInterface

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Declare that your Application class implements the interface to provide the authorization service.

```php
class Application extends BaseApplication implements AuthorizationServiceProviderInterface
```

--------------------------------

### Implement BeforeScopeInterface for scope pre-conditions

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

Returning a modified resource short-circuits the normal scope method. Returning null allows the scope method to run normally.

```php
namespace App\Policy;

use Authorization\Policy\BeforeScopeInterface;

class ArticlesTablePolicy implements BeforeScopeInterface
{
    public function beforeScope($user, $query, $action)
    {
        if ($user->getOriginalData()->is_trial_user) {
            return $query->where(['Articles.is_paid_only' => false]);
        }

        return null;
    }
}
```

--------------------------------

### Return a Result object from a policy method

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

Use Authorization\Policy\Result to provide additional context. The second argument is a reason string, here 'not-owner'.

```php
use Authorization\Policy\Result;

public function canUpdate(IdentityInterface $user, Article $article): Result
{
    if ($user->id === $article->user_id) {
        return new Result(true);
    }

    return new Result(false, 'not-owner');
}
```

--------------------------------

### Apply scope conditions with applyScope()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/checking-authorization.md

Apply authorization conditions to collections such as paginated queries so only accessible records are returned.

```php
$user = $this->request->getAttribute('identity');
$query = $user->applyScope('index', $query);
```

--------------------------------

### Add Authorization Imports

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Add these use statements to your Application class to access the authorization classes.

```php
use Authorization\AuthorizationService;
use Authorization\AuthorizationServiceInterface;
use Authorization\AuthorizationServiceProviderInterface;
use Authorization\Middleware\AuthorizationMiddleware;
use Authorization\Policy\OrmResolver;
use Psr\Http\Message\ServerRequestInterface;
```

--------------------------------

### Create RequestPolicy class in src/Policy/RequestPolicy.php

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/request-authorization-middleware.md

Defines a request policy implementing RequestPolicyInterface with a canAccess method that returns true for Articles/index requests and false otherwise.

```php
namespace App\Policy;

use Authorization\Policy\RequestPolicyInterface;
use Authorization\Policy\ResultInterface;
use Cake\Http\ServerRequest;

class RequestPolicy implements RequestPolicyInterface
{
    public function canAccess($identity, ServerRequest $request): bool|ResultInterface
    {
        if ($request->getParam('controller') === 'Articles'
            && $request->getParam('action') === 'index'
        ) {
            return true;
        }

        return false;
    }
}
```

--------------------------------

### Implement IdentityInterface on User entity

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Use your own user class as the identity by implementing Authorization\IdentityInterface and providing the required methods. The class must also implement the setAuthorization method to store the service.

```php
namespace App\Model\Entity;

use Authorization\AuthorizationServiceInterface;
use Authorization\IdentityInterface;
use Authorization\Policy\ResultInterface;
use Cake\ORM\Entity;

class User extends Entity implements IdentityInterface
{
    public function can(string $action, mixed $resource): bool
    {
        return $this->authorization->can($this, $action, $resource);
    }

    public function canResult(string $action, mixed $resource): ResultInterface
    {
        return $this->authorization->canResult($this, $action, $resource);
    }

    public function applyScope(string $action, mixed $resource, mixed ...$optionalArgs): mixed
    {
        return $this->authorization->applyScope($this, $action, $resource, ...$optionalArgs);
    }

    public function getOriginalData(): \ArrayAccess|array
    {
        return $this;
    }

    public function setAuthorization(AuthorizationServiceInterface $service): static
    {
        $this->authorization = $service;

        return $this;
    }
}
```

--------------------------------

### Configure unauthorized handler with redirect

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Configures AuthorizationMiddleware to redirect unauthorized requests to a login page using the 'Authorization.Redirect' handler. Includes shared redirect options like 'queryParam', 'exceptions', and 'allowedRedirectExtensions'.

```php
use Authorization\Exception\MissingIdentityException;

$middlewareQueue->add(new AuthorizationMiddleware($this, [
    'unauthorizedHandler' => [
        'className' => 'Authorization.Redirect',
        'url' => '/pages/unauthorized',
        'queryParam' => 'redirectUrl',
        'exceptions' => [
            MissingIdentityException::class,
            OtherException::class,
        ],
        'allowedRedirectExtensions' => ['csv', 'pdf'],
    ],
]));
```

--------------------------------

### Attach middleware only to application controller

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/request-authorization-middleware.md

In the initialize method, wraps RequestAuthorizationMiddleware in a closure to attach it only to the application controller, useful when fallback routing is enabled.

```php
public function initialize(): void
{
    parent::initialize();

    $this->middleware(function ($request, $handler): ResponseInterface {
        $config = [
            'unauthorizedHandler' => [
                // ...
            ],
        ];
        $middleware = new RequestAuthorizationMiddleware($config);

        return $middleware->process($request, $handler);
    });
}
```

--------------------------------

### Map request class to policy in getAuthorizationService()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/request-authorization-middleware.md

Configures the MapResolver to map ServerRequest to RequestPolicy and returns an AuthorizationService instance.

```php
use App\Policy\RequestPolicy;
use Authorization\AuthorizationService;
use Authorization\AuthorizationServiceInterface;
use Authorization\Middleware\AuthorizationMiddleware;
use Authorization\Middleware\RequestAuthorizationMiddleware;
use Authorization\Policy\MapResolver;
use Cake\Http\ServerRequest;
use Psr\Http\Message\ServerRequestInterface;

public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface
{
    $mapResolver = new MapResolver();
    $mapResolver->map(ServerRequest::class, RequestPolicy::class);

    return new AuthorizationService($mapResolver);
}
```

--------------------------------

### Authorize an entity with authorize()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Checks authorization for an entity in a controller action. Throws Authorization\Exception\ForbiddenException when access is denied.

```php
public function edit($id)
{
    $article = $this->Articles->get($id);
    $this->Authorization->authorize($article);

    // Rest of edit method
}
```

--------------------------------

### ResolverCollection combining multiple resolvers

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policy-resolvers.md

Shows how to combine MapResolver and OrmResolver in a ResolverCollection to check explicit maps first and fall back to ORM conventions.

```php
use Authorization\Policy\ResolverCollection;
use Authorization\Policy\MapResolver;
use Authorization\Policy\OrmResolver;

$ormResolver = new OrmResolver();
$mapResolver = new MapResolver();

$resolver = new ResolverCollection([$mapResolver, $ormResolver]);
```

--------------------------------

### Authorize Resource in Controller Action

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/index.md

Use the component's authorize() method to check permissions for an action.

```php
public function edit($id = null)
{
    $article = $this->Articles->get($id);
    $this->Authorization->authorize($article, 'update');

    // Rest of action
}
```

--------------------------------

### Check authorization with can() for boolean result

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Returns a boolean result instead of throwing an exception. Useful for conditional logic.

```php
if ($this->Authorization->can($article, 'update')) {
    // Do something to the article
}
```

--------------------------------

### Create CustomRedirectHandler class extending RedirectHandler

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Define a custom unauthorized handler that calls the parent handler and adds a flash error message before returning the response. The handler receives the exception, request, and options array, and the flash message is added via the request's flash component.

```php
<?php
declare(strict_types=1);

namespace App\Middleware\UnauthorizedHandler;

use Authorization\Exception\Exception;
use Authorization\Middleware\UnauthorizedHandler\RedirectHandler;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

class CustomRedirectHandler extends RedirectHandler
{
    public function handle(Exception $exception, ServerRequestInterface $request, array $options = []): ResponseInterface
    {
        $response = parent::handle($exception, $request, $options);
        $request->getFlash()->error('You are not authorized to access that location');

        return $response;
    }
}
```

--------------------------------

### Add more exception types to unauthorized handler

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Shows how to extend the list of exceptions that trigger the unauthorized handler, allowing graceful handling of additional exception types beyond the default.

```php
'exceptions' => [
    MissingIdentityException::class,
    ForbiddenException::class,
],
```

--------------------------------

### Skip authorization for public actions with skipAuthorization option

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Marks actions as public by skipping authorization. By default, every action requires authorization when checking is enabled.

```php
$this->loadComponent('Authorization.Authorization', [
    'skipAuthorization' => [
        'login',
    ],
]);
```

--------------------------------

### Configure automatic authorization checks with authorizeModel()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Configures the component to authorize actions automatically based on the controller's default model class and the current action. Pass the action names to authorize.

```php
$this->Authorization->authorizeModel('index', 'add');
```

--------------------------------

### Check authorization with canResult()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/checking-authorization.md

Use `canResult()` when policies return result objects, allowing inspection of the status before proceeding.

```php
$result = $user->canResult('delete', $article);
if ($result->getStatus()) {
    // Do deletion
}
```

--------------------------------

### ControllerHookPolicy catch-all policy for legacy authorization

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policy-resolvers.md

A policy class that uses __call to delegate authorization to a controller's isAuthorized method, bridging legacy AuthComponent during migration.

```php
// in src/Policy/ControllerHookPolicy.php
namespace App\Policy;

class ControllerHookPolicy
{
    public function __call(string $name, array $arguments)
    {
        /** @var ?\Authorization\Identity $user */
        [$user, $controller] = $arguments;

        return $controller->isAuthorized($user?->getOriginalData());
    }
}
```

--------------------------------

### Define a policy method that returns a boolean

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policies.md

Policy methods must return true or a Result object. Any other return value is treated as failure. The method receives null for anonymous users unless typehinted with IdentityInterface.

```php
public function canEdit(IdentityInterface $user, Article $article): bool
{
    return $user->id === $article->user_id;
}
```

--------------------------------

### Skip authorization inside an action with skipAuthorization()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Skips authorization for the current action. Useful for public actions.

```php
public function view($id)
{
    $this->Authorization->skipAuthorization();
}
```

--------------------------------

### Check authorization with can()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/checking-authorization.md

Use `can()` to check if the user is authorized for a single resource, typically an ORM entity or domain object. The identity is obtained from the request attribute.

```php
$user = $this->request->getAttribute('identity');

if ($user->can('delete', $article)) {
    // Do delete operation
}
```

--------------------------------

### Implement both Authentication and Authorization identities

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

When using the cakephp/authentication plugin, implement both Authentication\IdentityInterface and Authorization\IdentityInterface on the same class. The getIdentifier method is required by the authentication identity.

```php
use Authentication\IdentityInterface as AuthenticationIdentity;
use Authorization\IdentityInterface as AuthorizationIdentity;

class User extends Entity implements AuthorizationIdentity, AuthenticationIdentity
{
    public function getIdentifier(): int|string|null
    {
        return $this->id;
    }
}
```

--------------------------------

### Configure middleware with identityDecorator option

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Configures the AuthorizationMiddleware to use a custom identity decorator that calls setAuthorization on the user object. This is used when your user class implements IdentityInterface.

```php
$middlewareQueue->add(new AuthorizationMiddleware($this, [
    'identityDecorator' => function ($auth, $user) {
        return $user->setAuthorization($auth);
    },
]));
```

--------------------------------

### Retrieve original identity with getOriginalData()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

When using the default IdentityDecorator, call getOriginalData() to access the underlying identity object.

```php
$originalUser = $user->getOriginalData();
```

--------------------------------

### ControllerResolver resolving policies for controllers

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/policy-resolvers.md

A custom resolver implementing ResolverInterface that returns a ControllerHookPolicy for Controller resources and throws MissingPolicyException otherwise.

```php
// in src/Policy/ControllerResolver.php
namespace App\Policy;

use Authorization\Policy\Exception\MissingPolicyException;
use Authorization\Policy\ResolverInterface;
use Cake\Controller\Controller;

class ControllerResolver implements ResolverInterface
{
    public function getPolicy($resource)
    {
        if ($resource instanceof Controller) {
            return new ControllerHookPolicy();
        }

        throw new MissingPolicyException([get_class($resource)]);
    }
}
```

--------------------------------

### Override action name in authorize()

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/component.md

Overrides the action name used for authorization. If omitted, the request action is used.

```php
$this->Authorization->authorize($article, 'update');
```

--------------------------------

### Disable authorization check requirement

Source: https://github.com/cakephp/authorization/blob/3.x/docs/en/middleware.md

Disables the default behavior where AuthorizationMiddleware raises AuthorizationRequiredException if a request with an identity has not performed or bypassed authorization checks. Useful during development and testing.

```php
$middlewareQueue->add(new AuthorizationMiddleware($this, [
    'requireAuthorizationCheck' => false,
]));
```
Tokens:
Raw