使用自訂方法驗證使用者

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

如要驗證使用者，用戶端應用程式必須在 HTTP 要求的授權標頭中，傳送 JSON Web Token (JWT) 至後端 API。可擴充服務 Proxy (ESP) 會代表您的 API 驗證權杖，因此您不必在 API 中新增任何程式碼來處理驗證程序。不過，您必須設定 OpenAPI 文件，以支援所選的驗證方法。

ESP 會使用 JWT 發出者的公開金鑰，以高效的方式驗證 JWT。ESP 會快取公開金鑰五分鐘。此外，ESP 會將已驗證的 JWT 快取五分鐘，或直到 JWT 到期為止，以先到者為準。

事前準備

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

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

設置 ESP 來支援客戶端身分認證

在您的 OpenAPI 文件中必須擁有安全性需求物件與安全性定義物件，讓 ESP 能夠驗證已簽署 JWT 中的憑證附加資訊。

如何支援自訂驗證：

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

     security:
   - your_custom_auth_id: []

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

x-google-audiences 欄位並非必填欄位。ESP 會接受所有 JWT，其中後端服務名稱以 aud 憑證附加資訊中的 https://SERVICE_NAME 格式表示。如要允許其他用戶端 ID 存取後端服務，您可以使用半形逗號分隔的值，在 x-google-audiences 欄位中指定允許的用戶端 ID。接著，ESP 會接受 JWT，其中包含 aud 憑證中的任何指定用戶端 ID。

ESP 支援 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。

如果您省略 x-google-jwks_uri，ESP 會依照 OpenID Connect Discovery 通訊協定，自動探索指定 OpenID 提供者的 JWKS URI。ESP 會向 x-google-issuer/.well-known/openid-configuration 提出要求、剖析 JSON 回應，並從頂層 jwks_uri 欄位讀取 JWKS URI。

請注意，省略 x-google-jwks_uri 會導致冷啟動時間增加，因為 ESP 必須在啟動時進行額外的遠端呼叫。因此，只有在 JWKS URI 經常變更時，才建議省略這個欄位。大多數經認證的 OpenID 供應商 (例如 Google、Auth0 和 Okta) 都有穩定的 JWKS URI。

您也可以新增 x-google-extensions 自訂 JWT 位置。詳情請參閱「OpenAPI 擴充功能」。

讓身分認證呼叫 Endpoints API

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

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

在此，ENDPOINTS_HOST 和 TOKEN 分別是內含您 API 主機名稱和 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 物件的字串。ESPv2 和 ESP 的 JSON 物件格式不同。對於 ESPv2，JSON 物件就是原始的 JWT 酬載。針對 ESP，JSON 物件會使用不同的欄位名稱，並將原始 JWT 酬載放在 claims 欄位下。如要進一步瞭解格式，請參閱「在後端服務中處理 JWT」。

後續步驟