Key Auth

Looking for the plugin's configuration parameters? You can find them in the Key Auth configuration reference doc.

このプラグインを使用すると、サービスまたはルートにKey Authenticationを追加できます。コンシューマは、APIキーをクエリ文字列パラメータ、ヘッダー、またはリクエストボディに追加してリクエストを認証できます。

このプラグインは、アプリケーション登録プラグインと組み合わせて認証に使用できます。

このプラグインはエンタープライズバージョンであるKey Authentication Encryptedでも利用でき、キーを暗号化することができます。キーはAPIゲートウェイデータストアに保存時に暗号化されます。

大文字と小文字の区別

それぞれの使用によると、HTTPヘッダー名は大文字と小文字は 区別されません が、HTTPクエリ文字列パラメータ名は大文字と小文字が 区別されます 。Kongは設計どおりにこれらの仕様に従います。つまり、リクエストヘッダーフィールドの検索とクエリ文字列の検索ではkey_names構成値は処理が異なります。ベストプラクティスとして、管理者は認証キーがリクエストヘッダーに送信されることを期待する場合、大文字と小文字を区別するkey_names値を定義しないことを奨励します。

これが適用されると、有効な認証情報を持つユーザーはこのサービスにアクセスできます。特定の権限を持つユーザーの使用を制限するには、ACLプラグイン（ここでは説明されていません）を追加して許可されるユーザーと拒否されるユーザーのグループを作成できます。

使用法

コンシューマを作成

既存のコンシューマオブジェクトへの認証情報を関連付ける必要があります。コンシューマは多数の認証情報を持つことができます。

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://localhost:8001/consumers/

consumers:
- username: user123
  custom_id: SOME_CUSTOM_ID

どちらの場合も、パラメーターは以下のとおりです。

このサービスでACLプラグインと許可リストも使用している場合、新しいコンシューマを許可されたグループに追加する必要があります。詳細については、ACL：コンシューマの関連付けを参照してください。

匿名アクセスを構成する方法の詳細については、 匿名アクセスを参照してください。

複数認証

Kong Gatewayは特定のサービスに対して複数の認証プラグインをサポートしており、異なるクライアントが異なる認証方法を使用して特定のサービスまたはルートにアクセスできるようにします。詳細については、 複数認証を参照してください。

キーの作成

注 ：APIゲートウェイにキーを自動生成させることをお勧めします。既存のシステムをKong Gatewayに移行する場合にのみ、自分で指定してください。 Kong Gatewayへの移行をコンシューマにとって透過的にするために、キーを再利用する必要があります。

curl -X POST http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth

HTTP/1.1 201 Created
{
  "key": "5SRmk6gLnTy1SyQ1Cl9GzoRXJbjYGGbZ",
  "created_at": 1655412883,
  "tags": null,
  "ttl": null,
  "id": "0103844a-0b40-42c8-aa71-64e98e2e525f",
  "consumer": {
    "id": "d9e37c7d-3261-4b7b-81a6-a94bc203a0ca"
  }
}

keyauth_credentials:
- consumer: {USERNAME_OR_ID}
  ttl: 5000
  tags:
    - example_tag
  key: example_apikey

どちらの場合も、フィールド/パラメータは次のように機能します。

キーでリクエストする

クエリ文字列パラメータとしてキーを指定してリクエストします：

curl http://localhost:8000/{proxy path}?apikey={some_key}

注： key_in_query プラグインパラメータは true（デフォルト）に設定する必要があります。

ヘッダーにキーを使用してリクエストを行います。

curl http://localhost:8000/{proxy path} \
    -H 'apikey: {some_key}'

注： key_in_header プラグインパラメータは true（デフォルト）に設定する必要があります。

本文にキーを使用してリクエストを行います。

curl http://localhost:8000/{proxy path} \
    --data 'apikey={some_key}'

注： key_in_bodyプラグインパラメータはtrueに設定する必要があります（デフォルトはfalseです）。

gRPCクライアントもサポートされています。

grpcurl -H 'apikey: {some_key}' ...

リクエスト内のAPIキーの場所について

キーの場所のユースケース

• 推奨：サービス間呼び出しを実行する最も一般的で安全な方法として、key_in_header （デフォルトで有効）を使用します。
• ブラウザクライアントにリンクを共有する必要がある場合は、key_in_queryを使用します（デフォルトで有効になっています）。 クエリパラメータのリクエストは、アプリケーションログやURLブラウザバーに表示される可能性があり、これによってAPIキーが公開されることに注意してください。
• ログインフォームなど、ブラウザでフォームを送信する場合は、 key_in_bodyを使用します。このオプションは、あまり一般的ではないユースケースであり、コストが高くパフォーマンスの低いHTTPリクエストであるため、デフォルトでfalseに設定されています。

セキュリティを強化するために、使用する必要のあるキーの場所のみを有効にします。

キーの場所を無効にする

この例では、クエリパラメータでのキーの使用を無効にします。

curl -X POST http://localhost:8001/routes/{NAME_OR_ID}/plugins \
    --data "name=key-auth"  \
    --data "config.key_names=apikey" \
    --data "config.key_in_query=false"

キーの削除

APIキーを削除するには、次のリクエストを行います。

curl -X DELETE http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth/{ID}

応答：

HTTP/1.1 204 No Content

• USERNAME_OR_ID：認証情報を関連付けるためのコンシューマエンティティのidまたはusernameプロパティ。
• ID：キー認証情報オブジェクトの id属性。

アップストリームヘッダー

クライアントが認証されると、プラグインはアップストリームサービスにプロキシする前にリクエストへいくつかのヘッダーを追加し、以下のコードでコンシューマを識別できるようにします。

• X-Consumer-ID: Kong内のコンシューマのID。
• X-Consumer-Custom-ID: コンシューマのcustom_id（設定されている場合）。
• X-Consumer-Username: コンシューマのusername（設定されている場合）。
• X-Credential-Identifier: 認証情報の識別子（コンシューマがanonymousコンシューマでない場合にのみ）。
• X-Anonymous-Consumer: 認証に失敗した場合はtrueに設定され、代わりにanonymousコンシューマが設定されます。

この情報を利用して、追加のロジックを実装することができます。X-Consumer-ID値を使用してKong Admin APIのクエリを実行し、コンシューマについての詳細な情報を取得できます。

キーにページ番号を付ける

次のリクエストを実行して、すべてのコンシューマのAPIキーにページ番号を付けます。

curl -X GET http://localhost:8001/key-auths

応答：

...
{
   "data":[
      {
         "id":"17ab4e95-9598-424f-a99a-ffa9f413a821",
         "created_at":1507941267000,
         "key":"Qslaip2ruiwcusuSUdhXPv4SORZrfj4L",
         "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
      },
      {
         "id":"6cb76501-c970-4e12-97c6-3afbbba3b454",
         "created_at":1507936652000,
         "key":"nCztu5Jrz18YAWmkwOGJkQe9T8lB99l4",
         "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
      },
      {
         "id":"b1d87b08-7eb6-4320-8069-efd85a4a8d89",
         "created_at":1507941307000,
         "key":"26WUW1VEsmwT1ORBFsJmLHZLDNAxh09l",
         "consumer": { "id": "3c2c8fc1-7245-4fbb-b48b-e5947e1ce941" }
      }
   ]
   "next":null,
}

別のエンドポイントを使用して、コンシューマ別にリストをフィルタリングします。

curl -X GET http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth

上記は、コンシューマに関連付けられたusernameまたはidプロパティを置き換えます。

応答：

...
{
    "data": [
       {
         "id":"6cb76501-c970-4e12-97c6-3afbbba3b454",
         "created_at":1507936652000,
         "key":"nCztu5Jrz18YAWmkwOGJkQe9T8lB99l4",
         "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
       }
    ]
    "next":null,
}

キーに関連付けられたコンシューマを取得する

次のリクエストを実行して、APIキーに関連付けられたコンシューマを取得します。

curl -X GET http://localhost:8001/key-auths/{KEY_OR_ID}/consumer

上記は、Key Authenticationエンティティに関連付けられたkeyまたはidプロパティのいずれかを置き換えます。

応答：

{
   "created_at":1507936639000,
   "username":"foo",
   "id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}

リクエスト動作マトリックス

次の表は、さまざまなシナリオにおけるKong Gatewayの動作を示しています。