key-auth プラグインの設定 - Microservices Engine - Alibaba Cloud ドキュメントセンター

key-auth プラグインは、API キーに基づく認証に使用されます。 key-auth プラグインを使用すると、HTTP リクエストの URL パラメーターまたはリクエストヘッダーから API キーを解析し、サービスへのアクセスに対して API キーが有効かどうかを確認できます。このトピックでは、key-auth プラグインを設定する方法について説明します。

プラグインの種類

認証プラグイン。

フィールド

認証設定

名前	データ型	必須	デフォルト値	説明
consumers	オブジェクトの配列	はい	-	サービスの呼び出し元。このフィールドは、リクエストを認証するために使用されます。
keys	文字列の配列	はい	-	API キーのソースフィールド。ソースフィールドは、URL パラメーターまたは HTTP リクエストヘッダーです。
in_query	bool	いいえ（`in_query` と `in_header` の少なくとも 1 つを true に設定する必要があります。）	true	このフィールドが `true` に設定されている場合、ゲートウェイは URL パラメーターから API キーを解析しようとします。
in_header	bool	いいえ（`in_query` と `in_header` の少なくとも 1 つを true に設定する必要があります。）	true	このフィールドが `true` に設定されている場合、ゲートウェイは HTTP リクエストヘッダーから API キーを解析しようとします。
global_auth	文字列の配列	いいえ（インスタンスレベルの設定にのみ必要です。）	-	global_auth が true に設定されている場合、認証メカニズムはグローバルに有効になります。 global_auth が false に設定されている場合、認証メカニズムは、設定したドメイン名とルートに対してのみ有効になります。 global_auth が設定されていない場合、認証メカニズムは、ドメイン名とルートが設定されていない場合にのみグローバルに有効になります。

次の表は、consumers フィールドの設定項目を示しています。

名前	データ型	必須	デフォルト値	説明
credential	string	はい	-	コンシューマーのアクセス資格情報。
name	string	はい	-	コンシューマーの名前。

承認設定（オプション）

名前	データ型	必須	デフォルト値	説明
allow	文字列の配列	いいえ（インスタンスレベル以外の設定に必要）	-	このフィールドは、ルートやドメイン名などの細かい粒度でのみ設定できます。一致条件を満たすリクエストに対して、アクセスを許可するコンシューマーを設定できます。これにより、きめ細かい権限制御が実装されます。

重要

承認設定と認証設定は、1 つのルールで共存できません。
認証および承認されたリクエストの場合、X-Mse-Consumer フィールドがリクエストヘッダーに追加され、呼び出し元の名前が識別されます。

設定例

グローバル承認とルートレベル認証の設定

このセクションでは、ゲートウェイの特定のルートまたはドメインに対して key-auth プラグインに基づいて認証と承認を有効にする方法の例を示します。 credential フィールドは一意である必要があります。

インスタンスレベルで次のプラグイン設定を適用します。

global_auth: false  // グローバル認証を無効化
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5 // コンシューマー 1 の資格情報
  name: consumer1  // コンシューマー 1 の名前
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35 // コンシューマー 2 の資格情報
  name: consumer2  // コンシューマー 2 の名前
keys:
- apikey  // API キーのソースフィールド（URL パラメーター）
- x-api-key // API キーのソースフィールド（HTTP リクエストヘッダー）

route-a ルートと route-b ルートに次のプラグイン設定を適用します。

allow: // 許可されたコンシューマー
- consumer1 // コンシューマー 1 を許可

*.example.com ドメイン名と test.com ドメイン名に次のプラグイン設定を適用します。

allow: // 許可されたコンシューマー
- consumer2 // コンシューマー 2 を許可

説明

この例では、route-a ルートと route-b ルートは、ゲートウェイルートの作成時に指定されたルートです。クライアントリクエストがルートのいずれかと一致する場合、name が consumer1 である呼び出し元はゲートウェイへのアクセスを許可されます。他の呼び出し元はゲートウェイにアクセスできません。
この例では、*.example.com ドメイン名と test.com ドメイン名は、リクエスト内のドメイン名と照合するために使用されます。クライアントリクエストがドメイン名のいずれかと一致する場合、name が consumer2 である呼び出し元はゲートウェイへのアクセスを許可されます。他の呼び出し元はゲートウェイにアクセスできません。

上記の構成では、次のリクエストからのアクセスが許可されます。この例では、route-a が一致します。

URL パラメーターで API キーを指定します。

curl  http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1250b5

HTTP リクエストヘッダーで API キーを指定します。

curl  http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5'

認証と承認が完了すると、X-Mse-Consumer フィールドがリクエストのヘッダーに追加され、呼び出し元が識別されます。この例では、このフィールドの値は consumer1 です。

次のリクエストは拒否されます。

リクエストに API キーが指定されておらず、HTTP ステータスコード 401 が返されます。
```
curl  http://xxx.hello.com/test
```
リクエストに指定された API キーが無効であり、HTTP ステータスコード 401 が返されます。
```
curl  http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5
```

API キーを使用して一致した呼び出し元にアクセス許可がなく、HTTP ステータスコード 403 が返されます。

# 呼び出し元 consumer2 は route-a のホワイトリストに含まれていません。
curl  http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc40e35

ゲートウェイインスタンスの基本認証を有効にする

ゲートウェイに次の設定を適用すると、インスタンスレベルで基本認証が有効になり、すべてのリクエストはゲートウェイにアクセスするために認証される必要があります。

global_auth: true // グローバル認証を有効化
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5 // コンシューマー 1 の資格情報
  name: consumer1 // コンシューマー 1 の名前
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35 // コンシューマー 2 の資格情報
  name: consumer2 // コンシューマー 2 の名前
keys:
- apikey // API キーのソースフィールド（URL パラメーター）
- x-api-key // API キーのソースフィールド（HTTP リクエストヘッダー）

HTTP ステータスコード

HTTP ステータスコード	エラーメッセージ	理由
401	リクエストに API キーが見つかりません。	リクエストに API キーが指定されていません。
401	Key Auth チェックによってリクエストが拒否されました。無効な API キーです。	API キーが無効です。
403	Basic Auth チェックによってリクエストが拒否されました。承認されていないコンシューマーです。	リクエストの呼び出し元にアクセス許可がありません。