本文件將說明如何透過範例網頁應用程式,使用 Google Tasks API 顯示使用者的工作,實作 OAuth 2.0 授權回呼處理常式。範例應用程式會先要求授權存取使用者的 Google Tasks,接著就會在預設工作清單中顯示使用者的工作。
適用對象
本文件適用於熟悉 Java 和 J2EE 網頁應用程式架構的使用者。建議您瞭解 OAuth 2.0 授權流程。
目錄
為了讓範例可完整運作,您必須執行幾個步驟:
- 在 web.xml 檔案中宣告 JAR 對應
- 驗證系統中的使用者,並要求存取其工作的權限
- 從 Google Authorization 端點監聽授權碼
- 交換更新和存取權杖的授權碼
- 讀取並顯示使用者的工作
在 web.xml 檔案中宣告 JAR 對應
我們將在應用程式中使用 2 個 Webhook:
- PrintTasksTitlesServlet (對應至 /):應用程式進入點,用於處理使用者驗證,並顯示使用者的工作
- OAuthCodeCallbackHandlerServlet (對應至 /oauth2callback):OAuth 2.0 回呼,用於處理 OAuth 授權端點的回應
以下是 web.xml 檔案,會將這 2 個 Webhook 對應至應用程式裡的網址:
<?xml version="1.0" encoding="UTF-8"?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <servlet> <servlet-name>PrintTasksTitles</servlet-name> <servlet-class>com.google.oauthsample.PrintTasksTitlesServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>PrintTasksTitles</servlet-name> <url-pattern>/</url-pattern> </servlet-mapping> <servlet> <servlet-name>OAuthCodeCallbackHandlerServlet</servlet-name> <servlet-class>com.google.oauthsample.OAuthCodeCallbackHandlerServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>OAuthCodeCallbackHandlerServlet</servlet-name> <url-pattern>/oauth2callback</url-pattern> </servlet-mapping> </web-app>
驗證系統中的使用者,並要求存取其工作的權限
使用者透過對應至 PrintTaskListsTitlesServlet Webhook 的根網址輸入應用程式。在該 sys 中,系統會執行以下工作:
- 檢查使用者是否已在系統上驗證
- 如果使用者未通過驗證,系統會將其重新導向至驗證頁面
- 如果使用者通過驗證,我們會檢查資料儲存空間中是否已經有更新權杖,這個權杖是由下方的 OAuthTokenDao 處理。如果使用者未儲存任何更新權杖,表示使用者尚未授權應用程式存取工作。在此情況下,系統會將使用者重新導向至 Google 的 OAuth 2.0 授權端點。
package com.google.oauthsample; import ... /** * Simple sample Servlet which will display the tasks in the default task list of the user. */ @SuppressWarnings("serial") public class PrintTasksTitlesServlet extends HttpServlet { /** * The OAuth Token DAO implementation, used to persist the OAuth refresh token. * Consider injecting it instead of using a static initialization. Also we are * using a simple memory implementation as a mock. Change the implementation to * using your database system. */ public static OAuthTokenDao oauthTokenDao = new OAuthTokenDaoMemoryImpl(); public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // Getting the current user // This is using App Engine's User Service but you should replace this to // your own user/login implementation UserService userService = UserServiceFactory.getUserService(); User user = userService.getCurrentUser(); // If the user is not logged-in it is redirected to the login service, then back to this page if (user == null) { resp.sendRedirect(userService.createLoginURL(getFullRequestUrl(req))); return; } // Checking if we already have tokens for this user in store AccessTokenResponse accessTokenResponse = oauthTokenDao.getKeys(user.getEmail()); // If we don't have tokens for this user if (accessTokenResponse == null) { OAuthProperties oauthProperties = new OAuthProperties(); // Redirect to the Google OAuth 2.0 authorization endpoint resp.sendRedirect(new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(), OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties .getScopesAsString()).build()); return; } } /** * Construct the request's URL without the parameter part. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getFullRequestUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = req.getServletPath(); String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); String queryString = (req.getQueryString() == null) ? "" : "?" + req.getQueryString(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo + queryString; } }
注意:上述實作使用部分 App Engine 程式庫,這些程式庫會做為簡化程序使用。如果您正在為其他平台進行開發,您隨時可以重新導入 UserService 介面來處理使用者驗證作業。
應用程式會使用 DAO 保存並存取使用者的授權權杖。下方是這個範例中使用的介面 OAuthTokenDao,以及模擬 (記憶體內) 實作 - OAuthTokenDaoMemoryImpl:
package com.google.oauthsample; import com.google.api.client.auth.oauth2.draft10.AccessTokenResponse; /** * Allows easy storage and access of authorization tokens. */ public interface OAuthTokenDao { /** * Stores the given AccessTokenResponse using the {@code username}, the OAuth * {@code clientID} and the tokens scopes as keys. * * @param tokens The AccessTokenResponse to store * @param userName The userName associated wit the token */ public void saveKeys(AccessTokenResponse tokens, String userName); /** * Returns the AccessTokenResponse stored for the given username, clientId and * scopes. Returns {@code null} if there is no AccessTokenResponse for this * user and scopes. * * @param userName The username of which to get the stored AccessTokenResponse * @return The AccessTokenResponse of the given username */ public AccessTokenResponse getKeys(String userName); }
package com.google.oauthsample; import com.google.api.client.auth.oauth2.draft10.AccessTokenResponse; ... /** * Quick and Dirty memory implementation of {@link OAuthTokenDao} based on * HashMaps. */ public class OAuthTokenDaoMemoryImpl implements OAuthTokenDao { /** Object where all the Tokens will be stored */ private static MaptokenPersistance = new HashMap (); public void saveKeys(AccessTokenResponse tokens, String userName) { tokenPersistance.put(userName, tokens); } public AccessTokenResponse getKeys(String userName) { return tokenPersistance.get(userName); } }
此外,應用程式的 OAuth 2.0 憑證會儲存在屬性檔案中。或者,您也可以直接將它們做為其中一個 Java 類別中的常數,但以下是範例中使用的 OAuthProperties 類別和 oauth.properties 檔案:
package com.google.oauthsample; import ... /** * Object representation of an OAuth properties file. */ public class OAuthProperties { public static final String DEFAULT_OAUTH_PROPERTIES_FILE_NAME = "oauth.properties"; /** The OAuth 2.0 Client ID */ private String clientId; /** The OAuth 2.0 Client Secret */ private String clientSecret; /** The Google APIs scopes to access */ private String scopes; /** * Instantiates a new OauthProperties object reading its values from the * {@code OAUTH_PROPERTIES_FILE_NAME} properties file. * * @throws IOException IF there is an issue reading the {@code propertiesFile} * @throws OauthPropertiesFormatException If the given {@code propertiesFile} * is not of the right format (does not contains the keys {@code * clientId}, {@code clientSecret} and {@code scopes}) */ public OAuthProperties() throws IOException { this(OAuthProperties.class.getResourceAsStream(DEFAULT_OAUTH_PROPERTIES_FILE_NAME)); } /** * Instantiates a new OauthProperties object reading its values from the given * properties file. * * @param propertiesFile the InputStream to read an OAuth Properties file. The * file should contain the keys {@code clientId}, {@code * clientSecret} and {@code scopes} * @throws IOException IF there is an issue reading the {@code propertiesFile} * @throws OAuthPropertiesFormatException If the given {@code propertiesFile} * is not of the right format (does not contains the keys {@code * clientId}, {@code clientSecret} and {@code scopes}) */ public OAuthProperties(InputStream propertiesFile) throws IOException { Properties oauthProperties = new Properties(); oauthProperties.load(propertiesFile); clientId = oauthProperties.getProperty("clientId"); clientSecret = oauthProperties.getProperty("clientSecret"); scopes = oauthProperties.getProperty("scopes"); if ((clientId == null) || (clientSecret == null) || (scopes == null)) { throw new OAuthPropertiesFormatException(); } } /** * @return the clientId */ public String getClientId() { return clientId; } /** * @return the clientSecret */ public String getClientSecret() { return clientSecret; } /** * @return the scopes */ public String getScopesAsString() { return scopes; } /** * Thrown when the OAuth properties file was not at the right format, i.e not * having the right properties names. */ @SuppressWarnings("serial") public class OAuthPropertiesFormatException extends RuntimeException { } }
以下是 oauth.properties 檔案,其中包含您的應用程式授權的 OAuth 2.0 憑證。您必須自行變更以下的值。
# Client ID and secret. They can be found in the APIs console. clientId=1234567890.apps.googleusercontent.com clientSecret=aBcDeFgHiJkLmNoPqRsTuVwXyZ # API scopes. Space separated. scopes=https://www.googleapis.com/auth/tasks
OAuth 2.0 用戶端 ID 和用戶端密鑰會識別您的應用程式,並允許 Tasks API 套用針對應用程式定義的篩選器和配額規則。您可以在 Google API 控制台中找到用戶端 ID 和密鑰。前往控制台後,您必須:
- 建立或選取所需專案。
- 將服務清單中的 Tasks API 狀態切換為「開啟」,即可啟用 Tasks API。
- 如果尚未建立 OAuth 2.0 用戶端 ID,請在「API 存取權」下方建立。
- 請確認專案的 OAuth 2.0 程式碼回呼處理常式網址已在重新導向 URI 中註冊或加入許可清單。舉例來說,在這個範例專案中,如果您的網頁應用程式是由 https://www.example.com 網域提供,您必須註冊 https://www.example.com/oauth2callback。
監聽 Google Authorization 端點的授權碼
如果使用者尚未授權應用程式存取其工作,因而被重新導向至 Google 的 OAuth 2.0 授權端點,則 Google 會顯示授權對話方塊,要求使用者授予應用程式工作存取權:
授予或拒絕存取權後,使用者會重新導向至 OAuth 2.0 程式碼回呼處理常式,而這個處理常式在建立 Google 授權網址時指定為重新導向/回呼:
new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(), OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties .getScopesAsString()).build()
OAuth 2.0 程式碼回呼處理常式 OAuthCodeCallbackHandlerServlet - 會處理 Google OAuth 2.0 端點的重新導向。可處理的案例有 2 種:
- 使用者已授予存取權:剖析要求,以便從網址參數取得 OAuth 2.0 程式碼
- 使用者已拒絕存取:向使用者顯示訊息
package com.google.oauthsample; import ... /** * Servlet handling the OAuth callback from the authentication service. We are * retrieving the OAuth code, then exchanging it for a refresh and an access * token and saving it. */ @SuppressWarnings("serial") public class OAuthCodeCallbackHandlerServlet extends HttpServlet { /** The name of the Oauth code URL parameter */ public static final String CODE_URL_PARAM_NAME = "code"; /** The name of the OAuth error URL parameter */ public static final String ERROR_URL_PARAM_NAME = "error"; /** The URL suffix of the servlet */ public static final String URL_MAPPING = "/oauth2callback"; public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // Getting the "error" URL parameter String[] error = req.getParameterValues(ERROR_URL_PARAM_NAME); // Checking if there was an error such as the user denied access if (error != null && error.length > 0) { resp.sendError(HttpServletResponse.SC_NOT_ACCEPTABLE, "There was an error: \""+error[0]+"\"."); return; } // Getting the "code" URL parameter String[] code = req.getParameterValues(CODE_URL_PARAM_NAME); // Checking conditions on the "code" URL parameter if (code == null || code.length == 0) { resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "The \"code\" URL parameter is missing"); return; } } /** * Construct the OAuth code callback handler URL. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getOAuthCodeCallbackHandlerUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = URL_MAPPING; String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo; } }
使用授權碼交換更新和存取權杖
接著,OAuthCodeCallbackHandlerServlet 會交換 Auth 2.0 程式碼來重新整理重新整理和存取權杖,然後保留在資料儲存庫中,然後將使用者重新導向回 OAuthCodeCallbackHandlerServlet 網址:
在下方檔案中加入的程式碼經過醒目顯示,現有的程式碼會顯示為灰色。
package com.google.oauthsample; import ... /** * Servlet handling the OAuth callback from the authentication service. We are * retrieving the OAuth code, then exchanging it for a refresh and an access * token and saving it. */ @SuppressWarnings("serial") public class OAuthCodeCallbackHandlerServlet extends HttpServlet { /** The name of the Oauth code URL parameter */ public static final String CODE_URL_PARAM_NAME = "code"; /** The name of the OAuth error URL parameter */ public static final String ERROR_URL_PARAM_NAME = "error"; /** The URL suffix of the servlet */ public static final String URL_MAPPING = "/oauth2callback";/** 處理回呼後,系統重新導向的網址。建議 * 先儲存在 Cookie 中,再將使用者重新導向至 Google * 授權網址 (如有多個可將使用者重新導向至的網址)。*/ 公開靜態最終字串 REDIRECT_URL = "/"; /** OAuth 權杖 DAO 實作。請考慮將其插入,而不要使用 * 靜態初始化。此外,我們也會使用簡單的記憶體實作 * 做為模擬。將實作變更為使用資料庫系統。*/ public static OAuthTokenDao oauthTokenDao = new OAuthTokenDaoMemoryImpl();public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // Getting the "error" URL parameter String[] error = req.getParameterValues(ERROR_URL_PARAM_NAME); // Checking if there was an error such as the user denied access if (error != null && error.length > 0) { resp.sendError(HttpServletResponse.SC_NOT_ACCEPTABLE, "There was an error: \""+error[0]+"\"."); return; } // Getting the "code" URL parameter String[] code = req.getParameterValues(CODE_URL_PARAM_NAME); // Checking conditions on the "code" URL parameter if (code == null || code.length == 0) { resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "The \"code\" URL parameter is missing"); return; }// 建構傳入要求網址 String requestUrl = getOAuthCodeCallbackHandlerUrl(req); // Exchange the code for OAuthTokens(getAccessTokenResponse =exchangeCodeFor the current userUrlResponse})。/** * Construct the OAuth code callback handler URL. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getOAuthCodeCallbackHandlerUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = URL_MAPPING; String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo; }* * @param code The 程式碼從授權服務中取得OAuthCodeCallbackHandler 要求.java 檔案注意:上述實作使用部分 App Engine 程式庫,這些程式庫會做為簡化程序使用。如果您正在為其他平台進行開發,您隨時可以重新導入 UserService 介面來處理使用者驗證作業。
讀取使用者的工作並顯示其
使用者已授權應用程式存取其工作。應用程式具有重新整理權杖,可透過 OAuthTokenDao 存取資料儲存庫。PrintTaskListsTitlesServlet Webhook 現在可以使用這些符記存取使用者的工作並顯示其:
在下方檔案中加入的程式碼經過醒目顯示,現有的程式碼會顯示為灰色。
package com.google.oauthsample; import ... /** * Simple sample Servlet which will display the tasks in the default task list of the user. */ @SuppressWarnings("serial") public class PrintTasksTitlesServlet extends HttpServlet { /** * The OAuth Token DAO implementation, used to persist the OAuth refresh token. * Consider injecting it instead of using a static initialization. Also we are * using a simple memory implementation as a mock. Change the implementation to * using your database system. */ public static OAuthTokenDao oauthTokenDao = new OAuthTokenDaoMemoryImpl(); public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // Getting the current user // This is using App Engine's User Service but you should replace this to // your own user/login implementation UserService userService = UserServiceFactory.getUserService(); User user = userService.getCurrentUser(); // If the user is not logged-in it is redirected to the login service, then back to this page if (user == null) { resp.sendRedirect(userService.createLoginURL(getFullRequestUrl(req))); return; } // Checking if we already have tokens for this user in store AccessTokenResponse accessTokenResponse = oauthTokenDao.getKeys(user.getEmail()); // If we don't have tokens for this user if (accessTokenResponse == null) { OAuthProperties oauthProperties = new OAuthProperties(); // Redirect to the Google OAuth 2.0 authorization endpoint resp.sendRedirect(new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(), OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties .getScopesAsString()).build()); return; }// 列印使用者的工作,並在回應中列出工作 resp.setContentType("text/plain"); resp.getWriter().append("Task Lists title for user " + user.getEmail() + ":\n\n"); printTasksTitles(accessTokenResponse, resp.getWriter());} /** * Construct the request's URL without the parameter part. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getFullRequestUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = req.getServletPath(); String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); String queryString = (req.getQueryString() == null) ? "" : "?" + req.getQueryString(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo + queryString; }/** * 使用 Google Tasks 使用者的預設工作。} /** * Construct the request's URL without the parameter part. * * @param req the HttpRequest object * @return The constructed request's URL */ public static String getFullRequestUrl(HttpServletRequest req) { String scheme = req.getScheme() + "://"; String serverName = req.getServerName(); String serverPort = (req.getServerPort() == 80) ? "" : ":" + req.getServerPort(); String contextPath = req.getContextPath(); String servletPath = req.getServletPath(); String pathInfo = (req.getPathInfo() == null) ? "" : req.getPathInfo(); String queryString = (req.getQueryString() == null) ? "" : "?" + req.getQueryString(); return scheme + serverName + serverPort + contextPath + servletPath + pathInfo + queryString; }* * @param accessTokenResponse.OAuth 2.0 AccessTokenResponse 物件 * 包含存取權杖和更新權杖。 * @param 會輸出輸出串流寫入器,並在其中記錄工作在預設工作清單中列出標題 * @return A 列出使用者的工作標題。 * @throws IOException */ public void printTasksTitles(AccessTokenResponse accessTokenResponse, Writer output) throws IOException { // 初始化工作服務 HttpTransportTransport = new NetHttpTransport(); JsonFactory jsonFactory = new JacksonFactory(); OAuthTasks IOException */ public void printTasksTitles(AccessTokenResponse accessTokenResponse, Writer output) throws IOException { // 初始化工作服務 HttpTransportTransport = new NetHttpTransport(); OAuthProperties jsonFactory = new JacksonFactory(); OAuthTasks 二對指令} 工作PrintTasksTitlestf.java 檔案使用者會看到相關工作:
使用者的工作應用程式範例
您可在這裡下載這個範例應用程式的程式碼。歡迎查看。