Key Authentication (Key Auth)
概要
Key Authentication (key-auth) ポリシーは、API 消費者がリクエストヘッダーに有効な API Key を含めることを要求することで、API セキュリティを強化します。このメカニズムにより、認可されたユーザーまたはアプリケーションのみが API にアクセスできるようになります。
キー認証の仕組み
- API 消費者は、リクエストヘッダーに valid API Key を提供する必要があります。
- API ゲートウェイは、リクエストを処理する前に API キーを検証します。
- API キーが missing または invalid の場合、リクエストは認証エラーで拒否されます。
キー認証を使用するタイミング
- API アクセスを authorized clients に制限するため。
- API consumer identification メカニズムが必要な場合。
- combining multiple authentication methods の場合（例：key-auth + JWT）。
Note: key-auth と JWT authentication の両方が有効な場合、both 認証メソッドを渡す必要があります。
設定の詳細
API キーの作成
Key Authentication ポリシーを適用する前に、API キーを生成する必要があります。次の手順に従ってください。
Step 1: Open the API Key Management Page- APIM コンソールの APIM Management メニューに移動します。
- API キーを作成したいプロジェクトを選択します。
- Create API Key ボタンをクリックします。
- API キーのための description を入力します（例："モバイルアプリアクセス用のキー"）。
- システムが automatically generate a unique API Key します。
- 作成されると、API キーは API キー管理画面に表示されます。
- ユーザーは API キーを探して再度コピーできます。
設定フィールド
Key Authentication ポリシーには、次の設定が含まれています：
| Field Name | Description | Data Input |
|---|---|---|
| ヘッダー名 | API キーがリクエストに含まれるべき HTTP header。デフォルトのヘッダー名は x-apim-key です。Kubernetes デプロイメント 'apim-dff' では、環境変数を介してヘッダー名を変更できます。これらの変数を変更すると、APIM コンソールが再起動され、短時間のサービス中断が発生する可能性があります。 | 環境変数を介して設定可能（K8s のみ）。 |
| API キー検証 | システムは、提供された API キーが登録されており、有効であるかを確認してから API アクセスを許可します。 注：API キーは通常、32 文字の英数字の文字列です。 | 自動検証 |
| エラーハンドリング | 有効な API キーが提供されない場合、リクエストは HTTP 401 Unauthorized レスポンスで拒否されます。 | 自動応答 |
キー認証を使用した API 呼び出しの例
認証された API リクエストを行うには、リクエストヘッダーに API Key を含めます：
GET /api/resource HTTP/1.1
Host: api.example.com
headers: { "x-apim-key": "202cb962ac59075b964b07152d234b70" }
API キーが有効な場合、リクエストは 正常に処理されます。そうでない場合、レスポンスは次のようになります：
{
"message": "無効な認証情報",
"status": 401
}