このページでは、Cloud Endpoints でユーザー認証をサポートする方法について説明します。
ユーザーを認証するには、クライアント アプリケーションが HTTP リクエストの承認ヘッダー内の JSON Web Token(JWT)をバックエンド API に送信する必要があります。API に代わって Extensible Service Proxy(ESP)がトークンを検証するため、API にコードを追加して認証を処理する必要はありません。ただし、選択した特定の認証方式をサポートするように OpenAPI ドキュメントを構成する必要はあります。
ESP では、JWT の発行者の公開鍵を使用して、パフォーマンスの高い方法で JWT を検証します。ESP は公開鍵を 5 分間キャッシュに保存します。さらに、ESP は検証済みの JWT を 5 分間または JWT の有効期間のいずれか短い方の時間だけキャッシュに保存します。
始める前に
- Firebase Authentication のドキュメントに沿って、クライアント アプリケーションに認証コードを追加してください。Firebase では、パスワード、電話番号、Google、Facebook、Twitter など一般的なフェデレーション ID プロバイダを使用した認証がサポートされています。
- クライアント アプリケーションが HTTP リクエストを送信する際、リクエストの承認ヘッダーには次の JWT クレームが含まれる必要があります。
iss
(issuer)sub
(subject)aud
(audience)iat
(issued at)exp
(expiration time)
OpenAPI ドキュメントの構成
ESP が署名済みの JWT でクレームを検証できるように、OpenAPI ドキュメントにセキュリティ要件オブジェクトとセキュリティ定義オブジェクトが設定されている必要があります。
Firebase 認証をサポートするには:
OpenAPI ドキュメントのセキュリティ定義に次のコードを追加します。
securityDefinitions: firebase: authorizationUrl: "" flow: "implicit" type: "oauth2" # Replace YOUR-PROJECT-ID with your project ID x-google-issuer: "https://securetoken.google.com/YOUR-PROJECT-ID" x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com" x-google-audiences: "YOUR-PROJECT-ID"
security セクションを追加します。API 全体に適用する場合は API レベルに、特定のメソッドに適用する場合はメソッドレベルに追加します。
security: - firebase: []
OpenAPI ドキュメントでは複数のセキュリティ定義を記述できますが、定義ごとに異なる issuer が必要です。security セクションを API レベルとメソッド レベルの両方で指定した場合、API レベルの設定よりもメソッド レベルの設定が優先されます。
x-google-extensions
を追加することによって、JWT の場所をカスタマイズすることもできます。詳細については、openAPI 拡張機能をご覧ください。
Endpoints API への認証済み呼び出しの実行
認証トークンを使用してリクエストを送信する場合は、セキュリティ上の理由から、認証トークンを Authorization:Bearer
ヘッダーに入れることをおすすめします。次に例を示します。
curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"
ENDPOINTS_HOST
と TOKEN
はそれぞれ、API のホスト名と認証トークンを格納する環境変数です。Authorization:Bearer
ヘッダーを使用してリクエストを送信するサンプルコードについては、認証されたリクエストを Endpoints API へ送信するをご覧ください。
リクエストを送信するときにヘッダーを使用できない場合は、access_token
というクエリ パラメータに認証トークンを入れることができます。たとえば次のようになります。
curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"
API での認証結果の受信
通常、ESP は受信したすべてのヘッダーを転送します。ただし、バックエンド アドレスが OpenAPI 仕様の x-google-backend
または gRPC サービス構成の BackendRule
で指定されている場合は、元の Authorization
ヘッダーより優先します。
ESP は認証結果を X-Endpoint-API-UserInfo
でバックエンド API に送信します。元の Authorization
ヘッダーではなく、このヘッダーを使用することをおすすめします。このヘッダーは、base64url
が JSON オブジェクトをエンコードする文字列です。JSON オブジェクトの形式は ESPv2 と ESP で異なります。ESPv2 では、JSON オブジェクトは元の JWT ペイロードになります。ESP では、JSON オブジェクトは異なるフィールド名を使用し、元の JWT ペイロードを claims
フィールドに配置します。形式の詳細については、バックエンド サービスにおける JWT の取り扱いをご覧ください。
次のステップ