驗證使用者

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

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

• Firebase 驗證
• Auth0
• Google ID 權杖

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

• 使用 Firebase Auth 進行驗證
• 使用 Auth0 進行驗證
• 使用 Google ID 憑證驗證

必備條件

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

• 建立 Google Cloud專案。

• 已新增 API 管理。

使用 Firebase Auth 進行驗證

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

1. 如果您尚未建立一個 Firebase 專案，請先建立。Firebase 專案是使用 Firebase 服務的 Google Cloud 主控台專案。詳情請參閱「何謂 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/v1/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 驗證新增至您的程式碼中。用戶端必須具有相關的 Google Cloud 專案，且專案 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 控制台產生用戶端 ID。如需操作說明，請參閱「建立用戶端 ID」。

2. 為每個您要授予存取權的用戶端應用程式，新增包含用戶端 ID 的 clientIds 項目，並為每個 Android 用戶端新增 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 憑證驗證新增到用戶端

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

• Android 應用程式

在用戶端中傳送 JWT

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

• iss
• sub
• aud
• iat
• exp

後續步驟

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