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

Microservices Engine:oauth

最終更新日:Jan 08, 2025

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

プラグインの種類

認証プラグイン。

プラグイン設定の説明

フィールド

承認設定

名前

データ型

必須

デフォルト値

説明

consumers

オブジェクトの配列

はい

-

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

issuer

文字列

いいえ

Higress-Gateway

JWT発行者。

auth_path

文字列

いいえ

/oauth2/token

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

global_credentials

ブール値

いいえ

true

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

auth_header_name

文字列

いいえ

Authorization

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

token_ttl

数値

いいえ

7200

トークンが発行されてからの有効期間(TTL)。単位:秒。

clock_skew_seconds

数値

いいえ

60

JWTのexpフィールドとiatフィールドが検証されるときに許容されるクロックスキュー。単位:秒。

keep_token

ブール値

いいえ

true

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

global_auth

文字列の配列

いいえ (**インスタンスレベルの設定の場合のみ必須**)

-

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

次の表は、consumers フィールドの設定項目について説明しています。

名前

データ型

必須

デフォルト値

説明

name

文字列

はい

-

コンシューマーの名前。

client_id

文字列

はい

-

OAuth 2.0クライアントのID。

client_secret

文字列

はい

-

OAuth 2.0クライアントのシークレット。

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

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

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

認証設定(オプション)

名前

データ型

必須

デフォルト値

説明

allow

文字列の配列

いいえ (**インスタンスレベル以外の設定**)

-

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

重要

承認設定と認証設定は、1つのルールで共存できません。

設定例

ルートレベルの承認設定

次のプラグイン設定を 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 にアクセスすることはできません。同様に、route-bによって発行された資格情報を使用してroute-aにアクセスすることはできません。

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

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

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

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

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

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-a ルートと route-b ルートは、ゲートウェイルートの作成時に指定されたルートです。クライアントリクエストが2つのルートと一致する場合、nameconsumer1 である呼び出し元はゲートウェイへのアクセスを許可されます。他の呼び出し元はゲートウェイにアクセスできません。

  • この例では、*.example.com ドメイン名と test.com ドメイン名は、リクエスト内のドメイン名と照合するために使用されます。クライアントリクエストが2つのドメイン名と一致する場合、nameconsumer2 である呼び出し元はゲートウェイへのアクセスを許可されます。他の呼び出し元はゲートウェイにアクセスできません。

ゲートウェイレベルで認証を有効にする

次の設定は、ゲートウェイレベルで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

サンプルリクエスト

クライアント資格情報付与タイプを使用する

アクセストークンを取得する

# GETメソッドを使用してアクセストークンを取得します。このメソッドを使用することをお勧めします。
curl 'http://test.com/oauth2/token?grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# POSTメソッドを使用してアクセストークンを取得します。この操作を実行するには、実際の宛先サービスを指すルートと一致させる必要があります。そうでない場合、ゲートウェイはリクエスト本文を読み取りません。
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'

# レスポンスからaccess_tokenフィールドの値を取得します。
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0",
  "expires_in": 7200
}

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

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

HTTPステータスコード

HTTPステータスコード

エラーメッセージ

理由

401

無効なJWTトークン。

リクエストヘッダーにJWTが提供されていないか、JWT形式が無効か、JWTの有効期限が切れています。

403

アクセスが拒否されました。

コンシューマーは現在のルートへのアクセスが許可されていません。