ユーザーを認証するためのカスタム メソッドの使用

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

ユーザーを認証するには、クライアント アプリケーションが HTTP リクエストの承認ヘッダーで JSON ウェブトークン(JWT)をバックエンド API に送信する必要があります。Extensible Service Proxy(ESP)が API に代わってトークンを検証するため、API でコードを追加して認証を処理する必要はありません。ただし、選択した認証方法をサポートするように OpenAPI ドキュメントを構成する必要があります。

ESP では、JWT の発行者の公開鍵を使用して、パフォーマンスの高い方法で JWT を検証します。ESP は公開鍵を 5 分間キャッシュに保存します。さらに、ESP は検証済みの JWT を 5 分間または JWT の有効期間のいずれか短い方の時間だけキャッシュに保存します。

始める前に

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

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

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

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

カスタム認証をサポートするには:

  1. OpenAPI ドキュメントのセキュリティ定義に次のコードを追加します。

     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"
        
  2. security セクションを追加します。API 全体に適用する場合は API レベルに、特定のメソッドに適用する場合はメソッドレベルに追加します。

     security:
           - your_custom_auth_id: []
        

OpenAPI ドキュメントでは複数のセキュリティ定義を記述できますが、定義によって issuer は異なります。security セクションを API レベルとメソッドレベルの両方で指定した場合、API レベルの設定よりもメソッドレベルの設定が優先されます。

x-google-audiences フィールドは必須ではありません。ESP は、バックエンド サービス名を持つすべての JWT を、aud クレームの https://SERVICE_NAME のフォームで受け入れます。追加のクライアント ID によるバックエンド サービスへのアクセスを許可するには、x-google-audiences フィールドに許可されたクライアント ID をカンマ区切りで指定します。これにより、ESP は aud クレーム内で指定されたクライアント ID のいずれかを持つ JWT を受け入れます。

ESP では、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 を設定します。

x-google-jwks_uri を省略すると、ESP は OpenID Connect Discovery プロトコルに従って、指定された OpenID プロバイダの JWKS URI を自動的に検出します。 ESP は x-google-issuer/.well-known/openid-configuration にリクエストを送信し、JSON レスポンスを解析し、最上位の jwks_uri フィールドから JWKS URI を読み取ります。

ESP は起動時に追加のリモート呼び出しを行う必要があるため、x-google-jwks_uri を省略するとコールド スタート時間が長くなります。 したがって、JWKS URI が頻繁に変更される場合にのみ、このフィールドを省略することをおすすめします。 ほとんどの認定 OpenID プロバイダ(Google、Auth0、Okta など)では、JWKS URI は変更されません。

Endpoints API への認証済み呼び出しの実行

認証トークンを使用してリクエストを送信する場合は、セキュリティ上の理由から、認証トークンを Authorization:Bearer ヘッダーに入れることをおすすめします。例:

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"
    

ENDPOINTS_HOSTTOKEN はそれぞれ、API のホスト名と認証トークンを格納する環境変数です。認証されたリクエストを Endpoints API に送信するをご覧ください。 Authorization:Bearer ヘッダーを使用してリクエストを送信するコードのサンプルをご覧ください。

リクエストを送信するときにヘッダーを使用できない場合は、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 オブジェクトが含まれています。

    {
      "id": "from-sub",
      "issuer": "from-iss",
      "email": "from-email",
      "audiences": ["from-aud"],
      "claims": {
         original-jwt-payload
       }
    }
    

ESPv2 ベータ版を使用している場合、ヘッダー内の値の形式は異なります。 新しい形式の詳細については、Extensible Service Proxy V2 ベータ版に移行するをご覧ください。

次のステップ