授權(quán)

授權(quán)是指驗(yàn)證用戶是否允許做某件事的過(guò)程。Yii提供兩種授權(quán)方法： 存取控制過(guò)濾器（ACF）和基于角色的存取控制（RBAC）。

存取控制過(guò)濾器

存取控制過(guò)濾器（ACF）是一種通過(guò) yii\filters\AccessControl 類來(lái)實(shí)現(xiàn)的簡(jiǎn)單授權(quán)方法， 非常適用于僅需要簡(jiǎn)單的存取控制的應(yīng)用。正如其名稱所指，ACF 是一個(gè)種行動(dòng)（action）過(guò)濾器?filter，可在控制器或者模塊中使用。當(dāng)一個(gè)用戶請(qǐng)求一個(gè) action 時(shí)， ACF會(huì)檢查 yii\filters\AccessControl::rules 列表，判斷該用戶是否允許執(zhí) 行所請(qǐng)求的action。（譯者注：?action?在本文中視情況翻譯為行動(dòng)、操作、方法等）

下述代碼展示如何在?site?控制器中使用 ACF：

use yii\web\Controller;
use yii\filters\AccessControl;

class SiteController extends Controller{
    public function behaviors()
    {
        return [
            'access' => [
                'class' => AccessControl::className(),
                'only' => ['login', 'logout', 'signup'],
                'rules' => [
                    [
                        'allow' => true,
                        'actions' => ['login', 'signup'],
                        'roles' => ['?'],
                    ],
                    [
                        'allow' => true,
                        'actions' => ['logout'],
                        'roles' => ['@'],
                    ],
                ],
            ],
        ];
    }
    // ...
}

上面的代碼中 ACF 以行為 (behavior) 的形式附加到?site?控制器。 這就是很典型的使用行動(dòng)過(guò)濾器的方法。?only?選項(xiàng)指明 ACF 應(yīng)當(dāng)只 對(duì)?login，?logout?和?signup?方法起作用。所有其它的?site?控制器中的方法不受存取控制的限制。?rules?選項(xiàng)列出了 yii\filters\AccessRule，解讀如下：

• 允許所有訪客（還未經(jīng)認(rèn)證的用戶）執(zhí)行?login?和?signup?操作。?roles?選項(xiàng)包含的問(wèn)號(hào)???是一個(gè)特殊的標(biāo)識(shí)，代表”訪客用戶”。
• 允許已認(rèn)證用戶執(zhí)行?logout?操作。@是另一個(gè)特殊標(biāo)識(shí)， 代表”已認(rèn)證用戶”。

ACF 自頂向下逐一檢查存取規(guī)則，直到找到一個(gè)與當(dāng)前 欲執(zhí)行的操作相符的規(guī)則。 然后該匹配規(guī)則中的?allow?選項(xiàng)的值用于判定該用戶是否獲得授權(quán)。如果沒(méi)有找到匹配的規(guī)則， 意味著該用戶沒(méi)有獲得授權(quán)。（譯者注：?only?中沒(méi)有列出的操作，將無(wú)條件獲得授權(quán)）

當(dāng) ACF 判定一個(gè)用戶沒(méi)有獲得執(zhí)行當(dāng)前操作的授權(quán)時(shí)，它的默認(rèn)處理是：

• 如果該用戶是訪客，將調(diào)用 yii\web\User::loginRequired() 將用戶的瀏覽器重定向到登錄頁(yè)面。
• 如果該用戶是已認(rèn)證用戶，將拋出一個(gè) yii\web\ForbiddenHttpException 異常。

你可以通過(guò)配置 yii\filters\AccessControl::denyCallback 屬性定制該行為：

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

yii\filters\AccessRule 支持很多的選項(xiàng)。下列是所支持選項(xiàng)的總覽。 你可以派生 yii\filters\AccessRule 來(lái)創(chuàng)建自定義的存取規(guī)則類。

• yii\filters\AccessRule::allow： 指定該規(guī)則是 "允許" 還是 "拒絕" 。（譯者注：true是允許，false是拒絕）

• yii\filters\AccessRule::actions：指定該規(guī)則用于匹配哪些操作。 它的值應(yīng)該是操作方法的ID數(shù)組。匹配比較是大小寫(xiě)敏感的。如果該選項(xiàng)為空，或者不使用該選項(xiàng)， 意味著當(dāng)前規(guī)則適用于所有的操作。

• yii\filters\AccessRule::controllers：指定該規(guī)則用于匹配哪些控制器。 它的值應(yīng)為控制器ID數(shù)組。匹配比較是大小寫(xiě)敏感的。如果該選項(xiàng)為空，或者不使用該選項(xiàng)， 則意味著當(dāng)前規(guī)則適用于所有的操作。（譯者注：這個(gè)選項(xiàng)一般是在控制器的自定義父類中使用才有意義）

• yii\filters\AccessRule::roles：指定該規(guī)則用于匹配哪些用戶角色。 系統(tǒng)自帶兩個(gè)特殊的角色，通過(guò) yii\web\User::isGuest 來(lái)判斷：

• • ?： 用于匹配訪客用戶 （未經(jīng)認(rèn)證）
  • @： 用于匹配已認(rèn)證用戶

• 使用其他角色名時(shí)，將觸發(fā)調(diào)用 yii\web\User::can()，這時(shí)要求 RBAC 的支持 （在下一節(jié)中闡述）。 如果該選項(xiàng)為空或者不使用該選項(xiàng)，意味著該規(guī)則適用于所有角色。

• yii\filters\AccessRule::ips：指定該規(guī)則用于匹配哪些 yii\web\Request::userIP 。 IP 地址可在其末尾包含通配符?*?以匹配一批前綴相同的IP地址。 例如，192.168.*?匹配所有?192.168.?段的IP地址。 如果該選項(xiàng)為空或者不使用該選項(xiàng)，意味著該規(guī)則適用于所有角色。

• yii\filters\AccessRule::verbs：指定該規(guī)則用于匹配哪種請(qǐng)求方法（例如GET，POST）。 這里的匹配大小寫(xiě)不敏感。

• yii\filters\AccessRule::matchCallback：指定一個(gè)PHP回調(diào)函數(shù)用于 判定該規(guī)則是否滿足條件。（譯者注：此處的回調(diào)函數(shù)是匿名函數(shù)）

• yii\filters\AccessRule::denyCallback: 指定一個(gè)PHP回調(diào)函數(shù)， 當(dāng)這個(gè)規(guī)則不滿足條件時(shí)該函數(shù)會(huì)被調(diào)用。（譯者注：此處的回調(diào)函數(shù)是匿名函數(shù)）

以下例子展示了如何使用?matchCallback?選項(xiàng)， 可使你設(shè)計(jì)任意的訪問(wèn)權(quán)限檢查邏輯：

use yii\filters\AccessControl;

class SiteController extends Controller{
    public function behaviors()
    {
        return [
            'access' => [
                'class' => AccessControl::className(),
                'only' => ['special-callback'],
                'rules' => [
                    [
                        'actions' => ['special-callback'],
                        'allow' => true,
                        'matchCallback' => function ($rule, $action) {
                            return date('d-m') === '31-10';
                        }
                    ],
                ],
            ],
        ];
    }

    // 匹配的回調(diào)函數(shù)被調(diào)用了！這個(gè)頁(yè)面只有每年的10月31號(hào)能訪問(wèn)（譯者注：原文在這里說(shuō)該方法是回調(diào)函數(shù)不確切，讀者不要和 `matchCallback` 的值即匿名的回調(diào)函數(shù)混淆理解）。
    public function actionSpecialCallback()
    {
        return $this->render('happy-halloween');
    }
}

基于角色的存取控制 （RBAC）

基于角色的存取控制 （RBAC） 提供了一個(gè)簡(jiǎn)單而強(qiáng)大的集中式存取控制機(jī)制。 詳細(xì)的關(guān)于 RBAC 和諸多傳統(tǒng)的存取控制方案對(duì)比的詳情，請(qǐng)參閱?Wikipedia。

Yii 實(shí)現(xiàn)了通用的分層的 RBAC，遵循的模型是?NIST RBAC model. 它通過(guò) yii\rbac\ManagerInterface?application component?提供 RBAC 功能。

使用 RBAC 涉及到兩部分工作。第一部分是建立授權(quán)數(shù)據(jù)， 而第二部分是使用這些授權(quán)數(shù)據(jù)在需要的地方執(zhí)行檢查。

為方便后面的講述，這里先介紹一些 RBAC 的基本概念。

基本概念

角色是?權(quán)限?的集合 （例如：建貼、改貼）。一個(gè)角色 可以指派給一個(gè)或者多個(gè)用戶。要檢查某用戶是否有一個(gè)特定的權(quán)限， 系統(tǒng)會(huì)檢查該包含該權(quán)限的角色是否指派給了該用戶。

可以用一個(gè)規(guī)則?rule?與一個(gè)角色或者權(quán)限關(guān)聯(lián)。一個(gè)規(guī)則用一段代碼代表， 規(guī)則的執(zhí)行是在檢查一個(gè)用戶是否滿足這個(gè)角色或者權(quán)限時(shí)進(jìn)行的。例如，"改帖" 的權(quán)限 可以使用一個(gè)檢查該用戶是否是帖子的創(chuàng)建者的規(guī)則。權(quán)限檢查中，如果該用戶 不是帖子創(chuàng)建者，那么他（她）將被認(rèn)為不具有 "改帖"的權(quán)限。

角色和權(quán)限都可以按層次組織。特定情況下，一個(gè)角色可能由其他角色或權(quán)限構(gòu)成， 而權(quán)限又由其他的權(quán)限構(gòu)成。Yii 實(shí)現(xiàn)了所謂的?局部順序?的層次結(jié)構(gòu)，包含更多的特定的?樹(shù)?的層次。 一個(gè)角色可以包含一個(gè)權(quán)限，反之則不行。（譯者注：可理解為角色在上方，權(quán)限在下方，從上到下如果碰到權(quán)限那么再往下不能出現(xiàn)角色）

配置 RBAC

在開(kāi)始定義授權(quán)數(shù)據(jù)和執(zhí)行存取檢查之前，需要先配置應(yīng)用組件 yii\base\Application::authManager 。 Yii 提供了兩套授權(quán)管理器： yii\rbac\PhpManager 和 yii\rbac\DbManager。前者使用 PHP 腳本存放授權(quán)數(shù)據(jù)， 而后者使用數(shù)據(jù)庫(kù)存放授權(quán)數(shù)據(jù)。 如果你的應(yīng)用不要求大量的動(dòng)態(tài)角色和權(quán)限管理， 你可以考慮使用前者。

使用?PhpManager

以下代碼展示使用 yii\rbac\PhpManager 時(shí)如何在應(yīng)用配置文件中配置?authManager：

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

現(xiàn)在可以通過(guò)?\Yii::$app->authManager?訪問(wèn)?authManager?。

yii\rbac\PhpManager 默認(rèn)將 RBAC 數(shù)據(jù)保存在?@app/rbac?目錄下的文件中。 如果權(quán)限層次數(shù)據(jù)在運(yùn)行時(shí)會(huì)被修改，需確保WEB服務(wù)器進(jìn)程對(duì)該目錄和其中的文件有寫(xiě)權(quán)限。

使用?DbManager

以下代碼展示使用 yii\rbac\DbManager 時(shí)如何在應(yīng)用配置文件中配置?authManager：

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

DbManager?使用4個(gè)數(shù)據(jù)庫(kù)表存放它的數(shù)據(jù)：

• yii\rbac\DbManager::$itemTable： 該表存放授權(quán)條目（譯者注：即角色和權(quán)限）。默認(rèn)表名為 "auth_item" 。
• yii\rbac\DbManager::$itemChildTable： 該表存放授權(quán)條目的層次關(guān)系。默認(rèn)表名為 "auth_item_child"。
• yii\rbac\DbManager::$assignmentTable： 該表存放授權(quán)條目對(duì)用戶的指派情況。默認(rèn)表名為 "auth_assignment"。
• yii\rbac\DbManager::$ruleTable： 該表存放規(guī)則。默認(rèn)表名為 "auth_rule"。

繼續(xù)之前，你需要在數(shù)據(jù)庫(kù)中創(chuàng)建這些表。你可以使用存放在?@yii/rbac/migrations?目錄中的數(shù)據(jù)庫(kù)遷移文件來(lái)做這件事（譯者注：根據(jù)本人經(jīng)驗(yàn)，最好是將授權(quán)數(shù)據(jù)初始化命令也寫(xiě)到這個(gè) RBAC 數(shù)據(jù)庫(kù)遷移文件中）：

yii migrate --migrationPath=@yii/rbac/migrations

現(xiàn)在可以通過(guò)?\Yii::$app->authManager?訪問(wèn)?authManager?。

建立授權(quán)數(shù)據(jù)

所有授權(quán)數(shù)據(jù)相關(guān)的任務(wù)如下：

• 定義角色和權(quán)限；
• 建立角色和權(quán)限的關(guān)系；
• 定義規(guī)則；
• 將規(guī)則與角色和權(quán)限作關(guān)聯(lián)；
• 指派角色給用戶。

根據(jù)授權(quán)的彈性需求，上述任務(wù)可用不同的方法完成。

如果你的權(quán)限層次結(jié)構(gòu)不會(huì)發(fā)生改變，而且你的用戶數(shù)是恒定的，你可以通過(guò)?authManager?提供的 API 創(chuàng)建一個(gè)?控制臺(tái)命令?一次性初始化授權(quán)數(shù)據(jù)：

<?phpnamespace app\commands;

use Yii;
use yii\console\Controller;

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

        // 添加 "createPost" 權(quán)限
        $createPost = $auth->createPermission('createPost');
        $createPost->description = 'Create a post';
        $auth->add($createPost);

        // 添加 "updatePost" 權(quán)限
        $updatePost = $auth->createPermission('updatePost');
        $updatePost->description = 'Update post';
        $auth->add($updatePost);

        // 添加 "author" 角色并賦予 "createPost" 權(quán)限
        $author = $auth->createRole('author');
        $auth->add($author);
        $auth->addChild($author, $createPost);

        // 添加 "admin" 角色并賦予 "updatePost" 
                // 和 "author" 權(quán)限
        $admin = $auth->createRole('admin');
        $auth->add($admin);
        $auth->addChild($admin, $updatePost);
        $auth->addChild($admin, $author);

        // 為用戶指派角色。其中 1 和 2 是由 IdentityInterface::getId() 返回的id （譯者注：user表的id）
        // 通常在你的 User 模型中實(shí)現(xiàn)這個(gè)函數(shù)。
        $auth->assign($author, 2);
        $auth->assign($admin, 1);
    }
}

在用?yii rbac/init?執(zhí)行了這個(gè)命令后，我們將得到下圖所示的層次結(jié)構(gòu)：

作者可創(chuàng)建新貼，管理員可編輯帖子以及所有作者可做的事情。

如果你的應(yīng)用允許用戶注冊(cè)，你需要在注冊(cè)時(shí)給新用戶指派一次角色。例如， 在高級(jí)項(xiàng)目模板中，要讓所有注冊(cè)用戶成為作者，你需要如下例所示修改?frontend\models\SignupForm::signup()?方法：

public function signup(){
    if ($this->validate()) {
        $user = new User();
        $user->username = $this->username;
        $user->email = $this->email;
        $user->setPassword($this->password);
        $user->generateAuthKey();
        $user->save(false);

        // 要添加以下三行代碼：
        $auth = Yii::$app->authManager;
        $authorRole = $auth->getRole('author');
        $auth->assign($authorRole, $user->getId());

        return $user;
    }

    return null;
}

對(duì)于有動(dòng)態(tài)更改授權(quán)數(shù)據(jù)的復(fù)雜存取控制需求的，你可能需要使用?authManager?提供的 API 的開(kāi)發(fā)用戶界面（例如：管理面板）。

使用規(guī)則 (Rules)

如前所述，規(guī)則給角色和權(quán)限增加額外的約束條件。規(guī)則是 yii\rbac\Rule 的派生類。 它需要實(shí)現(xiàn) yii\rbac\Rule::execute() 方法。在之前我們創(chuàng)建的層次結(jié)構(gòu)中，作者不能編輯自己的帖子，我們來(lái)修正這個(gè)問(wèn)題。 首先我們需要一個(gè)規(guī)則來(lái)認(rèn)證當(dāng)前用戶是帖子的作者：

namespace app\rbac;

use yii\rbac\Rule;

class AuthorRule extends Rule{
    public $name = 'isAuthor';

    
    public function execute($user, $item, $params)
    {
        return isset($params['post']) ? $params['post']->createdBy == $user : false;
    }
}

上述規(guī)則檢查?post?是否是?$user?創(chuàng)建的。我們還要在之前的命令中 創(chuàng)建一個(gè)特別的權(quán)限?updateOwnPost?：

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

// 添加規(guī)則$rule = new \app\rbac\AuthorRule;
$auth->add($rule);

// 添加 "updateOwnPost" 權(quán)限并與規(guī)則關(guān)聯(lián)$updateOwnPost = $auth->createPermission('updateOwnPost');
$updateOwnPost->description = 'Update own post';
$updateOwnPost->ruleName = $rule->name;
$auth->add($updateOwnPost);

// "updateOwnPost" 權(quán)限將由 "updatePost" 權(quán)限使用$auth->addChild($updateOwnPost, $updatePost);

// 允許 "author" 更新自己的帖子$auth->addChild($author, $updateOwnPost);

現(xiàn)在我們得到如下層次結(jié)構(gòu):

存取檢查

授權(quán)數(shù)據(jù)準(zhǔn)備好后，存取檢查簡(jiǎn)單到只需要一個(gè)方法調(diào)用 yii\rbac\ManagerInterface::checkAccess()。 因?yàn)榇蠖鄶?shù)存取檢查都是針對(duì)當(dāng)前用戶而言，為方便起見(jiàn)， Yii 提供了一個(gè)快捷方法 yii\web\User::can()，可以如下例所示來(lái)使用：

if (\Yii::$app->user->can('createPost')) {
    // 建貼
}

如果當(dāng)前用戶是?ID=1?的 Jane ，我們從圖中的?createPost?開(kāi)始，并試圖到達(dá)?Jane?。 （譯者注：參照?qǐng)D中紅色路線所示的建貼授權(quán)流程）

為了檢查某用戶是否能更新帖子，我們需要傳遞一個(gè)額外的參數(shù)，該參數(shù)是?AuthorRule?要用的：

if (\Yii::$app->user->can('updatePost', ['post' => $post])) {
    // 更新帖子
}

下圖所示為當(dāng)前用戶是 John 時(shí)所發(fā)生的事情：

我們從圖中的?updatePost?開(kāi)始，經(jīng)過(guò)?updateOwnPost。為通過(guò)檢查，Authorrule?規(guī)則的?execute()?方法應(yīng)當(dāng)返回?true?。該方法從can()?方法調(diào)用接收到?$params?參數(shù)， 因此它的值是?['post' => $post]?。如果一切順利，我們會(huì)達(dá)到指派給 John 的?author?角色。

對(duì)于 Jane 來(lái)說(shuō)則更簡(jiǎn)單，因?yàn)樗枪芾韱T：

使用默認(rèn)角色

所謂默認(rèn)角色就是?隱式?地指派給?所有?用戶的角色。不需要調(diào)用 yii\rbac\ManagerInterface::assign() 方法做顯示指派，并且授權(quán)數(shù)據(jù)中不包含指派信息。

默認(rèn)角色通常與一個(gè)規(guī)則關(guān)聯(lián)，用以檢查該角色是否符合被檢查的用戶。

默認(rèn)角色常常用于已經(jīng)確立了一些角色的指派關(guān)系的應(yīng)用（譯者注：指派關(guān)系指的是應(yīng)用業(yè)務(wù)邏輯層面， 并非指授權(quán)數(shù)據(jù)的結(jié)構(gòu)）。比如，一個(gè)應(yīng)用的 user 表中有一個(gè)?group?字段，代表用戶屬于哪個(gè)特權(quán)組。 如果每個(gè)特權(quán)組可以映射到 RBAC 的角色，你就可以采用默認(rèn)角色自動(dòng)地為每個(gè)用戶指派一個(gè) RBAC 角色。 讓我們用一個(gè)例子展示如何做到這一點(diǎn)。

假設(shè)在 user 表中，你有一個(gè)?group?字段，用 1 代表管理員組，用 2 表示作者組。 你規(guī)劃兩個(gè) RBAC 角色?admin?和?author?分別對(duì)應(yīng)這兩個(gè)組的權(quán)限。 你可以這樣設(shè)置 RBAC 數(shù)據(jù)，

namespace app\rbac;

use Yii;
use yii\rbac\Rule;

class UserGroupRule extends Rule{
    public $name = 'userGroup';

    public function execute($user, $item, $params)
    {
        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;
            }
        }
        return false;
    }
}

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

$rule = new \app\rbac\UserGroupRule;
$auth->add($rule);

$author = $auth->createRole('author');
$author->ruleName = $rule->name;
$auth->add($author);
// ... 添加$author角色的子項(xiàng)部分代碼 ... （譯者注：省略部分參照之前的控制臺(tái)命令）

$admin = $auth->createRole('admin');
$admin->ruleName = $rule->name;
$auth->add($admin);
$auth->addChild($admin, $author);
// ... 添加$admin角色的子項(xiàng)部分代碼 ... （譯者注：省略部分參照之前的控制臺(tái)命令）

注意，在上述代碼中，因?yàn)?"author" 作為 "admin" 的子角色，當(dāng)你實(shí)現(xiàn)這個(gè)規(guī)則的?execute()?方法時(shí)， 你也需要遵從這個(gè)層次結(jié)構(gòu)。這就是為何當(dāng)角色名為 "author" 的情況下（譯者注：$item->name就是角色名），?execute()?方法在組為 1 或者 2 時(shí)均要返回 true （意思是用戶屬于 "admin" 或者 "author" 組 ）。

接下來(lái)，在配置?authManager?時(shí)指定 yii\rbac\BaseManager::$defaultRoles 選項(xiàng)（譯者注：在應(yīng)用配置文件中的組件部分配置）：

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