Merge pull request #535 from lonnieezell/add-filter-permission-and-group

Add filter permission and group

Author: lonnieezell

docs/authorization.md

@@ -9,6 +9,8 @@
       - [can()](#can)
       - [inGroup()](#ingroup)
       - [hasPermission()](#haspermission)
+      - [Authorizing via Filters](#authorizing-via-filters)
+      - [Authorizing via Routes](#authorizing-via-routes)
   - [Managing User Permissions](#managing-user-permissions)
       - [addPermission()](#addpermission)
       - [removePermission()](#removepermission)
@@ -128,6 +130,28 @@ if (! $user->hasPermission('users.create')) {
 }
 ```
 
+#### Authorizing via Filters
+
+You can restrict access to multiple routes through a [Controller Filter](https://codeigniter.com/user_guide/incoming/filters.html). One is provided for both restricting via groups the user belongs to, as well as which permission they need. The filters are automatically registered with the system under the `group` and `permission` aliases, respectively. You can define the protections within `app/Config/Filters.php`:
+
+```php
+public $filters = [
+    'group:admin,superadmin' => ['before' => ['admin/*']],
+    'permission:users.manage' => ['before' => ['admin/users/*']],
+];
+```
+
+#### Authorizing via Routes
+
+The filters can also be used on a route or route group level:
+
+```php
+$routes->group('admin', ['filter' => 'group:admin,superadmin'], static function ($routes) {
+    $routes->resource('users');
+});
+
+```
+
 ## Managing User Permissions
 
 Permissions can be granted on a user level as well as on a group level. Any user-level permissions granted will
@@ -199,7 +223,7 @@ $user->syncGroups('admin', 'beta');
 
 #### getGroups()
 
-Returns all groups this user is a part of. 
+Returns all groups this user is a part of.
 
 ```php
 $user->getGroups();

docs/install.md

@@ -135,15 +135,32 @@ your project.
     1. Use InnoDB, not MyISAM.
 
 ## Controller Filters
+The [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can use to protect your routes the shield provides are:
+
+```php
+public $aliases = [
+    // ...
+    'session'    => \CodeIgniter\Shield\Filters\SessionAuth::class,
+    'tokens'     => \CodeIgniter\Shield\Filters\TokenAuth::class,
+    'chain'      => \CodeIgniter\Shield\Filters\ChainAuth::class,
+    'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class,
+    'group'      => \CodeIgniter\Shield\Filters\GroupFilter::class,
+    'permission' => \CodeIgniter\Shield\Filters\PermissionFilter::class,
+];
+```
+
+Filters | Description
+--- | ---
+session and tokens | The `Session` and `AccessTokens` authenticators, respectively.
+chained | The filter will check both authenticators in sequence to see if the user is logged in through either of authenticators, allowing a single API endpoint to work for both an SPA using session auth, and a mobile app using access tokens.
+auth-rates | Provides a good basis for rate limiting of auth-related routes.
+group | Checks if the user is in one of the groups passed in.
+permission | Checks if the user has the passed permissions.
 
-Shield provides 4 [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) you can
-use to protect your routes, `session`, `tokens`, and `chained`. The first two cover the `Session` and
-`AccessTokens` authenticators, respectively. The `chained` filter will check both authenticators in sequence
-to see if the user is logged in through either of authenticators, allowing a single API endpoint to
-work for both an SPA using session auth, and a mobile app using access tokens. The fourth, `auth-rates`,
-provides a good basis for rate limiting of auth-related routes.
 These can be used in any of the [normal filter config settings](https://codeigniter.com/user_guide/incoming/filters.html?highlight=filter#globals), or [within the routes file](https://codeigniter.com/user_guide/incoming/routing.html?highlight=routs#applying-filters).
 
+> **Note** These filters are already loaded for you by the registrar class located at `src/Config/Registrar.php`.
+
 ### Protect All Pages
 
 If you want to limit all routes (e.g. `localhost:8080/admin`, `localhost:8080/panel` and ...), you need to add the following code in the `app/Config/Filters.php` file.
@@ -158,18 +175,6 @@ public $globals = [
 ];
 ```
 
-> **Note** These filters are already loaded for you by the registrar class located at `src/Config/Registrar.php`.
-
-```php
-public $aliases = [
-    // ...
-    'session'    => \CodeIgniter\Shield\Filters\SessionAuth::class,
-    'tokens'     => \CodeIgniter\Shield\Filters\TokenAuth::class,
-    'chain'      => \CodeIgniter\Shield\Filters\ChainAuth::class,
-    'auth-rates' => \CodeIgniter\Shield\Filters\AuthRates::class,
-];
-```
-
 ### Rate Limiting
 
 To help protect your authentication forms from being spammed by bots, it is recommended that you use

src/Authorization/AuthorizationException.php

@@ -19,4 +19,9 @@ public static function forUnknownPermission(string $permission): self
     {
         return new self(lang('Auth.unknownPermission', [$permission]));
     }
+
+    public static function forUnauthorized(): self
+    {
+        return new self(lang('Auth.notEnoughPrivilege'));
+    }
 }

src/Config/Registrar.php

@@ -8,6 +8,8 @@
 use CodeIgniter\Shield\Collectors\Auth;
 use CodeIgniter\Shield\Filters\AuthRates;
 use CodeIgniter\Shield\Filters\ChainAuth;
+use CodeIgniter\Shield\Filters\GroupFilter;
+use CodeIgniter\Shield\Filters\PermissionFilter;
 use CodeIgniter\Shield\Filters\SessionAuth;
 use CodeIgniter\Shield\Filters\TokenAuth;
 
@@ -24,6 +26,8 @@ public static function Filters(): array
                 'tokens'     => TokenAuth::class,
                 'chain'      => ChainAuth::class,
                 'auth-rates' => AuthRates::class,
+                'group'      => GroupFilter::class,
+                'permission' => PermissionFilter::class,
             ],
         ];
     }

src/Exceptions/GroupException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Exceptions;
+
+use CodeIgniter\Shield\Authorization\AuthorizationException;
+
+class GroupException extends AuthorizationException
+{
+}

src/Exceptions/PermissionException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Exceptions;
+
+use CodeIgniter\Shield\Authorization\AuthorizationException;
+
+class PermissionException extends AuthorizationException
+{
+}

src/Filters/AbstractAuthFilter.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Filters;
+
+use CodeIgniter\Filters\FilterInterface;
+use CodeIgniter\HTTP\RedirectResponse;
+use CodeIgniter\HTTP\RequestInterface;
+use CodeIgniter\HTTP\Response;
+use CodeIgniter\HTTP\ResponseInterface;
+
+/**
+ * Group Authorization Filter.
+ */
+abstract class AbstractAuthFilter implements FilterInterface
+{
+    /**
+     * Ensures the user is logged in and a member of one or
+     * more groups as specified in the filter.
+     *
+     * @param array|null $arguments
+     *
+     * @return RedirectResponse|void
+     */
+    public function before(RequestInterface $request, $arguments = null)
+    {
+        if (empty($arguments)) {
+            return;
+        }
+
+        if (! auth()->loggedIn()) {
+            return redirect()->route('login');
+        }
+
+        if ($this->isAuthorized($arguments)) {
+            return;
+        }
+
+        // If the previous_url is from this site, then
+        // we can redirect back to it.
+        if (strpos(previous_url(), site_url()) === 0) {
+            return redirect()->back()->with('error', lang('Auth.notEnoughPrivilege'));
+        }
+
+        // Otherwise, we'll just send them to the home page.
+        return redirect()->to('/')->with('error', lang('Auth.notEnoughPrivilege'));
+    }
+
+    /**
+     * We don't have anything to do here.
+     *
+     * @param Response|ResponseInterface $response
+     * @param array|null                 $arguments
+     */
+    public function after(RequestInterface $request, ResponseInterface $response, $arguments = null): void
+    {
+        // Nothing required
+    }
+
+    abstract protected function isAuthorized(array $arguments): bool;
+}

src/Filters/GroupFilter.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Filters;
+
+/**
+ * Group Authorization Filter.
+ */
+class GroupFilter extends AbstractAuthFilter
+{
+    /**
+     * Ensures the user is logged in and a member of one or
+     * more groups as specified in the filter.
+     */
+    protected function isAuthorized(array $arguments): bool
+    {
+        return auth()->user()->inGroup(...$arguments);
+    }
+}

src/Filters/PermissionFilter.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Filters;
+
+/**
+ * Permission Authorization Filter.
+ */
+class PermissionFilter extends AbstractAuthFilter
+{
+    /**
+     * Ensures the user is logged in and has one or more
+     * of the permissions as specified in the filter.
+     */
+    protected function isAuthorized(array $arguments): bool
+    {
+        foreach ($arguments as $permission) {
+            if (auth()->user()->can($permission)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

src/Language/de/Auth.php

@@ -19,6 +19,7 @@
     'invalidEmail'          => 'Es konnte nicht überprüft werden, ob die E-Mail-Adresse mit der gespeicherten übereinstimmt.',
     'unableSendEmailToUser' => 'Leider gab es ein Problem beim Senden der E-Mail. Wir konnten keine E-Mail an "{0}" senden.',
     'throttled'             => 'Es wurden zu viele Anfragen von dieser IP-Adresse gestellt. Sie können es in {0} Sekunden erneut versuchen.',
+    'notEnoughPrivilege'    => 'Sie haben nicht die erforderliche Berechtigung, um den gewünschten Vorgang auszuführen.',
 
     'email'           => 'E-Mail-Adresse',
     'username'        => 'Benutzername',