JWT を使用したユーザーの認証

このページでは、API Gateway でユーザー認証をサポートする方法について説明します。

ユーザーを認証するには、クライアントアプリケーションが HTTP リクエストの承認ヘッダー内の JSON Web Token（JWT）をバックエンド API に送信する必要があります。API Gateway は API に代わってトークンを検証するので、ユーザーが自分で API にコードを追加して認証を処理する必要はありません。ただし、選択した認証方法をサポートするようにゲートウェイの API 構成を行う必要があります。

API Gateway は、JWT 発行者の JSON ウェブキーセット（JWKS）を使用して、パフォーマンスの高い方法で JWT を検証します。JWKS のロケーションは、ゲートウェイの API 構成の x-google-jwks_uri フィールドで指定されます。API Gateway は JWKS を 5 分間キャッシュに保存し、5 分ごとに更新します。

始める前に

認証プロバイダのドキュメントに従って、認証コードをクライアントアプリケーションに追加します。

クライアントアプリケーションが HTTP リクエストを送信する際、リクエストの承認ヘッダーには次の JWT クレームが含まれる必要があります。
- iss（issuer）
- sub（subject）
- aud（audience）
- iat（issued at）
- exp（expiration time）

クライアント認証をサポートする API Gateway の構成

API Gateway で署名済みの JWT でクレームを検証できるように、API 構成にセキュリティ要件オブジェクトとセキュリティ定義オブジェクトが設定されている必要があります。

JWT 認証をサポートするには:

OpenAPI 2.0 セキュリティスキームに従った API 構成のセキュリティ定義に、次の内容を追加します。

 securityDefinitions:
   your_custom_auth_id:
     authorizationUrl: ""
     flow: "implicit"
     type: "oauth2"
     # The value below should be unique
     x-google-issuer: "issuer of the token"
     x-google-jwks_uri: "url to the public key"
     # Optional. Replace YOUR-CLIENT-ID with your client ID
     x-google-audiences: "YOUR-CLIENT-ID"

security セクションを追加します。API 全体に適用する場合は API レベルに、特定のメソッドに適用する場合はメソッドレベルに追加します。
```
 security:
   - your_custom_auth_id: []
```

API 構成には複数のセキュリティ定義を定義できますが、各定義の発行者は異なっている必要があります。security セクションを API レベルとメソッドレベルの両方で指定した場合、API レベルの設定よりもメソッドレベルの設定が優先されます。

x-google-audiences フィールドは必要ありません。API Gateway は、aud クレーム内で https://SERVICE_NAME という形式のバックエンドサービス名を持つすべての JWT を受け入れます。

注: API Gateway は、aud クレームで次の URI タイプを受け入れません。

内部アドレス
IPv4 または IPv6 アドレス

追加のクライアント ID によるバックエンドサービスへのアクセスを許可するには、カンマ区切り値を使用して x-google-audiences フィールドに許可されたクライアント ID を指定します。これにより、API Gateway は、aud クレーム内で指定されたクライアント ID のいずれかを持つ JWT を受け入れます。

x-google-jwks_uri フィールドは必須です。API Gateway は、x-google-jwks_uri OpenAPI 拡張で定義された次の 2 つの非対称公開鍵形式がサポートされています。

JWK セット形式例:

x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

X509例:

x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

対称鍵形式を使用する場合は、Base64URL エンコードされた鍵文字列を含むファイルの URI に x-google-jwks_uri を設定します。

注: API Gateway が x-google-jwks_uri にリクエストを送信すると、リクエストには x-forwarded-proto ヘッダーが含まれます。

認証された呼び出しを API Gateway API に送信する

認証トークンを使用してリクエストを送信する場合は、トークンを Authorization:Bearer ヘッダーに入れることをおすすめします。次に例を示します。

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

ここで、GATEWAY_URL と TOKEN はそれぞれ、デプロイされたゲートウェイの URL と認証トークンを格納する環境変数です。Authorization:Bearer ヘッダーを使用してリクエストを送信するサンプルコードについては、認証されたリクエストを API Gateway API へ送信するをご覧ください。

リクエストを送信するときにヘッダーを使用できない場合は、access_token というクエリパラメータに認証トークンを入れることができます。たとえば次のようになります。

curl "${GATEWAY_URL}/echo?access_token=${TOKEN}"

API での認証結果の受信

通常、API Gateway は受信したすべてのヘッダーを転送します。ただし、バックエンドアドレスが API 構成の x-google-backend で指定されている場合は、元の Authorization ヘッダーより優先します。

API Gateway が X-Apigateway-Api-Userinfo の認証結果をバックエンド API に送信します。元の Authorization ヘッダーではなく、このヘッダーを使用することをおすすめします。このヘッダーは base64url エンコードされ、JWT ペイロードが含まれています。

次のステップ

サービス間の認証