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

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

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

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

始める前に

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

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

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

Google Cloud Endpoints の Okta 統合ガイドで説明したように、OpenAPI ドキュメントを次のように変更します。

  1. OpenAPI ドキュメントのセキュリティ定義に次のコードを追加します。YOUR_OKTA_TENANT_NAME は Okta テナントの名前に、YOUR_OKTA_CLIENT_ID は Okta テナントで作成したクライアント ID に置き換えます。

              securityDefinitions:
                okta_jwt:
                  authorizationUrl: ""
                  flow: "implicit"
                  type: "oauth2"
                  x-google-issuer: "https://YOUR_OKTA_TENANT_NAME.com"
                  x-google-jwks_uri: "https://YOUR_OKTA_TENANT_NAME.com/oauth2/v1/keys"
                  x-google-audiences: "YOUR_OKTA_CLIENT_ID"
        
  2. security セクションを追加します。API 全体に適用する場合は API レベルに、特定のメソッドに適用する場合はメソッドレベルに追加します。

      security:
            - okta_jwt: []
        

OpenAPI ドキュメントでは複数のセキュリティ定義を定義できますが、定義ごとに、異なる発行者が必要です。API レベルとメソッドレベルの両方で セキュリティ セクションを使用する場合、API レベルの設定よりもメソッドレベルの設定が優先されます。

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

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 ベータ版への移行をご覧ください。

次のステップ