<commit_before>権限付与
========

権限付与は、ユーザが何かをするのに十分な許可を有しているか否かを確認するプロセスです。
Yii は二つの権限付与の方法を提供しています。すなわち、アクセス制御フィルタ (ACF) と、ロール・ベース・アクセス制御 (RBAC) です。


アクセス制御フィルタ (ACF)
--------------------------

アクセス制御フィルタ (ACF) は、[[yii\filters\AccessControl]] として実装される単純な権限付与の方法であり、何らかの単純なアクセス制御だけを必要とするアプリケーションで使うのに最も適したものです。
その名前が示すように、ACF は、コントローラまたはモジュールで使用することが出来るアクション [フィルタ](structure-filters.md) です。
ACF は、ユーザがアクションの実行をリクエストしたときに、一連の [[yii\filters\AccessControl::rules|アクセス規則]] をチェックして、現在のユーザがそのアクションにアクセスする許可を持つかどうかを決定します。

下記のコードは、`site` コントローラで ACF を使う方法を示すものです。

```php
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 は `site` コントローラにビヘイビアとしてアタッチされています。
これがアクション・フィルタを使用する典型的な方法です。
`only` オプションは、ACF が `login`、`logout`、`signup` のアクションにのみ適用されるべきであることを指定しています。
`site` コントローラの他の全てのアクションには ACF の影響は及びません。
`rules` オプションは [[yii\filters\AccessRule|アクセス規則]] を指定するものであり、以下のように読むことが出来ます。

- 全てのゲスト・ユーザ (まだ認証されていないユーザ) に、'login' と 'singup' のアクションにアクセスすることを許可します。
  `roles` オプションに疑問符 `?` が含まれていますが、これは「ゲスト」を表す特殊なトークンです。
- 認証されたユーザに、'logout' アクションにアクセスすることを許可します。
  `@` という文字はもう一つの特殊なトークンで、「認証されたユーザ」を表すものです。

ACF が権限のチェックを実行するときには、規則を一つずつ上から下へ、適用されるものを見つけるまで調べます。
そして、適用される規則の `allow` の値が、ユーザが権限を有するか否かを判断するのに使われます。
適用される規則が一つもなかった場合は、ユーザが権限をもたないことを意味し、ACF はアクションの継続を中止します。

ユーザが現在のアクションにアクセスする権限を持っていないと判定した場合は、デフォルトでは、ACF は以下の手段を取ります。

* ユーザがゲストである場合は、[[yii\web\User::loginRequired()]] を呼び出して、ユーザのブラウザをログイン・ページにリダイレクトします。
* ユーザが既に認証されている場合は、[[yii\web\ForbiddenHttpException]] を投げます。

この動作は、次のように、[[yii\filters\AccessControl::denyCallback]] プロパティを構成することによって、カスタマイズすることが出来ます。

```php
[
    'class' => AccessControl::className(),
    ...
    'denyCallback' => function ($rule, $action) {
        throw new \Exception('このページにアクセスする権限がありません。');
    }
]
```

[[yii\filters\AccessRule|アクセス規則]] は多くのオプションをサポートしています。
以下はサポートされているオプションの要約です。
[[yii\filters\AccessRule]] を拡張して、あなた自身のカスタマイズしたアクセス規則のクラスを作ることも出来ます。

 * [[yii\filters\AccessRule::allow|allow]]: これが「許可」の規則であるか、「禁止」の規則であるかを指定します。

 * [[yii\filters\AccessRule::actions|actions]]: どのアクションにこの規則が適用されるかを指定します。
これはアクション ID の配列でなければなりません。
比較は大文字と小文字を区別します。
このオプションが空であるか指定されていない場合は、規則が全てのアクションに適用されることを意味します。

 * [[yii\filters\AccessRule::controllers|controllers]]: どのコントローラにこの規則が適用されるかを指定します。
これはコントローラ ID の配列でなければなりません。
コントローラがモジュールに属する場合は、モジュール ID をコントローラ ID の前に付けます。
比較は大文字と小文字を区別します。
このオプションが空であるか指定されていない場合は、規則が全てのコントローラに適用されることを意味します。

 * [[yii\filters\AccessRule::roles|roles]]: どのユーザ・ロールにこの規則が適用されるかを指定します。
   二つの特別なロールが認識されます。
   これらは、[[yii\web\User::isGuest]] によって判断されます。

    - `?`: ゲスト・ユーザ (まだ認証されていないユーザ) を意味します。
    - `@`: 認証されたユーザを意味します。

   その他のロール名を使うと、[[yii\web\User::can()]] の呼び出しが惹起されますが、そのためには、RBAC (次のセクションで説明します) を有効にする必要があります。
   このオプションが空であるか指定されていない場合は、規則が全てのロールに適用されることを意味します。

 * [[yii\filters\AccessRule::roleParams|roleParams]]: [[yii\web\User::can()]] に渡されるパラメータを指定します。
   パラメータがどのように使われるかは、RBAC 規則を説明する後のセクションを参照して下さい。
   このオプションが空であるか設定されていない場合は、パラメータは渡されません。

 * [[yii\filters\AccessRule::ips|ips]]: どの [[yii\web\Request::userIP|クライアントの IP アドレス]] にこの規則が適用されるかを指定します。
IP アドレスは、最後にワイルドカード `*` を含むことが出来て、同じプレフィクスを持つ IP アドレスに合致させることが出来ます。
例えば、'192.168.*' は、'192.168.' のセグメントに属する全ての IP アドレスに合致します。
このオプションが空であるか指定されていない場合は、規則が全ての IP アドレスに適用されることを意味します。

 * [[yii\filters\AccessRule::verbs|verbs]]: どのリクエスト・メソッド (HTTP 動詞、例えば `GET` や `POST`) にこの規則が適用されるかを指定します。
比較は大文字と小文字を区別しません。

 * [[yii\filters\AccessRule::matchCallback|matchCallback]]: この規則が適用されるべきか否かを決定するために呼び出されるべき PHP コーラブルを指定します。

 * [[yii\filters\AccessRule::denyCallback|denyCallback]]: この規則がアクセスを禁止する場合に呼び出されるべき PHP コーラブルを指定します。

下記は、`matchCallback` オプションを利用する方法を示す例です。
このオプションによって、任意のアクセス制御ロジックを書くことが可能になります。

```php
use yii\filters\AccessControl;

class SiteController extends Controller<commit_msg>guide-ja/security-authorization.md revising WIP [ci skip]<commit_after>権限付与
========

権限付与は、ユーザが何かをするのに十分な許可を有しているか否かを確認するプロセスです。
Yii は二つの権限付与の方法を提供しています。すなわち、アクセス制御フィルタ (ACF) と、ロール・ベース・アクセス制御 (RBAC) です。


## アクセス制御フィルタ (ACF) <span id="access-control-filter"></span>

アクセス制御フィルタ (ACF) は、[[yii\filters\AccessControl]] として実装される単純な権限付与の方法であり、
何らかの単純なアクセス制御だけを必要とするアプリケーションで使うのに最も適したものです。
その名前が示すように、ACF は、コントローラまたはモジュールで使用することが出来るアクション [フィルタ](structure-filters.md) です。
ACF は、ユーザがアクションの実行をリクエストしたときに、一連の [[yii\filters\AccessControl::rules|アクセス規則]] をチェックして、
現在のユーザがそのアクションにアクセスする許可を持つかどうかを決定します。

下記のコードは、`site` コントローラで ACF を使う方法を示すものです。

```php
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 は `site` コントローラにビヘイビアとしてアタッチされています。これがアクション・フィルタを使用する典型的な方法です。
`only` オプションは、ACF が `login`、`logout`、`signup` のアクションにのみ適用されるべきであることを指定しています。
`site` コントローラの他の全てのアクションには ACF の影響は及びません。
`rules` オプションは [[yii\filters\AccessRule|アクセス規則]] を指定するものであり、以下のように読むことが出来ます。

- 全てのゲスト・ユーザ (まだ認証されていないユーザ) に、`login` と `singup` のアクションにアクセスすることを許可します。
  `roles` オプションに疑問符 `?` が含まれていますが、これは「ゲスト」を表す特殊なトークンです。
- 認証されたユーザに、`logout` アクションにアクセスすることを許可します。
  `@` という文字はもう一つの特殊なトークンで、「認証されたユーザ」を表すものです。

ACF による権限付与のプロセスにおいては、現在の実行コンテキストに合致する規則が見つかるまで、
アクセス規則が上から下へと一つずつ調べられます。
そして、合致したアクセス規則の `allow` の値が、ユーザが権限を有するか否かを決定するのに使われます。
合致する規則が一つもなかった場合は、ユーザが権限をもたないことを意味し、ACF はアクションの継続を中止します。

ユーザが現在のアクションにアクセスする権限を持っていないと判定した場合は、デフォルトでは、ACF は以下の手段を取ります。

* ユーザがゲストである場合は、[[yii\web\User::loginRequired()]] を呼び出して、ユーザのブラウザをログイン・ページにリダイレクトします。
* ユーザが既に認証されている場合は、[[yii\web\ForbiddenHttpException]] を投げます。

この動作は、次のように、[[yii\filters\AccessControl::denyCallback]] プロパティを構成することによって、カスタマイズすることが出来ます。

```php
[
    'class' => AccessControl::className(),
    ...
    'denyCallback' => function ($rule, $action) {
        throw new \Exception('このページにアクセスする権限がありません。');
    }
]
```

[[yii\filters\AccessRule|アクセス規則]] は多くのオプションをサポートしています。以下はサポートされているオプションの要約です。
[[yii\filters\AccessRule]] を拡張して、あなた自身のカスタマイズしたアクセス規則のクラスを作ることも出来ます。

 * [[yii\filters\AccessRule::allow|allow]]: これが「許可」の規則であるか、「禁止」の規則であるかを指定します。

 * [[yii\filters\AccessRule::actions|actions]]: どのアクションにこの規則が適用されるかを指定します。
   これはアクション ID の配列でなければなりません。比較は大文字と小文字を区別します。
   このオプションが空であるか指定されていない場合は、規則が全てのアクションに適用されることを意味します。

 * [[yii\filters\AccessRule::controllers|controllers]]: どのコントローラにこの規則が適用されるかを指定します。これはコントローラ ID の配列でなければなりません。
   コントローラがモジュールに属する場合は、モジュール ID をコントローラ ID の前に付けます。比較は大文字と小文字を区別します。
   このオプションが空であるか指定されていない場合は、規則が全てのコントローラに適用されることを意味します。

 * [[yii\filters\AccessRule::roles|roles]]: どのユーザ・ロールにこの規則が適用されるかを指定します。
   二つの特別なロールが認識されます。これらは、[[yii\web\User::isGuest]] によって判断されます。

    - `?`: ゲスト・ユーザ (まだ認証されていないユーザ) を意味します。
    - `@`: 認証されたユーザを意味します。

   その他のロール名を使うと、[[yii\web\User::can()]] の呼び出しが惹起されますが、そのためには、RBAC (次のセクションで説明します) を有効にする必要があります。
   このオプションが空であるか指定されていない場合は、規則が全てのロールに適用されることを意味します。

 * [[yii\filters\AccessRule::roleParams|roleParams]]: [[yii\web\User::can()]] に渡されるパラメータを指定します。
   パラメータがどのように使われるかは、RBAC 規則を説明する後のセクションを参照して下さい。このオプションが空であるか設定されていない場合は、パラメータは渡されません。

 * [[yii\filters\AccessRule::ips|ips]]: どの [[yii\web\Request::userIP|クライアントの IP アドレス]] にこの規則が適用されるかを指定します。
   IP アドレスは、最後にワイルドカード `*` を含むことが出来て、同じプレフィクスを持つ IP アドレスに合致させることが出来ます。
   例えば、'192.168.*' は、'192.168.' のセグメントに属する全ての IP アドレスに合致します。
   このオプションが空であるか指定されていない場合は、規則が全ての IP アドレスに適用されることを意味します。

 * [[yii\filters\AccessRule::verbs|verbs]]: どのリクエスト・メソッド (HTTP 動詞、例えば `GET` や `POST`) にこの規則が適用されるかを指定します。
   比較は大文字と小文字を区別しません。

 * [[yii\filters\AccessRule::matchCallback|matchCallback]]: この規則が適用されるべきか否かを決定するために呼び出されるべき
   PHP コーラブルを指定します。

 * [[yii\filters\AccessRule::denyCallback|denyCallback]]: この規則がアクセスを禁止する場合に呼び出されるべき
   PHP コーラブルを指定します。

下記は、`matchCallback` オプションを利用する方法を示す例です。
このオプションによって、任意のアクセス制御ロジックを書くことが可能になります。

```php
use yii\filters\AccessControl;

class SiteController extends Controller
{'fraction_non_alphanumeric': 0.13466889259877574, 'fraction_numerical': 0.002671118530884808, 'mean_word_length': 4.644472361809045, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6330867', 'n_tokens_mistral': 6168, 'n_tokens_neox': 5728, 'n_words': 411}