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
}