使用 Google ID 憑證驗證使用者

本頁說明如何在 API Gateway 中支援使用者驗證。

如要驗證使用者，用戶端應用程式必須在傳送至後端 API 的 HTTP 要求授權標頭中，傳送 JSON Web Token (JWT)。API Gateway 會代表 API 驗證權杖，因此您不必在 API 中新增任何程式碼來處理驗證。不過，您必須為閘道設定 API 設定，才能支援所選的驗證方法。

API Gateway 會使用 JWT 簽發者的 JSON Web Key Set (JWKS)，以高效能的方式驗證 JWT。JWKS 的位置是在閘道的 API 設定中指定。API Gateway 會將 JWKS 快取五分鐘，並每五分鐘重新整理一次。

事前準備

  • 用戶端應用程式傳送 HTTP 要求時，要求中的授權標頭必須包含下列 JWT 聲明：
    • iss (發行者)
    • sub (主旨)
    • aud (目標對象)
    • iat (發行時間)
    • exp (到期時間)

設定 API Gateway 以支援用戶端驗證

您必須在 API 設定中加入安全性部分，API Gateway 才能驗證已簽署 JWT 中的憑證附加資訊。用來定義安全方法的結構定義取決於您使用的 OpenAPI 規格版本。

如何使用 Google ID 憑證支援驗證功能：

OpenAPI 2.0

  1. 在 API 設定中新增下列內容： 
    securityDefinitions:
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    # Optional. Replace CLIENT_ID with your client ID
    x-google-audiences: "CLIENT_ID"
  2. 在 API 層級新增安全性區段，並套用至整個 API，或是在方法層級套用至特定方法。
    security:
   -   google_id_token: []

OpenAPI 3.x

  1. 在 API 設定中新增下列內容： 
    components:
  securitySchemes:
    google_id_token:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: https://accounts.google.com
        jwksUri: https://www.googleapis.com/oauth2/v3/certs
        # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings.
        audiences:
          - CLIENT_ID
  2. 在 API 層級新增安全性區段，並套用至整個 API，或是在方法層級套用至特定方法。
    security:
  - google_id_token: []

您可以在 API 設定中定義多項安全定義，但每項定義必須要有不同的簽發者。如果您在 API 層級和方法層級使用安全性區段，方法層級的設定就會覆寫 API 層級的設定。

x-google-audiences 欄位 (OpenAPI 2.0) 或 audiences 欄位 (OpenAPI 3.x) 為非必填欄位。API Gateway 會接受 aud 憑證附加資訊中含有後端服務名稱 (格式為 https://SERVICE_NAME) 的所有 JWT。

如要允許其他用戶端 ID 存取後端服務，您可以在適用的 audiences 欄位中指定允許的用戶端 ID。在 OpenAPI 2.0 中，多個目標對象會以半形逗號分隔值指定，在 OpenAPI 3.x 中則會以清單指定。API Gateway 接著會接受 aud 聲明中指定任何用戶端 ID 的 JWT。

對 API 閘道 API 發出經過驗證的呼叫

使用認證權杖傳送要求時，建議您將權杖放入 Authorization:Bearer 標頭。例如：

curl -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"

其中 GATEWAY_URL 和 TOKEN 應分別替換為已部署的閘道網址和驗證權杖。如需使用 Authorization:Bearer 標頭傳送要求的程式碼範例，請參閱「向 API Gateway API 發出已驗證的要求」。

如果無法在傳送要求時使用標頭，可將驗證憑證放入查詢參數中，名為 access_token。例如：

curl "GATEWAY_URL/hello?access_token=TOKEN"

在 API 中接收驗證結果

API Gateway 通常會轉發所有接收到的標頭。不過，如果 API 設定中的 x-google-backend 指定後端位址，系統就會覆寫原始的 Authorization 標頭。

API Gateway 會將驗證結果傳送至後端 API 的 X-Apigateway-Api-Userinfo 。建議使用這個標頭，而非原始的 Authorization 標頭。此標頭是由 base64url 所編碼，並且包含 JWT 酬載。

後續步驟