Trình xử lý gọi lại uỷ quyền bản dựng

Tài liệu này giải thích cách triển khai trình xử lý gọi lại uỷ quyền OAuth 2.0 bằng dịch vụ Java thông qua một ứng dụng web mẫu sẽ hiển thị công việc của người dùng bằng API Google Tasks. Trước tiên, ứng dụng mẫu sẽ yêu cầu cấp quyền truy cập vào Google Tasks của người dùng, sau đó sẽ hiển thị công việc của người dùng trong danh sách công việc mặc định.

Đối tượng

Tài liệu này dành riêng cho những người quen với kiến trúc ứng dụng web Java và J2EE. Một số kiến thức về quy trình uỷ quyền OAuth 2.0 được đề xuất.

Nội dung

Để có một mẫu hoạt động đầy đủ như vậy, bạn cần thực hiện một số bước sau:

• Khai báo ánh xạ servlet trong tệp web.xml
• Xác thực người dùng trên hệ thống của bạn và yêu cầu uỷ quyền để truy cập vào Tasks
• Nghe mã uỷ quyền từ điểm cuối Uỷ quyền của Google
• Đổi mã uỷ quyền lấy mã thông báo truy cập và làm mới
• Đọc các công việc của người dùng và hiển thị các công việc đó

Khai báo liên kết servlet trong tệp web.xml

Chúng ta sẽ sử dụng 2 servlet trong ứng dụng của mình:

• PrintTasksTitlesServlet (được ánh xạ tới /): Điểm truy cập của ứng dụng sẽ xử lý quy trình xác thực người dùng và sẽ hiển thị các công việc của người dùng
• OAuthCodeCallbackHandlerServlet (được ánh xạ đến /oauth2callback): Lệnh gọi lại OAuth 2.0 xử lý phản hồi từ điểm cuối uỷ quyền OAuth

Dưới đây là tệp web.xml ánh xạ 2 servlet này với các URL trong ứng dụng của chúng ta:

<?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>

Tệp /WEB-INF/web.xml

Xác thực người dùng trên hệ thống của bạn và yêu cầu uỷ quyền để truy cập vào các nhiệm vụ của hệ thống

Người dùng truy cập ứng dụng thông qua thư mục gốc '/' URL được liên kết với servlet PrintTaskListsTitlesServlet. Trong servlet đó, các tác vụ sau được thực hiện:

• Kiểm tra xem người dùng có được xác thực trên hệ thống hay không
• Nếu người dùng không được xác thực, họ sẽ được chuyển hướng đến trang xác thực
• Nếu người dùng được xác thực, chúng tôi sẽ kiểm tra xem đã có mã làm mới trong bộ nhớ dữ liệu hay chưa – do OAuthTokenDao xử lý bên dưới. Nếu không có mã làm mới nào trong cửa hàng cho người dùng thì điều này có nghĩa là người dùng chưa cấp quyền cho ứng dụng truy cập vào các tác vụ của ứng dụng. Trong trường hợp đó, người dùng sẽ được chuyển hướng đến điểm cuối Uỷ quyền OAuth 2.0 của Google.

Dưới đây là một cách để triển khai việc này:

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;
  }
}

Tệp PrintTasksTitlesServlet.java

Lưu ý: Cách triển khai ở trên sử dụng một số thư viện App Engine. Các thư viện này được dùng để đơn giản hoá. Nếu bạn đang phát triển cho một nền tảng khác, vui lòng triển khai lại giao diện UserService để xử lý việc xác thực người dùng.

Ứng dụng dùng một DAO để duy trì và truy cập vào mã thông báo uỷ quyền của người dùng. Dưới đây là giao diện – OAuthTokenDao – và triển khai mô phỏng (trong bộ nhớ) – OAuthTokenDaoMemoryImpl – được sử dụng trong mẫu này:

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);
}

Tệp OAuthTokenDao.java

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 Map

Tệp OAuthTokenDaoMemoryImpl.java

Ngoài ra, thông tin đăng nhập OAuth 2.0 cho ứng dụng cũng được lưu trữ trong tệp thuộc tính. Ngoài ra, bạn chỉ cần có chúng như một hằng số ở đâu đó trong một trong các lớp java của mình, mặc dù ở đây là lớp OAuthProperties và tệp oauth.properties đang được sử dụng trong mẫu:

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 {
  }
}

Tệp OAuthProperties.java

Dưới đây là tệp oauth.properties chứa thông tin đăng nhập OAuth 2.0 cho ứng dụng của bạn. Bạn cần phải tự thay đổi các giá trị bên dưới.

# 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

Tệp oauth.properties

Mã ứng dụng khách OAuth 2.0 và Mật khẩu ứng dụng khách xác định ứng dụng của bạn và cho phép API Tasks áp dụng các bộ lọc và quy tắc hạn mức được xác định cho ứng dụng của bạn. Bạn có thể tìm thấy mã ứng dụng khách và khoá bí mật trong Bảng điều khiển API của Google. Khi truy cập vào bảng điều khiển, bạn sẽ phải:

• Tạo hoặc chọn một dự án.
• Bật API Tasks bằng cách chuyển trạng thái của API Tasks sang trạng thái BẬT trong danh sách dịch vụ.
• Trong phần Quyền truy cập API, hãy tạo một mã ứng dụng khách OAuth 2.0 nếu bạn chưa tạo.
• Đảm bảo rằng URL trình xử lý gọi lại mã OAuth 2.0 của dự án đã được đăng ký/đưa vào danh sách cho phép trong phần URI chuyển hướng. Ví dụ: trong dự án mẫu này, bạn sẽ phải đăng ký https://www.example.com/oauth2callback nếu ứng dụng web của bạn được phân phối từ miền https://www.example.com/oauth2callback.

URI chuyển hướng trong Bảng điều khiển API

Lắng nghe Mã uỷ quyền từ điểm cuối Uỷ quyền của Google

Trong trường hợp người dùng chưa cho phép ứng dụng truy cập vào các tác vụ của mình và do đó đã được chuyển hướng đến điểm cuối Uỷ quyền OAuth 2.0 của Google, người dùng sẽ thấy hộp thoại uỷ quyền từ Google yêu cầu người dùng cấp cho ứng dụng của bạn quyền truy cập vào các tác vụ của Google:

Hộp thoại uỷ quyền của Google

Sau khi cấp hoặc từ chối quyền truy cập, người dùng sẽ được chuyển hướng trở lại trình xử lý gọi lại mã OAuth 2.0 đã được chỉ định làm lệnh chuyển hướng/lệnh gọi lại khi tạo URL uỷ quyền của Google:

new GoogleAuthorizationRequestUrl(oauthProperties.getClientId(),
      OAuthCodeCallbackHandlerServlet.getOAuthCodeCallbackHandlerUrl(req), oauthProperties
          .getScopesAsString()).build()

Trình xử lý gọi lại mã OAuth 2.0 - OAuthCodeCallbackHandlerServlet – xử lý chuyển hướng từ điểm cuối Google OAuth 2.0. Có 2 trường hợp cần xử lý:

• Người dùng đã cấp quyền truy cập: phân tích cú pháp yêu cầu lấy mã OAuth 2.0 từ các tham số URL
• Người dùng đã từ chối truy cập: hiển thị thông báo cho người dùng

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;
  }
}

Tệp OAuthCodeCallbackHandlerServlet.java

Trao đổi mã uỷ quyền để lấy mã thông báo làm mới và truy cập

Sau đó, OAuthCodeCallbackHandlerServlet sẽ trao đổi mã Auth 2.0 để có mã thông báo truy cập và làm mới, duy trì mã đó trong kho dữ liệu và chuyển hướng người dùng quay lại URL PrintTaskListsTitlesServlet:

Mã đã thêm vào tệp bên dưới được làm nổi bật theo cú pháp, mã đã có sẵn có màu xám.

  /** URL để chuyển hướng người dùng đến sau khi xử lý lệnh gọi lại. Cân nhắc
   * lưu mã này vào cookie trước khi chuyển hướng người dùng đến Google
   * URL uỷ quyền nếu bạn có nhiều URL hợp lệ để chuyển hướng người dùng đến. */
  Public static last string REDIRECT_URL = "/";

  /** Triển khai DAO của mã thông báo OAuth. Hãy cân nhắc việc chèn ngôn ngữ này thay vì sử dụng
   * một quá trình khởi tạo tĩnh. Ngoài ra, chúng ta đang sử dụng
cách triển khai bộ nhớ đơn giản
   * để mô phỏng. Thay đổi phương thức triển khai thành sử dụng hệ thống cơ sở dữ liệu. */
  công khai tĩnh OAuthTokenDao oauthTokenDao = mới OAuthTokenDaoMemoryImpl();


    // Tạo URL yêu cầu đến
    Chuỗi requestUrl = getOAuthCodeCallbackHandlerUrl(req);

    // Trao đổi mã để lấy mã thông báo OAuth
    AccessTokenResponse accessTokenResponse = ExchangeCodeForAccessAndRefreshTokens(mã[0],
        requestUrl);

    // Lấy người dùng hiện tại
    // Điều này đang sử dụng Dịch vụ người dùng của App Engine nhưng bạn nên thay thế dịch vụ này thành
    // triển khai người dùng/đăng nhập của riêng bạn
    UserService userService = UserServiceFactory.getUserService();
    Chuỗi email = userService.getCurrentUser().getEmail();

    // Lưu mã thông báo
    oauthTokenDao.saveKeys(accessTokenResponse, email);

    resp.sendRedirect(REDIRECT_URL);
  }


  /**
   * Trao đổi mã đã cho cho một sàn giao dịch và mã làm mới.
   *
   * @param mã Mã nhận lại từ dịch vụ uỷ quyền
   * @param currentUrl URL của lệnh gọi lại
   * @param oauthProperties Đối tượng chứa cấu hình OAuth
   * @return Đối tượng chứa cả mã truy cập và mã làm mới
   * @throw IOException
   */
  AccessTokenResponse ExchangeCodeForAccessAndRefreshTokens(Mã chuỗi, Chuỗi currentUrl)
      throws IOException {

    HttpTransport httpTransport = mới NetHttpTransport();
    JacksonFactory jsonFactory = new JacksonFactory();

    // Đang tải tệp cấu hình OAuth
    OAuthProperties oauthProperties = mới OAuthProperties(); chưa

    trả về Googleuỷ quyềnCode Grants mới(httpTransport, jsonFactory, oauthProperties) mới
        .getClientId(), oauthProperties.getClientSecret(), mã, currentUrl).implementation();
  }
}

Tệp OAuthCodeCallbackHandlerServlet.java


Lưu ý: Cách triển khai ở trên sử dụng một số thư viện App Engine. Các thư viện này được dùng để đơn giản hoá. Nếu bạn đang phát triển cho một nền tảng khác, vui lòng triển khai lại giao diện UserService để xử lý việc xác thực người dùng.


Đọc các công việc của người dùng và hiển thị các công việc đó


Người dùng đã cấp cho ứng dụng quyền truy cập vào các tác vụ của ứng dụng này. Ứng dụng có mã làm mới được lưu trong kho dữ liệu có thể truy cập được thông qua OAuthTokenDao. Hiện tại, servlet PrintTaskListsTitlesServlet có thể sử dụng các mã thông báo này để truy cập vào các tác vụ của người dùng và hiển thị chúng:


Mã đã thêm vào tệp bên dưới được làm nổi bật theo cú pháp, mã đã có sẵn có màu xám.