すべてのプロダクト
Search
ドキュメントセンター

API Gateway:oauth

最終更新日:Jan 09, 2025

oauthプラグインは、JSON webトークン (JWT) に基づいてOAuth 2.0アクセストークンを発行するために使用されます。 oauthプラグインは、RFC9068仕様に準拠しています。 このトピックでは、oauthプラグインを設定する方法について説明します。

プラグイン型

認証と承認のためのプラグイン。

設定の説明

フィールド

権限付与の設定

項目

データ型

必須 / 任意

デフォルト値

説明

消費者

オブジェクトの配列

対象

-

サービスの呼び出し元であるコンシューマーの名前。 このフィールドは、リクエストを認証するために使用されます。

発行者

String

非対象

Higress-ゲートウェイ

JWT発行者。

auth_path

String

非対象

/oauth2 /トークン

指定されたパスのサフィックス。 サフィックスはトークンの発行に使用されます。 このフィールドをルートレベルで設定するときは、指定したルートが一致することを確認する必要があります。 API管理機能を使用してAPIを作成する場合は、同じパスを持つAPIを作成する必要があります。

global_資格情報

bool

非対象

true

コンシューマー認証に合格した場合に、アクセス用のルートによって発行された資格情報を使用するかどうかを指定します。

auth_header_name

String

非対象

承認

JWTを取得できるリクエストヘッダー。

token_ttl

数値

非対象

7200

トークンが発行された後の有効期間 (TTL) 。 単位は秒です。

clock_skew_秒

数値

非対象

60

JWT内のexpおよびiatフィールドが検証されるときに許容されるクロックスキュー。 単位は秒です。

keep_token

bool

非対象

true

リクエストがバックエンドサービスに転送されるときに、リクエスト内のJWTを保持するかどうかを指定します。

global_auth

文字列の配列

いいえ (インスタンスレベルの設定にのみ必要)

-

このフィールドは、インスタンスレベルでのみ設定できます。 このフィールドがtrueに設定されている場合、認証メカニズムはグローバルに有効になります。 このフィールドがfalseに設定されている場合、認証メカニズムは設定されたドメイン名とルートに対してのみ有効になります。 このフィールドが設定されていない場合、認証メカニズムはドメイン名とルートが設定されていない場合にのみグローバルに有効になります。 これは、古いユーザの使用習慣を考慮したものである。

次の表に、consumersのフィールドを示します。

項目

データ型

必須 / 任意

デフォルト値

説明

name

String

対象

-

コンシューマーの名前。

client_id

String

対象

-

OAuth 2.0クライアントのID。

client_secret

String

対象

-

OAuth 2.0クライアントの秘密。

重要
  • 上記の設定が有効になっているルートの場合、パスサフィックスとauth_pathが一致すると、システムはルート情報を宛先サービスに転送せず、ルートを使用してトークンを生成します。

  • global_credentialsフィールドがfalseに設定されている場合、プラグインが有効になっているルートが完全一致を使用しないことを確認する必要があります。 別のルートが存在し、プレフィックス一致を使用する場合、予期しない問題が発生する可能性があります。

  • 認証されたリクエストの場合、X-Mse-Consumerフィールドがリクエストヘッダーに追加され、呼び出し元の名前が識別されます。

(オプション) 許可設定

項目

データ型

必須 / 任意

デフォルト値

説明

許可する

文字列の配列

いいえ (非インスタンスレベルの設定には必須)

-

このフィールドは、ルートやドメイン名などの細かい粒度でのみ設定できます。 一致する条件を満たすリクエストについては、アクセスを許可されるコンシューマーを設定できます。 これにより、詳細な権限制御が実装されます。

重要

許可設定と認証設定はルール内で共存できません。

ルートレベルの認証設定

route-aおよびroute-bのルートに次のプラグイン設定を適用します。

consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

同じ設定が使用されていますが、route-aによって発行された資格情報を使用してroute-bにアクセスすることはできません。

同じ設定に基づいて資格情報のアクセス許可を共有する場合は、次の設定を適用できます。

global_credentials: true
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

グローバル認証設定とルートレベル認証設定

次の設定では、ゲートウェイの特定のルートまたはドメイン名に対してJWT認証を有効にします。 JWTが複数のJSON Webキーセット (JWKS) と一致する場合、一致した最初のコンシューマーが設定シーケンスに基づいてヒットします。

インスタンスレベルで次のプラグイン設定を適用します。

global_auth: false
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

route-aおよびroute-bのルートに次のプラグイン設定を適用します。

allow:
- consumer1

次のプラグイン設定を * .example.comおよびtest.comドメイン名に適用します。

allow:
- consumer2
説明
  • この例では、route-aroute-bのルートは、ゲートウェイルートの作成時に指定されたルートです。 クライアント要求が2つのルートと一致する場合、名前consumer1である呼び出し元はゲートウェイにアクセスできます。 他の発信者はゲートウェイにアクセスできません。

  • この例では、* .example.comtest.comドメイン名を使用して、リクエストのドメイン名を照合します。 クライアント要求が2つのドメイン名と一致する場合、名前consumer2である呼び出し元はゲートウェイにアクセスできます。 他の発信者はゲートウェイにアクセスできません。

ゲートウェイレベルでの認証の有効化

次の設定では、ゲートウェイレベルでOAuth2認証が有効になります。 すべてのリクエストは、ゲートウェイにアクセスする前に認証する必要があります。

global_auth: true
consumers:
- name: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

サンプルリクエスト

クライアント資格付与タイプの使用

アクセストークンの取得

# Obtain an access token by using the GET method. We recommend that you use this method.
curl 'http://test.com/oauth2/token?grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Obtain an access token by using the POST method. To perform this operation, you need to match a route that points to a real destination service. Otherwise, the gateway does not read request bodies.
curl 'http://test.com/oauth2/token' -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Obtain the value of the access_token field from the response.
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0",
  "expires_in": 7200
}

アクセストークンを使用してリクエストを開始

curl 'http://test.com' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0'

エラーコード

HTTPステータスコード

エラーメッセージ

理由

401

無効なJwtトークン。

リクエストヘッダーにJWTが指定されていないか、JWT形式が無効であるか、JWTが期限切れになります。

403

アクセス拒否。

コンシューマは、現在のルートにアクセスする権限がありません。