Forward-Auth、認証機能のもう一つの選択肢

API7.ai

January 26, 2022

Ecosystem

Forward Authは、認証と認可のロジックを専用の外部サービスに巧妙に移行します。ゲートウェイはユーザーのリクエストを認証サービスに転送し、認証サービスが20x以外のステータスで応答した場合、元のリクエストをブロックして結果を置き換えます。これにより、認証が失敗した場合にカスタムエラーを返したり、ユーザーを認証ページにリダイレクトしたりすることが可能になります。

原理

プラグインの原理

Apache APISIXのforward-authプラグインの原理とフローは上図の通りで、以下のステップにまとめられます。

  • ステップ1: クライアントがAPISIXにリクエストを送信
  • ステップ2: APISIXがユーザー設定の認証サービスにリクエストを送信
  • ステップ3: 認証サービスが応答（2xxまたは例外ステータス）
  • ステップ4: 認証サービスの応答に基づき、APISIXはリクエストをアップストリームに転送するか、クライアントに拒否応答を直接送信するかを決定

使用方法

ステップ1: 認証サービスの設定

認証サービスがあり、ユーザーがAuthorizationリクエストヘッダーを付けてリクエストを送信するとします。このデータが認証を通過すると、200ステータスコードとX-User-IDというレスポンスヘッダーが返されます。認証を通過しない場合、認証ステータスが期限切れと見なされ、302ステータスコードとLocationレスポンスヘッダーが返され、クライアントをログインページにリダイレクトします。

ステップ2: ルートの作成とforward-authプラグインの有効化

次に、ルートを設定し、forward-authプラグインを有効にして、上記の認証サービスをアップストリームアプリケーションと連携させます。

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
        "forward-auth": {
            "address": "http://127.0.0.1:9080/auth",
            "request_headers": ["Authorization"],
            "upstream_headers": ["X-User-ID"],
            "client_headers": ["Location"]
        }
    },
    "uri": "/user"
}'

上記の設定の詳細は以下の通りです。

  • リクエストが現在のルートにマッチすると、addressに指定されたアドレスにリクエストが送信され、request_headersで定義されたAuthorizationリクエストヘッダー（クライアントが認証サービスに転送するように設定されたリクエストヘッダー、設定されていない場合は転送されない）が付加されます。これにより、認証サービスはユーザーの身元を確認できます。
  • 認証が成功すると、ステータスコード200が返され、upstream_headersで定義されたX-User-ID（認証が成功した場合に認証サービスがアップストリームに転送するリクエストヘッダー、設定されていない場合は転送されない）が返されます。
  • 認証が失敗すると、ステータスコード302が返され、client_headersで定義されたLocation（認証が失敗した場合に認証サービスがクライアントに送信するレスポンスヘッダー、設定されていない場合は送信されない）が返されます。

ステップ3: リクエストのテスト

# POSTを使用してリクエストを送信
curl http://127.0.0.1:9080/user \
    --header 'Authorization: true'

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 28
Server: APISIX/2.11.0

{"user_id":"i-am-real-user"}

# GETを使用してリクエスト
curl -i http://127.0.0.1:9080/user \
    --header 'Authorization: false'

HTTP/1.1 302 FOUND
Server: APISIX/2.11.0
Location: https://example.com/auth

補足: プラグインの無効化

Forward Authプラグインの使用が終了したら、ルート設定からforward-authプラグインの設定を削除して保存するだけで、ルート上のForward Authプラグインを無効にできます。

Apache APISIXの動的な性質により、プラグインの有効化や無効化にApache APISIXの再起動は必要ありません。

まとめ

forward-authプラグインの詳細な説明と完全な設定リストについては、公式ドキュメントを参照してください。また、より複雑な認証や認可のアプリケーションシナリオがある場合は、opaプラグインを試してみてください。これにより、プログラム可能な方法でより強力な機能を実現できます。

Apache APISIXは現在、追加のサービス統合をサポートするための追加プラグインの開発にも取り組んでいます。興味がある場合は、GitHub Discussionでディスカッションを開始するか、メーリングリストを通じてコミュニケーションを取ってください。

Tags:
APISIX Basics
Plugin