security-authorization.md 18.8 KB
Newer Older
1 2 3
Authorization
=============

4
> Note: This section is under development.
Qiang Xue committed
5

6 7
Authorization is the process of verifying that a user has enough permission to do something. Yii provides two authorization
methods: Access Control Filter (ACF) and Role-Based Access Control (RBAC).
8

9 10

Access Control Filter
11 12
---------------------

13 14 15 16 17 18
Access Control Filter (ACF) is a simple authorization method that is best used by applications that only need some
simple access control. As its name indicates, ACF is an action filter that can be attached to a controller or a module
as a behavior. ACF will check a set of [[yii\filters\AccessControl::rules|access rules]] to make sure the current user
can access the requested action.

The code below shows how to use ACF which is implemented as [[yii\filters\AccessControl]]:
19 20

```php
21 22
use yii\filters\AccessControl;

23 24
class SiteController extends Controller
{
25 26 27 28
    public function behaviors()
    {
        return [
            'access' => [
29
                'class' => AccessControl::className(),
30 31 32 33
                'only' => ['login', 'logout', 'signup'],
                'rules' => [
                    [
                        'allow' => true,
34
                        'actions' => ['login', 'signup'],
35 36 37 38
                        'roles' => ['?'],
                    ],
                    [
                        'allow' => true,
39
                        'actions' => ['logout'],
40 41 42 43 44 45 46
                        'roles' => ['@'],
                    ],
                ],
            ],
        ];
    }
    // ...
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
}
```

In the code above ACF is attached to the `site` controller as a behavior. This is the typical way of using an action
filter. The `only` option specifies that the ACF should only be applied to `login`, `logout` and `signup` actions.
The `rules` option specifies the [[yii\filters\AccessRule|access rules]], which reads as follows:

- Allow all guest (not yet authenticated) users to access 'login' and 'signup' actions. The `roles` option
  contains a question mark `?` which is a special token recognized as "guests".
- Allow authenticated users to access 'logout' action. The `@` character is another special token recognized as
  authenticated users.

When ACF performs authorization check, it will examine the rules one by one from top to bottom until it finds
a match. The `allow` value of the matching rule will then be used to judge if the user is authorized. If none
of the rules matches, it means the user is NOT authorized and ACF will stop further action execution.

By default, ACF does only of the followings when it determines a user is not authorized to access the current action:

* If the user is a guest, it will call [[yii\web\User::loginRequired()]], which may redirect the browser to the login page.
* If the user is already authenticated, it will throw a [[yii\web\ForbiddenHttpException]].

You may customize this behavior by configuring the [[yii\filters\AccessControl::denyCallback]] property:

```php
[
    'class' => AccessControl::className(),
    'denyCallback' => function ($rule, $action) {
        throw new \Exception('You are not allowed to access this page');
    }
]
77 78
```

79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
[[yii\filters\AccessRule|Access rules]] support many options. Below is a summary of the supported options.
You may also extend [[yii\filters\AccessRule]] to create your own customized access rule classes.

 * [[yii\filters\AccessRule::allow|allow]]: specifies whether this is an "allow" or "deny" rule.

 * [[yii\filters\AccessRule::actions|actions]]: specifies which actions this rule matches. This should
be an array of action IDs. The comparison is case-sensitive. If this option is empty or not set,
it means the rule applies to all actions.

 * [[yii\filters\AccessRule::controllers|controllers]]: specifies which controllers this rule
matches. This should be an array of controller IDs. The comparison is case-sensitive. If this option is
empty or not set, it means the rule applies to all controllers.

 * [[yii\filters\AccessRule::roles|roles]]: specifies which user roles that this rule matches.
Two special roles are recognized, and they are checked via [[yii\web\User::isGuest]]:
     - `?`: matches a guest user (not authenticated yet)
     - `@`: matches an authenticated user
Using other role names requires RBAC (to be described in the next section), and [[yii\web\User::can()]] will be called.
If this option is empty or not set, it means this rule applies to all roles.

MarsuBoss committed
99
 * [[yii\filters\AccessRule::ips|ips]]: specifies which [[yii\web\Request::userIP|client IP addresses]] this rule matches.
100 101 102 103 104 105
An IP address can contain the wildcard `*` at the end so that it matches IP addresses with the same prefix.
For example, '192.168.*' matches all IP addresses in the segment '192.168.'. If this option is empty or not set,
it means this rule applies to all IP addresses.

 * [[yii\filters\AccessRule::verbs|verbs]]: specifies which request method (e.g. `GET`, `POST`) this rule matches.
The comparison is case-insensitive.
106

107 108
 * [[yii\filters\AccessRule::matchCallback|matchCallback]]: specifies a PHP callable that should be called to determine
if this rule should be applied.
109

110 111
 * [[yii\filters\AccessRule::denyCallback|denyCallback]]: specifies a PHP callable that should be called when this rule
will deny the access.
112

113 114
Below is an example showing how to make use of the `matchCallback` option, which allows you to write arbitrary access
check logic:
115 116

```php
117 118
use yii\filters\AccessControl;

119 120
class SiteController extends Controller
{
121 122 123 124
    public function behaviors()
    {
        return [
            'access' => [
125
                'class' => AccessControl::className(),
126 127 128 129 130 131 132 133 134
                'only' => ['special-callback'],
                'rules' => [
                    [
                        'actions' => ['special-callback'],
                        'allow' => true,
                        'matchCallback' => function ($rule, $action) {
                            return date('d-m') === '31-10';
                        }
                    ],
135 136 137 138
                ],
            ],
        ];
    }
139

140 141 142 143 144
    // Match callback called! This page can be accessed only each October 31st
    public function actionSpecialCallback()
    {
        return $this->render('happy-halloween');
    }
145
}
146 147
```

148 149 150 151

Role based access control (RBAC)
--------------------------------

152 153 154 155 156
Role-Based Access Control (RBAC) provides a simple yet powerful centralized access control. Please refer to
the [Wiki article](http://en.wikipedia.org/wiki/Role-based_access_control) for details about comparing RBAC
with other more traditional access control schemes.

Yii implements a General Hierarchical RBAC, following the [NIST RBAC model](http://csrc.nist.gov/rbac/sandhu-ferraiolo-kuhn-00.pdf).
157
It provides the RBAC functionality through the [[yii\rbac\ManagerInterface|authManager]] [application component](structure-application-components.md).
158 159 160 161 162 163 164 165 166

Using RBAC involves two parts of work. The first part is to build up the RBAC authorization data, and the second
part is to use the authorization data to perform access check in places where it is needed.

To facilitate our description next, we will first introduce some basic RBAC concepts.


### Basic Concepts

167
A role represents a collection of *permissions* (e.g. creating posts, updating posts). A role may be assigned
168 169 170 171 172
to one or multiple users. To check if a user has a specified permission, we may check if the user is assigned
with a role that contains that permission.

Associated with each role or permission, there may be a *rule*. A rule represents a piece of code that will be
executed during access check to determine if the corresponding role or permission applies to the current user.
173 174
For example, the "update post" permission may have a rule that checks if the current user is the post creator.
During access checking, if the user is NOT the post creator, he/she will be considered not having the "update post" permission.
175 176 177 178 179 180 181 182 183

Both roles and permissions can be organized in a hierarchy. In particular, a role may consist of other roles or permissions;
and a permission may consist of other permissions. Yii implements a *partial order* hierarchy which includes the
more special *tree* hierarchy. While a role can contain a permission, it is not true vice versa.


### Configuring RBAC Manager

Before we set off to define authorization data and perform access checking, we need to configure the
184
[[yii\base\Application::authManager|authManager]] application component. Yii provides two types of authorization managers:
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
[[yii\rbac\PhpManager]] and [[yii\rbac\DbManager]]. The former uses a PHP script file to store authorization
data, while the latter stores authorization data in database. You may consider using the former if your application
does not require very dynamic role and permission management.

The following code shows how to configure `authManager` in the application configuration:

```php
return [
    // ...
    'components' => [
        'authManager' => [
            'class' => 'yii\rbac\PhpManager',
        ],
        // ...
    ],
];
```

The `authManager` can now be accessed via `\Yii::$app->authManager`.

205 206 207
> Tip: By default, [[yii\rbac\PhpManager]] stores RBAC data in three files: `@app/rbac/items.php`, `@app/rbac/assignments.php` and `@app/rbac/rules.php`.
  Make sure these files are writable by the Web server process if the authorization needs to be changed online.
  Sometimes you will need to create these files manually.
sitawit committed
208

209 210 211

### Building Authorization Data

Alexander Makarov committed
212
Building authorization data is all about the following tasks:
213

Alexander Makarov committed
214 215 216 217 218
- defining roles and permissions;
- establishing relations among roles and permissions;
- defining rules;
- associating rules with roles and permissions;
- assigning roles to users.
219

Alexander Makarov committed
220
Depending on authorization flexibility requirements the tasks above could be done in different ways.
221

Valentin Ts committed
222 223
If your permissions hierarchy doesn't change at all and you have a fixed number of users you can create a
[console command](tutorial-console.md#create-command) command that will initialize authorization data once via APIs offered by `authManager`:
224 225

```php
Alexander Makarov committed
226 227 228
<?php
namespace app\commands;

sitawit committed
229
use Yii;
Alexander Makarov committed
230 231 232 233 234 235 236 237 238 239
use yii\console\Controller;

class RbacController extends Controller
{
    public function actionInit()
    {
        $auth = Yii::$app->authManager;

        // add "createPost" permission
        $createPost = $auth->createPermission('createPost');
240
        $createPost->description = 'Create a post';
Alexander Makarov committed
241 242 243 244
        $auth->add($createPost);

        // add "updatePost" permission
        $updatePost = $auth->createPermission('updatePost');
245
        $updatePost->description = 'Update post';
Alexander Makarov committed
246 247 248 249 250 251 252 253 254 255 256 257 258 259
        $auth->add($updatePost);

        // add "author" role and give this role the "createPost" permission
        $author = $auth->createRole('author');
        $auth->add($author);
        $auth->addChild($author, $createPost);

        // add "admin" role and give this role the "updatePost" permission
        // as well as the permissions of the "author" role
        $admin = $auth->createRole('admin');
        $auth->add($admin);
        $auth->addChild($admin, $updatePost);
        $auth->addChild($admin, $author);

260
        // Assign roles to users. 1 and 2 are IDs returned by IdentityInterface::getId()
Alexander Makarov committed
261
        // usually implemented in your User model.
262 263
        $auth->assign($author, 2);
        $auth->assign($admin, 1);
Alexander Makarov committed
264 265
    }
}
266 267
```

268
After executing the command with `yii rbac/init` we'll get the following hierarchy:
269 270 271 272 273

![Simple RBAC hierarchy](images/rbac-hierarchy-1.png "Simple RBAC hierarchy")

Author can create post, admin can update post and do everything author can.

Alexander Makarov committed
274
If your application allows user signup you need to assign roles to these new users once. For example, in order for all
275
signed up users to become authors you in advanced application template you need to modify `frontend\models\SignupForm::signup()`
Alexander Makarov committed
276 277 278
as follows:

```php
279
public function signup()
Alexander Makarov committed
280
{
281 282 283 284 285 286 287
    if ($this->validate()) {
        $user = new User();
        $user->username = $this->username;
        $user->email = $this->email;
        $user->setPassword($this->password);
        $user->generateAuthKey();
        $user->save(false);
Alexander Makarov committed
288 289 290

        // the following three lines were added:
        $auth = Yii::$app->authManager;
291 292
        $authorRole = $auth->getRole('author');
        $auth->assign($authorRole, $user->getId());
Alexander Makarov committed
293 294 295

        return $user;
    }
296 297

    return null;
Alexander Makarov committed
298 299 300 301 302 303 304
}
```

For applications that require complex access control with dynamically updated authorization data, special user interfaces
(i.e. admin panel) may need to be developed using APIs offered by `authManager`.


305 306 307
> Tip: By default, [[yii\rbac\PhpManager]] stores RBAC data in three files: `@app/rbac/items.php`, `@app/rbac/assignments.php` and `@app/rbac/rules.php`.
  Make sure these files are writable by the Web server process if the authorization needs to be changed online.
  Sometimes you will need to create these files manually.
308 309 310 311 312


### Using Rules

As aforementioned, rules add additional constraint to roles and permissions. A rule is a class extending
313
from [[yii\rbac\Rule]]. It must implement the [[yii\rbac\Rule::execute()|execute()]] method. In the hierarchy we've
314
created previously author cannot edit his own post. Let's fix it. First we need a rule to verify that the user is the post author:
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340

```php
namespace app\rbac;

use yii\rbac\Rule;

/**
 * Checks if authorID matches user passed via params
 */
class AuthorRule extends Rule
{
    public $name = 'isAuthor';

    /**
     * @param string|integer $user the user ID.
     * @param Item $item the role or permission that this rule is associated with
     * @param array $params parameters passed to ManagerInterface::checkAccess().
     * @return boolean a value indicating whether the rule permits the role or permission it is associated with.
     */
    public function execute($user, $item, $params)
    {
        return isset($params['post']) ? $params['post']->createdBy == $user : false;
    }
}
```

341 342
The rule above checks if the `post` is created by `$user`. We'll create a special permission `updateOwnPost` in the
command we've used previously:
343 344

```php
345 346
$auth = Yii::$app->authManager;

347 348 349 350 351
// add the rule
$rule = new \app\rbac\AuthorRule;
$auth->add($rule);

// add the "updateOwnPost" permission and associate the rule with it.
352
$updateOwnPost = $auth->createPermission('updateOwnPost');
353
$updateOwnPost->description = 'Update own post';
354 355 356
$updateOwnPost->ruleName = $rule->name;
$auth->add($updateOwnPost);

357
// "updateOwnPost" will be used from "updatePost"
358
$auth->addChild($updateOwnPost, $updatePost);
359

360 361 362 363
// allow "author" to update their own posts
$auth->addChild($author, $updateOwnPost);
```

364 365 366
Now we've got the following hierarchy:

![RBAC hierarchy with a rule](images/rbac-hierarchy-2.png "RBAC hierarchy with a rule")
367 368 369 370 371 372 373 374 375 376 377 378 379

### Access Check

With the authorization data ready, access check is as simple as a call to the [[yii\rbac\ManagerInterface::checkAccess()]]
method. Because most access check is about the current user, for convenience Yii provides a shortcut method
[[yii\web\User::can()]], which can be used like the following:

```php
if (\Yii::$app->user->can('createPost')) {
    // create post
}
```

380 381 382 383 384
If the current user is Jane with ID=1 we're starting at `createPost` and trying to get to `Jane`:

![Access check](images/rbac-access-check-1.png "Access check")

In order to check if user can update post we need to pass an extra parameter that is required by the `AuthorRule` described before:
385 386

```php
387
if (\Yii::$app->user->can('updatePost', ['post' => $post])) {
388 389 390 391
    // update post
}
```

392 393 394 395 396 397 398 399 400 401 402 403
Here's what happens if current user is John:


![Access check](images/rbac-access-check-2.png "Access check")

We're starting with the `updatePost` and going through `updateOwnPost`. In order to pass it `AuthorRule` should return
`true` from its `execute` method. The method receives its `$params` from `can` method call so the value is
`['post' => $post]`. If everything is OK we're getting to `author` that is assigned to John.

In case of Jane it is a bit simpler since she's an admin:

![Access check](images/rbac-access-check-3.png "Access check")
404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424

### Using Default Roles

A default role is a role that is *implicitly* assigned to *all* users. The call to [[yii\rbac\ManagerInterface::assign()]]
is not needed, and the authorization data does not contain its assignment information.

A default role is usually associated with a rule which determines if the role applies to the user being checked.

Default roles are often used in applications which already have some sort of role assignment. For example, an application
may have a "group" column in its user table to represent which privilege group each user belongs to.
If each privilege group can be mapped to a RBAC role, you can use the default role feature to automatically
assign each user to a RBAC role. Let's use an example to show how this can be done.

Assume in the user table, you have a `group` column which uses 1 to represent the administrator group and 2 the author group.
You plan to have two RBAC roles `admin` and `author` to represent the permissions for these two groups, respectively.
You can create set up the RBAC data as follows,


```php
namespace app\rbac;

425
use Yii;
426 427 428
use yii\rbac\Rule;

/**
429
 * Checks if user group matches
430 431 432 433 434 435 436
 */
class UserGroupRule extends Rule
{
    public $name = 'userGroup';

    public function execute($user, $item, $params)
    {
437 438 439 440 441 442 443
        if (!Yii::$app->user->isGuest) {
            $group = Yii::$app->user->identity->group;
            if ($item->name === 'admin') {
                return $group == 1;
            } elseif ($item->name === 'author') {
                return $group == 1 || $group == 2;
            }
444
        }
445
        return false;
446 447 448
    }
}

449 450
$auth = Yii::$app->authManager;

451 452 453 454 455 456 457
$rule = new \app\rbac\UserGroupRule;
$auth->add($rule);

$author = $auth->createRole('author');
$author->ruleName = $rule->name;
$auth->add($author);
// ... add permissions as children of $author ...
458 459 460 461 462 463

$admin = $auth->createRole('admin');
$admin->ruleName = $rule->name;
$auth->add($admin);
$auth->addChild($admin, $author);
// ... add permissions as children of $admin ...
464 465
```

466 467 468 469 470
Note that in the above, because "author" is added as a child of "admin", when you implement the `execute()` method
of the rule class, you need to respect this hierarchy as well. That is why when the role name is "author",
the `execute()` method will return true if the user group is either 1 or 2 (meaning the user is in either "admin"
group or "author" group).

MarsuBoss committed
471
Next, configure `authManager` by listing the two roles in [[yii\rbac\BaseManager::$defaultRoles]]:
472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489

```php
return [
    // ...
    'components' => [
        'authManager' => [
            'class' => 'yii\rbac\PhpManager',
            'defaultRoles' => ['admin', 'author'],
        ],
        // ...
    ],
];
```

Now if you perform an access check, both of the `admin` and `author` roles will be checked by evaluating
the rules associated with them. If the rule returns true, it means the role applies to the current user.
Based on the above rule implementation, this means if the `group` value of a user is 1, the `admin` role
would apply to the user; and if the `group` value is 2, the `author` role would apply.