使用 JWT 驗證使用者

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

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

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

事前準備

  • 按照驗證提供者的說明文件，在用戶端應用程式中新增驗證程式碼。

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

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

在 API Gateway 的 API 設定中，您必須擁有安全性需求物件和安全性定義物件，才能驗證已簽署 JWT 中的憑證附加資訊。

如要支援 JWT 驗證：

  1. 請在 API 設定檔的安全性定義中加入以下內容，並遵循 OpenAPI 2.0 安全性配置方案：

     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. 在 API 層級新增安全性區段，套用至整個 API，或是在方法層級新增安全性區段，套用至特定方法。

     security:
   - your_custom_auth_id: []

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

x-google-audiences 欄位不是必填欄位。API Gateway 會接受所有 JWT，其中後端服務名稱以 https://SERVICE_NAME 的形式出現在 aud 憑證附加資訊中。

如要允許其他用戶端 ID 存取後端服務，您可以使用半形逗號分隔的值，在 x-google-audiences 欄位中指定允許的用戶端 ID。接著，API Gateway 會接受 aud 宣告中任何指定用戶端 ID 的 JWT。

x-google-jwks_uri 欄位是必填欄位。API Gateway 支援 x-google-jwks_uri OpenAPI 擴充功能定義的兩種非對稱公開金鑰格式：

  • 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"

如果您使用的是對稱式金鑰格式，請將 x-google-jwks_uri 設為含有 base64url 編碼金鑰字串的檔案 URI。

對 API Gateway API 發出經過驗證的呼叫

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

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

其中 GATEWAY_URL 和 TOKEN 分別是內含您部署的網關網址和驗證權杖的環境變數。請參閱「向 API Gateway API 發出已驗證的要求」一文，瞭解如何使用 Authorization:Bearer 標頭傳送要求的程式碼範例。

如果您無法在傳送要求時使用標頭，可將認證憑證放入查詢參數中，名為 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 酬載。

後續步驟