身份驗證 ¶

與 Web 應用程式不同，RESTful API 通常是無狀態的，這表示不應使用 session 或 Cookie。因此，每個請求都應帶有一些身份驗證憑證，因為使用者身份驗證狀態可能不會透過 session 或 Cookie 維護。常見的做法是在每個請求中發送一個秘密存取權杖以驗證使用者身份。由於存取權杖可用於唯一識別和驗證使用者，**API 請求應始終透過 HTTPS 發送，以防止中間人 (MitM) 攻擊**。

以下是發送存取權杖的不同方式

• HTTP 基本身份驗證：存取權杖作為使用者名稱發送。這僅應在存取權杖可以安全地儲存在 API 消費端時使用。例如，API 消費者是在伺服器上執行的程式。
• 查詢參數：存取權杖作為 API URL 中的查詢參數發送，例如，https://example.com/users?access-token=xxxxxxxx。由於大多數 Web 伺服器會將查詢參數保留在伺服器日誌中，因此這種方法應主要用於服務 JSONP 請求，這些請求無法使用 HTTP 標頭發送存取權杖。
• OAuth 2：存取權杖由消費者從授權伺服器取得，並根據 OAuth2 協定透過 HTTP Bearer Tokens 發送到 API 伺服器。

Yii 支援上述所有身份驗證方法。您也可以輕鬆建立新的身份驗證方法。

若要為您的 API 啟用身份驗證，請執行以下步驟

1. 配置 user 應用程式組件
   • 將 enableSession 屬性設定為 false。
   • 將 loginUrl 屬性設定為 null 以顯示 HTTP 403 錯誤，而不是重新導向到登入頁面。
2. 透過在您的 REST 控制器類別中配置 authenticator 行為，指定您計劃使用的身份驗證方法。
3. 在您的 使用者身份類別 中實作 yii\web\IdentityInterface::findIdentityByAccessToken()。

步驟 1 不是必需的，但建議用於應為無狀態的 RESTful API。當 enableSession 為 false 時，使用者身份驗證狀態將不會跨請求使用 session 持續保存。相反地，將針對每個請求執行身份驗證，這透過步驟 2 和 3 完成。

提示：如果您正在應用程式方面開發 RESTful API，您可以在應用程式配置中配置 user 應用程式組件的 enableSession。如果您將 RESTful API 開發為模組，您可以將以下行放在模組的 init() 方法中，如下所示

public function init()
{
    parent::init();
    \Yii::$app->user->enableSession = false;
}

例如，若要使用 HTTP 基本身份驗證，您可以如下配置 authenticator 行為，

use yii\filters\auth\HttpBasicAuth;

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => HttpBasicAuth::class,
    ];
    return $behaviors;
}

如果您想要支援上述所有三種身份驗證方法，您可以使用 CompositeAuth，如下所示，

use yii\filters\auth\CompositeAuth;
use yii\filters\auth\HttpBasicAuth;
use yii\filters\auth\HttpBearerAuth;
use yii\filters\auth\QueryParamAuth;

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => CompositeAuth::class,
        'authMethods' => [
            HttpBasicAuth::class,
            HttpBearerAuth::class,
            QueryParamAuth::class,
        ],
    ];
    return $behaviors;
}

authMethods 中的每個元素都應該是身份驗證方法類別名稱或配置陣列。

findIdentityByAccessToken() 的實作是應用程式特定的。例如，在簡單的場景中，當每個使用者只能有一個存取權杖時，您可以將存取權杖儲存在使用者表中的 access_token 欄位中。然後可以在 User 類別中輕鬆實作該方法，如下所示，

use yii\db\ActiveRecord;
use yii\web\IdentityInterface;

class User extends ActiveRecord implements IdentityInterface
{
    public static function findIdentityByAccessToken($token, $type = null)
    {
        return static::findOne(['access_token' => $token]);
    }
}

如上所述啟用身份驗證後，對於每個 API 請求，請求的控制器將嘗試在其 beforeAction() 步驟中驗證使用者身份。

如果身份驗證成功，控制器將執行其他檢查（例如速率限制、授權），然後執行操作。已驗證的使用者身份資訊可以透過 Yii::$app->user->identity 檢索。

如果身份驗證失敗，將發送 HTTP 狀態 401 的回應，以及其他適當的標頭（例如用於 HTTP 基本身份驗證的 WWW-Authenticate 標頭）。

授權 ¶

在使用者通過身份驗證後，您可能想要檢查他或她是否具有執行所請求資源的請求操作的權限。此過程稱為授權，在授權章節中詳細介紹。

如果您的控制器從 yii\rest\ActiveController 擴展而來，您可以覆寫 checkAccess() 方法來執行授權檢查。該方法將由 yii\rest\ActiveController 提供的內建操作呼叫。