Java 8 適用的 Users API 總覽

Users API 允許應用程式:

  • 偵測目前的使用者是否已登入。
  • 將使用者重新導向至適當的登入頁面以進行登入。
  • 如果應用程式使用者尚未擁有 Google 帳戶,則要求使用者建立新帳戶。

使用者登入應用程式後,應用程式即可存取該使用者的電子郵件地址,而且也可以偵測目前的使用者是否為管理員 (也稱為「管理員使用者」),方便您實作應用程式的管理員專屬區域。

在 Java 應用程式中驗證使用者

下列範例是以個人化訊息來歡迎登入應用程式的使用者,並為其提供一個登出連結。如果使用者未登入,應用程式會提供對於「Google 帳戶」登入頁面的連結。

您可以使用標準 Servlet API 及要求物件的 getUserPrincipal() 方法,測試使用者是否已登入,並取得使用者的電子郵件地址。您可以利用 User Service API 來產生登入和登出網址。

Java 8


package com.example.appengine.users;

import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import java.io.IOException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "UserAPI",
    description = "UserAPI: Login / Logout with UserService",
    urlPatterns = "/userapi"
)
public class UsersServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();

    String thisUrl = req.getRequestURI();

    resp.setContentType("text/html");
    if (req.getUserPrincipal() != null) {
      resp.getWriter()
          .println(
              "<p>Hello, "
                  + req.getUserPrincipal().getName()
                  + "!  You can <a href=\""
                  + userService.createLogoutURL(thisUrl)
                  + "\">sign out</a>.</p>");
    } else {
      resp.getWriter()
          .println(
              "<p>Please <a href=\"" + userService.createLoginURL(thisUrl) + "\">sign in</a>.</p>");
    }
  }
}

Java 7


package com.example.appengine.users;

import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import java.io.IOException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class UsersServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws IOException {
    UserService userService = UserServiceFactory.getUserService();

    String thisUrl = req.getRequestURI();

    resp.setContentType("text/html");
    if (req.getUserPrincipal() != null) {
      resp.getWriter().println("<p>Hello, "
          + req.getUserPrincipal().getName()
          + "!  You can <a href=\""
          + userService.createLogoutURL(thisUrl)
          + "\">sign out</a>.</p>");
    } else {
      resp.getWriter().println("<p>Please <a href=\""
          + userService.createLoginURL(thisUrl)
          + "\">sign in</a>.</p>");
    }
  }
}

User Service API 可以將目前使用者資訊做為 User 物件傳回。雖然 User 物件可以做為屬性值儲存在資料儲存庫中,但我們強烈建議您避免這麼做,因為這包含電子郵件地址以及使用者的唯一 ID。如果使用者變更了電子郵件地址,但您還是使用先前儲存的 User 來比對新的 User 值,兩者將無法配對。請考慮改為使用「User 使用者 ID 值」做為該使用者的穩定唯一識別碼。

使用 web.xml 強制要求登入和管理員權限

如果使用者必須登入才能存取您的網頁,您可以在部署作業描述元 (web.xml 檔案) 中為這些網頁建立安全限制。如果使用者存取設有安全限制的網址,而且使用者沒有登入,App Engine 會自動將使用者重新導向到登入頁面 (進行「Google 帳戶」或 G Suite 驗證),然後在成功登入或註冊之後,將使用者引導回到網址。

安全限制也可要求使用者必須是應用程式的已註冊管理員;也就是使用者必須擁有檢視者、編輯者或擁有者原始角色,或 App Engine 應用程式管理員預先定義的角色。這使得建立網站的管理員專屬部分變得很容易,因為不需要另外實作授權機制。

如要瞭解如何為網址設定安全限制,請參閱部署作業描述元:安全性和驗證中的 web.xml

驗證選項

您的應用程式可以使用以下其中一個選項來驗證使用者:

  • Google 帳戶
  • G Suite 網域上的帳戶

選擇驗證的選項

您建立應用程式之後,可選擇要使用的驗證選項。根據預設,您的應用程式將使用「Google 帳戶」來驗證。如要選擇另一個選項 (例如 G Suite 網域),請前往 Google Cloud Platform 主控台中專案的 [Settings] (設定) 頁面,然後按一下 [Edit] (編輯)。在 [Google authentication] (Google 驗證) 下拉式選單中,選取所需的驗證類型,然後按一下 [Save] (儲存)

登入和登出

應用程式可以偵測使用者是否透過應用程式所選擇的驗證選項登入應用程式。如果使用者未登入,應用程式會將使用者導向到「Google 帳戶」以便登入,或建立新的「Google 帳戶」。應用程式會呼叫 Users API 的方法,取得登入頁面的網址。使用者造訪需要驗證的頁面時,應用程式能將此網址顯示為連結,或發出對於網址的 HTTP 重新導向。

如果應用程式使用「Google 帳戶」或 G Suite 來驗證,使用者登入您的應用程式時,應用程式的名稱會顯示在登入頁面上。顯示的名稱是您在註冊應用程式時指定的應用程式名稱。您可以變更 Google Cloud Platform 主控台中「Credentials」(憑證) 頁面的 [Product name shown to users] (向使用者顯示的產品名稱) 欄位中的應用程式名稱。

使用者一旦登入或建立 Google 帳戶之後,就會重新導向您的應用程式。應用程式將提供重新導向網址,以連結可產生登入網址的方法。

Users API 也提供方法,可產生用來登出應用程式的網址。登出網址會從應用程式取消使用者驗證,然後重新導向回到應用程式的網址,而不顯示任何內容。

在系統提示要登入應用程式,且使用者輸入其帳戶的電子郵件地址和密碼後,使用者才能登入應用程式。就算使用者已經使用其「Google 帳戶」登入其他應用程式也是如此。

存取帳戶資訊

如果使用者已登入應用程式,應用程式可為使用者向應用程式提出的每一項要求,來存取帳戶的電子郵件地址。應用程式也能存取可識別使用者的唯一使用者 ID,就算使用者變更了其帳戶的電子郵件地址也是如此。

應用程式還能偵測目前的使用者是否為管理員。「管理員」使用者是擁有檢視者、編輯者或擁有者原始角色,或 App Engine 應用程式管理員預先定義角色的任何使用者。即使您不驗證其他使用者,也可以使用這項功能建構應用程式的管理功能。Go、Java、PHP 和 Python API 都能將網址輕易設定為「管理員專屬」。

Users 和資料儲存庫

Users 服務 API 可以將目前使用者資訊做為 User 物件傳回。雖然 User 物件可以做為屬性值儲存在資料儲存庫中,但我們強烈建議您避免這麼做,因為這包含電子郵件地址以及使用者的唯一 ID。如果使用者變更了電子郵件地址,但您還是使用先前儲存的 User 來比對新的 User 值,兩者將無法配對。請考慮改為使用「User 使用者 ID 值」做為該使用者的穩定唯一識別碼。

Google 帳戶和開發伺服器

開發伺服器使用虛擬登入畫面模擬「Google 帳戶」系統。當應用程式呼叫 Users API 以取得登入畫面的網址時,API 將傳回特殊的開發伺服器網址,提示使用者輸入電子郵件地址,但不用輸入密碼。您可以在提示下輸入任何電子郵件地址,應用程式的行為會如同您已經以該地址帳戶登入一樣。

虛擬登入畫面中也有核取方塊,顯示虛擬帳戶是否為管理員;也就是該帳戶是否擁有檢視者、編輯者或擁有者原始角色,或 App Engine 應用程式管理員預先定義的角色。若您勾選此核取方塊,應用程式的行為會如同您已經使用管理員帳戶登入一樣。

同樣的,Users API 將傳回登出網址以取消虛擬登入。

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

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

這個網頁
Java 適用的 App Engine 標準環境