feat: Add Bearer Token Support to key-auth Plugin

オープン
  • 何か問題がありますか？
#12,908 コメント 2 件 リアクション 1 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

まだ誰も着手していません。

  • #12909 @r-it-ae による — マージされずにクローズ

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
45/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
lua
領域
api, authentication

調査の方向性

まず、key-auth プラグインの実装、そのスキーマ、および既存の認証テストを見つけます。設定されたヘッダーと WWW-Authenticate レスポンスがどのように処理されるかを追跡し、続いて bearer_token が有効な場合と無効な場合について、有効および無効な Authorization 値を含むテストカバレッジを追加します。要求されたトークン抽出、厳密な形式エラー、レスポンススキーム、後方互換性が検証されれば完了です。

索引モデルが issue の本文から書いたものです。

説明

enhancement
Description

Description

The key-auth plugin currently only supports custom header names (default: apikey) for API key authentication. However, it does not support the standard OAuth 2.0 Bearer token format (Authorization: Bearer <token>), which is widely used in modern APIs and is the standard way to pass authentication tokens.

Current Behavior

Currently, when using the key-auth plugin:

  • The API key can be passed via a custom header (default: apikey) or query parameter
  • The header parameter allows customization of the header name
  • Example: apikey: my-secret-key or X-API-KEY: my-secret-key

Expected Behavior

The plugin should support the standard Bearer token format:

  • Accept tokens in the format: Authorization: Bearer <token>
  • When enabled, the plugin should:
    • Force the use of the Authorization header (ignoring the header parameter)
    • Extract the token after the "Bearer " prefix
    • Validate the token format strictly
    • Update the WWW-Authenticate response header to use "Bearer" scheme instead of "apikey"

Use Case

Many APIs and OAuth 2.0-based authentication systems use the Bearer token format as a standard. Supporting this format in the key-auth plugin would:

  1. Standards Compliance: Follow RFC 6750 (Bearer Token Usage) and OAuth 2.0 specifications
  2. Interoperability: Allow APISIX to work seamlessly with existing OAuth 2.0 clients and tools
  3. Migration: Enable easier migration from other API gateways that support Bearer tokens
  4. Developer Experience: Provide familiar authentication patterns that developers expect

Proposed Solution

Add a new boolean parameter bearer_token to the plugin schema:

{
  "plugins": {
    "key-auth": {
      "bearer_token": true
    }
  }
}

When bearer_token is set to true:

  • The plugin should read from the Authorization header only
  • Extract the token after "Bearer " prefix
  • Return 401 with error message "Invalid Bearer token format" if the prefix is missing
  • Set WWW-Authenticate: Bearer realm="key" in error responses

Example Configuration

# Create a consumer
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "username": "jack",
    "plugins": {
      "key-auth": {
        "key": "my-secret-token"
      }
    }
  }'

# Create a route with bearer_token enabled
curl "http://127.0.0.1:9180/apisix/admin/routes/1" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "uri": "/protected",
    "plugins": {
      "key-auth": {
        "bearer_token": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

# Valid request
curl "http://127.0.0.1:9080/protected" \
  -H "Authorization: Bearer my-secret-token"
# Returns: 200 OK

# Invalid request (missing Bearer prefix)
curl "http://127.0.0.1:9080/protected" \
  -H "Authorization: my-secret-token"
# Returns: 401 Unauthorized
# Response: {"message":"Invalid Bearer token format"}

Benefits

  • Backward compatible (default: false)
  • No breaking changes to existing configurations
  • Follows OAuth 2.0 and RFC 6750 standards
  • Simple to implement and use
  • Improves security by enforcing standard token format

Alternative Considered

Using the existing header parameter set to "Authorization" doesn't work because:

  1. It doesn't validate the "Bearer " prefix
  2. The WWW-Authenticate response header still uses "apikey" scheme
  3. Tokens without "Bearer " prefix would be accepted, which is non-standard

Environment

  • APISIX Version: [version]
  • Operating System: [OS]
  • Deployment: [Docker/Bare Metal/Kubernetes]
主要言語
Lua
スター
17.3k
フォーク
3k
平均マージ
4日 16時間
マージ済み PR（30日）
69

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

apache/apisix のほかの issue

apache/apisix の issue をすべて見る

似ている issue

Lua の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。