Key-Auth プラグインによる API キー認証の設定 - API Gateway

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

プラグイン型

認証と承認のためのプラグイン。

フィールド

認証設定

設定アイテム	データ型	必須 / 任意	デフォルト値	説明
消費者	オブジェクトの配列	対象	-	サービスの呼び出し元。このフィールドは、リクエストを認証するために使用されます。
キー	文字列の配列	対象	-	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	文字列の配列	いいえ (インスタンスレベルの設定にのみ必要)	-	このフィールドは、インスタンスレベルでのみ設定できます。このフィールドがtrueに設定されている場合、認証メカニズムはグローバルに有効になります。このフィールドがfalseに設定されている場合、認証メカニズムは設定されたドメイン名とルートに対してのみ有効になります。このフィールドが設定されていない場合、認証メカニズムはドメイン名とルートが設定されていない場合にのみグローバルに有効になります。これは、古いユーザの使用習慣を考慮したものである。

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

設定アイテム	データ型	必須 / 任意	デフォルト値	説明
資格情報	String	対象	-	コンシューマーのアクセス資格情報。
name	String	対象	-	コンシューマーの名前。

(オプション) 許可設定

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

重要

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

例

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

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

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

global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e125***
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40***
  name: consumer2
keys:
- apikey
- x-api-key

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

allow:
- consumer1

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

allow:
- consumer2

説明

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

上記の設定では、次のリクエストからのアクセスが許可されます。この例では、リクエスト内のルート名がルート-aルートと一致します。

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

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

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

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

認証と承認が渡された後、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-00163e1***
```
APIキーを使用して一致した呼び出し元にはアクセス権限がなく、HTTPステータスコード403が返されます。
```
# The caller consumer2 is not in the whitelist of route-a.
curl  http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc***
```

ゲートウェイの認証の有効化

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

global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1***
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc***
  name: consumer2
keys:
- apikey
- x-api-key

エラーコード

HTTPステータスコード	エラーメッセージ	理由
401	リクエストにAPIキーがありません。	リクエストにAPIキーが指定されていません。
401	Key Authチェックによって拒否されたリクエスト。 APIキーが無効です。	APIキーが無効です。
403	Basic Authチェックによって拒否されたリクエスト。無許可の消費者。	リクエストの呼び出し元にアクセス権限がありません。