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つのルートと一致する場合、nameがconsumer1である呼び出し元はゲートウェイへのアクセスを許可されます。他の呼び出し元はゲートウェイにアクセスできません。この例では、
*.example.comドメイン名とtest.comドメイン名は、リクエスト内のドメイン名と照合するために使用されます。クライアントリクエストが2つのドメイン名と一致する場合、nameが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サンプルリクエスト
クライアント資格情報付与タイプを使用する
アクセストークンを取得する
# 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 | アクセスが拒否されました。 | コンシューマーは現在のルートへのアクセスが許可されていません。 |