使用自訂方法驗證使用者

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

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

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

事前準備

  • 按照驗證供應商的說明文件，將驗證碼新增至用戶端應用程式。

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

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

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

如要支援自訂驗證，請按照下列步驟操作：

OpenAPI 2.0

  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 3.x

  1. 在 OpenAPI 文件的安全性定義中加入下列內容： 
    components:
  securitySchemes:
    your_custom_auth_id:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "issuer of the token"
        jwksUri: "url to the public key"
        audiences:
          - "YOUR_CLIENT_ID"
  2. 在 API 層級新增安全性區段，並套用至整個 API，或是在方法層級套用至特定方法。
    security:
  - your_custom_auth_id: []

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

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

ESP 支援 x-google-jwks_uri 和 jwksUri OpenAPI 擴充功能定義的兩種非對稱公開金鑰格式：

  • JWK 集格式。 例如：

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    x-google-auth:
  jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509。例如：

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    x-google-auth:
  jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

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

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

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

您也可以新增 x-google 擴充功能，自訂 JWT 位置。詳情請參閱 OpenAPI 2.0 擴充功能 或 OpenAPI 3.x 擴充功能。

讓身分認證呼叫 Endpoints API

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

curl -H "Authorization: Bearer <var>TOKEN</var>" "<var>ENDPOINTS_HOST</var>/echo"

請在此將 ENDPOINTS_HOST 和 TOKEN 變數分別替換為 API 主機名稱和驗證權杖。如需使用 Authorization:Bearer 標頭傳送要求的範例程式碼，請參閱「向 Endpoints API 發出經過驗證的要求」。

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

curl "<var>ENDPOINTS_HOST</var>/echo?access_token=<var>TOKEN</var>"

在 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」。

後續步驟