驗證使用者

本頁面說明如何在 API 中使用 Cloud Endpoints Frameworks 從用戶端應用程式新增支援,以進行使用者驗證。請注意,目前支援 Android 和 JavaScript 用戶端。

Endpoints Frameworks 支援使用以下任何方法的用戶端應用程式進行使用者驗證:

無論使用哪種驗證方法,在每種 API 方法中檢查正確驗證時,您都必須檢查有效的 User。您可於下列各文找到相關說明:

必備條件

本頁假設您已具備以下條件:

使用 Firebase Auth 進行驗證

若要支援使用 Firebase Auth 的呼叫:

  1. 如果您尚未建立一個 Firebase 專案,請先建立。Firebase 專案是使用 Firebase 服務的 Google Cloud Platform 主控台專案。詳情情參閱何謂 Firebase 專案?以及 Firebase 說明文件

  2. 將以下內容新增到 @Api 或方法註解:

    • authenticators 參數新增到註解,並設為 {EspAuthenticator.class} 值。
    • 新增 issuers 參數,當中須包含設為 Firebase 的 @ApiIssuer
    • 新增 issuerAudiences 參數,當中須包含設為 Firebase 和相關專案 ID 的 @ApiIssuerAudience

    例如:

    @Api(
        name = "YOUR_API_NAME",
        version = "VERSION_NUMBER",
        authenticators = {EspAuthenticator.class},
        issuers = {
            @ApiIssuer(
                name = "firebase",
                issuer = "https://securetoken.google.com/YOUR_PROJECT_ID",
                jwksUri = "https://www.googleapis.com/service_accounts/VERSION_NUMBER/metadata/x509/securetoken@system.gserviceaccount.com")
        },
        issuerAudiences = {
            @ApiIssuerAudience(name = "firebase", audiences = "YOUR_PROJECT_ID")
        })
    
    • YOUR_API_NAME 替換為您的 API 名稱。
    • VERSION_NUMBER 替換為您的 API 版本,例如 v1
    • YOUR_PROJECT_ID 的兩個執行個體替換為 Firebase 專案 ID。
  3. 在 API 的實作程式碼中匯入 Users

    import com.google.api.server.spi.auth.common.User;
    
  4. 在要檢查正確驗證的每種 API 方法中,檢查有效的 User 並在發現無效時擲回例外狀況,此範例方法定義如下所示:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  5. 在新增用戶端時重新部署 API

將 Firebase 驗證新增到用戶端

您可以按照 Firebase 說明文件,將 Firebase 驗證新增至您的程式碼中。用戶端必須具有相關的 GCP 專案,且專案 ID 必須列於 API 的 Firebase 發行者設定中,如上一節所示。

使用 Auth0 進行驗證

若要從使用 Auth0 的用戶端支援呼叫:

  1. 將以下內容新增到 @Api 或方法註解:

    • authenticators 參數新增到註解,並設為 {EspAuthenticator.class} 值。
    • 新增 issuers 參數,當中須包含設為 Auth0 的 @ApiIssuer
    • 新增 issuerAudiences 參數,當中須包含設為 Auth0 和您的 Auth0 用戶端 ID 的 @ApiIssuerAudience

    例如:

    @Api(
        name = "YOUR_API_NAME",
        version = "VERSION_NUMBER",
        authenticators = {EspAuthenticator.class},
        issuers = {
            @ApiIssuer(
                name = "auth0",
                issuer = "https://YOUR_ACCOUNT_NAME.auth0.com/",
                jwksUri = "https://YOUR_ACCOUNT_NAME.auth0.com/.well-known/jwks.json")
         },
         issuerAudiences = {
             @ApiIssuerAudience(name = "auth0", audiences = "AUTH0_CLIENT_ID")
        })
    
    • YOUR_API_NAME 替換為您的 API 名稱。
    • VERSION_NUMBER 替換為您的 API 版本,例如 v1
    • YOUR_ACCOUNT_NAME 替換為用戶端的 Auth0 帳戶名稱。
    • AUTH0_CLIENT_ID 替換為您要用於用戶端的 ID。
  2. 在 API 的實作程式碼中匯入 Users

    import com.google.api.server.spi.auth.common.User;
    
  3. 在要檢查正確驗證的每種 API 方法中,檢查有效的 User 並在發現無效時擲回例外狀況,此範例方法定義如下所示:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  4. 在新增用戶端時重新部署 API

將 Auth0 驗證新增到用戶端

您可以按照 Auth0 說明文件的說明,將 Auth0 驗證新增至您的程式碼中。用戶端必須列在 API 的 Auth0 發行者設定中。

使用 Google ID 憑證進行驗證

如要支援使用 Google ID 憑證進行驗證的用戶端呼叫,請按照以下步驟操作:

  1. 為每個用戶端應用程式取得 OAuth 2 用戶端 ID。用戶端應用程式擁有者必須透過 Google Cloud Platform 主控台產生用戶端 ID。如需操作說明,請參閱建立用戶端 ID 一文。

  2. 為每個您要授予存取權的用戶端應用程式,新增包含用戶端 ID 的 clientIds 項目,並為每個 Andoird 用戶端新增 audiences 項目 (在您的 @Api 註解中)。

    例如:

    @Api(
       name = "YOUR_API_NAME",
       version = "VERSION_NUMBER",
       clientIds = {"YOUR_CLIENT_ID"},
       audiences = {"YOUR_CLIENT_ID"}
    )
    
    • YOUR_API_NAME 替換為您的 API 名稱。
    • VERSION_NUMBER 替換為您的 API 版本,例如 v1
    • YOUR_CLIENT_ID 替換為在用戶端應用程式專案中產生的 OAuth 2 用戶端 ID。
  3. 在 API 的實作程式碼中匯入 Users

    import com.google.api.server.spi.auth.common.User;
    
  4. 在要檢查正確驗證的每種 API 方法中,檢查有效的 User 並在發現無效時擲回例外狀況,此範例方法定義如下所示:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  5. 在新增用戶端時重新部署 API

將 Google ID 憑證驗證新增到用戶端

如需關於新增驗證程式碼至用戶端的資訊,請參閱:

在用戶端中傳送 JWT

若您在用戶端使用 JWT 將經過驗證的要求傳送到 API,則 JWT 必須位於 HTTP 要求的授權標頭中。JWT 應具備以下所需的聲明:

  • iss
  • sub
  • aud
  • iat
  • exp

後續步驟

參閱 API 金鑰的使用時機與原因一文,瞭解使用者驗證的背景資訊,以及使用者驗證與 API 金鑰驗證的不同之處。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁