Sử dụng OAuth với Google Data API

Eric Bidelman, Nhóm API dữ liệu của Google
Tháng 9 năm 2008

Giới thiệu

Đây là thời điểm thú vị đối với các nhà phát triển. Chúng tôi nhận thấy có một số tiêu chuẩn mở đang được áp dụng trên web. Như bạn đã biết, Google luôn là một người ủng hộ nhiệt tình các tiêu chuẩn và việc thúc đẩy cộng đồng nguồn mở.

Gần đây, tất cả Google Data API đều hỗ trợ OAuth, một giao thức mở nhằm chuẩn hoá cách các ứng dụng trên máy tính và web truy cập vào dữ liệu riêng tư của người dùng. OAuth cung cấp một phương thức để thực hiện xác thực API theo cách tiêu chuẩn và an toàn. Là lập trình viên, chúng ta được dạy cách sử dụng lại mã bất cứ khi nào có thể. OAuth sẽ giúp nhà phát triển giảm lượng mã trùng lặp mà họ viết và giúp họ dễ dàng tạo các công cụ hoạt động với nhiều dịch vụ của nhiều nhà cung cấp khác nhau.

Đối tượng

Bài viết này giả định rằng bạn đã quen thuộc với một hoặc nhiều API dữ liệu của Google nhưng không nhất thiết phải biết các khái niệm đằng sau OAuth. Nếu bạn mới bắt đầu hoặc chỉ tò mò về OAuth, thì đây chính là nơi bạn cần đến. Bài viết này sẽ cung cấp cho bạn kiến thức cơ bản về các khái niệm này. Tôi cũng sẽ thảo luận về các chi tiết trong việc triển khai OAuth của Google.

Tài liệu này cũng dành cho những nhà phát triển đã quen với việc sử dụng AuthSub, đặc biệt là ở chế độ đã đăng ký với chế độ bảo mật nâng cao. Trong quá trình này, tôi sẽ cố gắng nêu bật những điểm tương đồng và khác biệt giữa hai giao thức này. Nếu có các ứng dụng sử dụng AuthSub, bạn có thể dùng thông tin này để di chuyển sang OAuth, một giao thức hiện đại và cởi mở hơn.

Một số thuật ngữ

Để hiểu về OAuth, bạn cần hiểu rõ thuật ngữ của giao thức này. Quy cách OAuth và tài liệu Xác thực OAuth cho ứng dụng web của Google phụ thuộc nhiều vào một số định nghĩa nhất định, vì vậy, hãy làm rõ ý nghĩa của từng định nghĩa trong bối cảnh triển khai OAuth của Google.

  1. "Quy trình OAuth"

    Thuật ngữ không chính thức của tôi để mô tả toàn bộ quy trình xác thực/uỷ quyền OAuth.

  2. (OAuth) Mã thông báo yêu cầu

    Một mã thông báo ban đầu cho phép Google biết rằng ứng dụng của bạn đang yêu cầu quyền truy cập vào một trong các API Dữ liệu của Google. Bước thứ hai của quy trình OAuth là người dùng tự cấp quyền truy cập vào dữ liệu của họ. Nếu bước này thành công, mã thông báo yêu cầu sẽ được uỷ quyền.

  3. (OAuth) Mã truy cập

    Bước cuối cùng của quy trình này là trao đổi mã thông báo yêu cầu được uỷ quyền để lấy mã truy cập. Sau khi ứng dụng của bạn có mã thông báo này, người dùng sẽ không cần thực hiện lại quy trình OAuth, trừ phi mã thông báo bị thu hồi.

    Tương tự như AuthSub:
    Mã truy cập OAuth cũng giống như mã thông báo phiên AuthSub bảo mật.

  4. (OAuth) Điểm cuối

    Đây là những URI cần thiết để xác thực một ứng dụng và lấy mã truy cập. Có tổng cộng 3 tham số, mỗi tham số cho một bước trong quy trình OAuth. Các điểm cuối OAuth của Google là:

    Lấy mã thông báo yêu cầu:https://www.google.com/accounts/OAuthGetRequestToken
    Uỷ quyền cho mã thông báo yêu cầu:https://www.google.com/accounts/OAuthAuthorizeToken
    Nâng cấp lên mã truy cập:https://www.google.com/accounts/OAuthGetAccessToken

    Tương tự như AuthSub:
    Việc trao đổi mã thông báo yêu cầu được uỷ quyền lấy mã truy cập tương tự như việc nâng cấp mã thông báo AuthSub dùng một lần thành mã thông báo phiên hoạt động dài hạn tại https://www.google.com/accounts/AuthSubRequestToken và https://www.google.com/accounts/AuthSubSessionToken, tương ứng. Điểm khác biệt là AuthSub không có khái niệm về mã thông báo yêu cầu ban đầu. Thay vào đó, người dùng bắt đầu quy trình mã thông báo từ trang uỷ quyền AuthSubRequestToken.

  5. (OAuth) Nhà cung cấp dịch vụ

    Trong trường hợp Google Data API, nhà cung cấp này là Google. Nhìn chung, nhà cung cấp dịch vụ được dùng để mô tả trang web hoặc dịch vụ web cung cấp các điểm cuối OAuth. MySpace là một ví dụ khác về nhà cung cấp dịch vụ OAuth.

  6. (OAuth) Người dùng

    Chương trình yêu cầu quyền truy cập vào dữ liệu của người dùng (tức là ứng dụng của bạn). Giao thức OAuth có tính linh hoạt vì cho phép nhiều loại ứng dụng (web, đã cài đặt, máy tính, thiết bị di động).

Lưu ý: Mặc dù giao thức OAuth hỗ trợ trường hợp sử dụng ứng dụng trên máy tính/đã cài đặt, nhưng Google chỉ hỗ trợ OAuth cho các ứng dụng web.

Bắt đầu

Đăng ký

Bạn cần thiết lập một số ít thông tin trước khi có thể bắt đầu sử dụng OAuth với Google Data API. Vì tất cả các yêu cầu OAuth đều phải được ký bằng chữ ký số, nên trước tiên, bạn cần đăng ký miền và tải một chứng chỉ công khai lên Google. Hãy xem phần Đăng ký cho các ứng dụng dựa trên web và Tạo khoá và chứng chỉ để sử dụng với chế độ đã đăng ký để biết thêm thông tin về cách thực hiện.

Yêu cầu ký

Sau khi đăng ký miền, bạn có thể bắt đầu ký các yêu cầu. Một trong những khái niệm khó nhất của OAuth là cách tạo đúng oauth_signature và khái niệm về chuỗi cơ sở chữ ký. Chuỗi cơ sở là dữ liệu mà bạn ký bằng khoá riêng tư (bằng cách sử dụng RSA_SHA1). Kết quả là giá trị bạn đặt cho oauth_signature.

Ví dụ về yêu cầu

GET danh sách Lịch Google của người dùng tại http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

Định dạng chuỗi cơ sở base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Ví dụ về chuỗi cơ sở GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Ví dụ về yêu cầu HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Lưu ý: Đây chỉ là hình ảnh minh hoạ. oauth_signature của bạn sẽ dài hơn nhiều.

Lưu ý về chuỗi cơ sở:

  • Tham số truy vấn orderby=starttime được sắp xếp cùng với các tham số oauth_* còn lại theo thứ tự giá trị byte từ vựng.
  • Chuỗi này cũng không chứa ký tự "?".
  • Phần base-http-request-url chỉ chứa URL cơ sở được mã hoá cho URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • oauth_token được mã hoá URL hai lần.

Lưu ý về tiêu đề Authorization:

  • Thứ tự của các tham số oauth_* không quan trọng trong tiêu đề Authorization.
  • Tiêu đề không bao gồm orderby=starttime như chuỗi cơ sở. Tham số truy vấn đó được duy trì trong URL yêu cầu.

Để biết thêm thông tin về cách ký yêu cầu bằng OAuth, hãy xem phần Ký yêu cầu OAuth.

Điểm khác biệt so với AuthSub:
Để so sánh, đây là ví dụ tương tự khi sử dụng AuthSub bảo mật:

Định dạng chuỗi cơ sở base_string = http-method http-request-URL timestamp nonce
Ví dụ về chuỗi cơ sở 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Ví dụ về yêu cầu HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Để biết thêm thông tin về cách ký yêu cầu bằng AuthSub, hãy xem phần Ký yêu cầu AuthSub.

Công cụ OAuth Playground

Mục đích

Một số người dùng cho rằng OAuth có đường cong học tập dốc. So với các API xác thực khác của Google, tôi đồng ý. Lợi ích của OAuth sẽ rõ ràng khi bạn mở rộng ứng dụng để sử dụng các dịch vụ khác (không phải của Google). Việc viết một đoạn mã xác thực duy nhất hoạt động trên nhiều nhà cung cấp dịch vụ và API của họ nghe có vẻ khá ổn đối với tôi. Bạn sẽ cảm ơn chính mình sau này vì đã tìm hiểu giao thức này ngay từ bây giờ.

OAuth Playground là một công cụ mà tôi tạo ra để giúp các nhà phát triển giải quyết những vấn đề về OAuth. Bạn có thể sử dụng Playground để gỡ lỗi, kiểm tra quá trình triển khai của riêng bạn hoặc thử nghiệm với Google Data API.

Tính năng này có công dụng gì?

  1. Minh hoạ quy trình xác thực OAuth: tìm nạp mã thông báo yêu cầu, uỷ quyền mã thông báo và nâng cấp mã thông báo đó thành mã thông báo truy cập.
  2. Hiển thị chuỗi cơ sở chữ ký chính xác cho mỗi yêu cầu.
  3. Hiển thị tiêu đề Authorization chính xác cho mỗi yêu cầu.
  4. Minh hoạ cách sử dụng oauth_token để tương tác với một nguồn cấp dữ liệu đã xác thực của Google. Bạn có thể GET/POST/PUT/DELETE dữ liệu.
  5. Xem nguồn cấp dữ liệu đã xác thực ngay trong trình duyệt.
  6. Cho phép bạn kiểm thử oauth_consumer_key (miền đã đăng ký) và khoá riêng tư của riêng mình.
  7. Khám phá những dịch vụ Nguồn cấp dữ liệu của Google mà oauth_token có thể sử dụng.

Chạy bản minh hoạ

Bước 1: Chọn(các) phạm vi

Trước tiên, hãy quyết định bạn muốn sử dụng API nào bằng cách chọn một hoặc nhiều phạm vi. Trong bản minh hoạ này, tôi đang yêu cầu một mã thông báo sẽ hoạt động với Blogger và Danh bạ Google.

Tương tự như AuthSub:
AuthSub cũng yêu cầu tham số scope để kiểm soát phạm vi dữ liệu mà mã thông báo có thể truy cập. Google đã triển khai tham số này theo đề xuất trong thông số kỹ thuật OAuth.

Bước 2: Sửa đổi các thông số và chế độ cài đặt OAuth

Hiện tại, đừng sửa đổi bất kỳ chế độ cài đặt nào trong hộp "Sửa đổi các thông số OAuth". Sau đó, bạn có thể kiểm thử bằng khoá riêng tư của chính mình bằng cách thay đổi oauth_consumer_key thành miền đã đăng ký và nhập khoá riêng tư bằng cách nhấp vào "sử dụng khoá riêng tư của riêng bạn". Vui lòng chỉ sử dụng khoá riêng tư TEST.

Lưu ý: oauth_signature_method và oauth_consumer_key là những trường duy nhất có thể chỉnh sửa tại đây. oauth_timestamp, oauth_nonce và oauth_token sẽ được tạo tự động cho bạn.

Ngoài RSA-SHA1, bạn có thể chọn dùng HMAC-SHA1 cho oauth_signature_method. Trong trường hợp đó, Playground sẽ hiển thị các hộp bổ sung mà bạn cần nhập oauth_consumer_key và khoá bí mật của người dùng. Bạn có thể tìm thấy các giá trị này trên trang https://www.google.com/accounts/ManageDomains cho miền đã đăng ký của mình.

Điểm khác biệt so với AuthSub:
Trong AuthSub an toàn, không có tham số nào để đặt tên miền một cách rõ ràng. Miền được đưa vào dưới dạng một phần của tham số URL next. OAuth có một tham số như vậy: oauth_consumer_key. Đặt miền đó thành miền đã đăng ký của bạn.

Bước 3 – 5: Lấy mã truy cập

Có 3 bước để lấy mã truy cập OAuth. Bước đầu tiên là truy xuất mã thông báo yêu cầu. Điều này giúp Google biết rằng ứng dụng của bạn đang bắt đầu quy trình OAuth.

Trước tiên, hãy nhấp vào nút "Request token" (Yêu cầu mã thông báo) trong hộp "Get the Token" (Nhận mã thông báo).

Một số trường sẽ được điền sẵn dữ liệu.

  • "Chuỗi cơ sở chữ ký" cho biết dạng thức phù hợp của chuỗi cơ sở dùng để tạo tham số oauth_signature.
  • "Tiêu đề uỷ quyền" cho biết tiêu đề Authorization tương ứng cho yêu cầu.
  • Hộp "Sửa đổi các tham số OAuth" chứa các giá trị oauth_nonce và oauth_timestamp được gửi trong yêu cầu.
  • Đầu vào oauth_token được điền sẵn bằng giá trị tương ứng được trả về trong phần nội dung phản hồi. Playground cũng cho biết loại oauth_token mà chúng ta hiện có. Hiện tại, đây là mã thông báo yêu cầu.

Tiếp theo, hãy nhấp vào nút "Uỷ quyền" trong hộp "Nhận mã thông báo".

Trên trang uỷ quyền này, hãy nhấp vào nút "Cấp quyền truy cập" để uỷ quyền mã thông báo yêu cầu và được chuyển hướng trở lại OAuth Playground.

Tương tự như AuthSub:
Trang uỷ quyền này giống với AuthSub.

Điểm khác biệt so với AuthSub:
Tham số URL next của AuthSub tương tự như tham số oauth_callback. Điểm khác biệt là trong OAuth, oauth_callback là không bắt buộc. Sau khi người dùng nhấp vào nút "Cấp quyền truy cập", mã thông báo yêu cầu sẽ được uỷ quyền và quá trình nâng cấp mã thông báo lên https://www.google.com/accounts/OAuthGetAccessToken có thể được thực hiện không đồng bộ.

Lưu ý: Bạn nên chỉ định URL oauth_callback nếu đang viết một ứng dụng web vì URL này mang lại trải nghiệm người dùng tốt hơn.

Cuối cùng, hãy nhấp vào nút "Mã truy cập" trong hộp "Lấy mã".

Thao tác này sẽ nâng cấp mã thông báo yêu cầu được uỷ quyền (như được ghi chú bằng nhãn "mã truy cập" màu đỏ).

Nếu bạn muốn tìm nạp một mã thông báo mới, hãy nhấp vào "bắt đầu lại" để bắt đầu lại quy trình OAuth.

Giờ đây, chúng ta có thể làm một việc thú vị!

Sử dụng mã truy cập

Giờ đây, bạn đã sẵn sàng truy vấn nguồn cấp dữ liệu, chèn, cập nhật hoặc xoá dữ liệu. Hãy cẩn thận khi thực hiện 3 phương thức HTTP cuối cùng này vì bạn đang làm việc với dữ liệu thực của mình!

Lưu ý: Để khám phá những nguồn cấp dữ liệu có sẵn cho mã truy cập của bạn, hãy nhấp vào nút "nguồn cấp dữ liệu có sẵn".

Sau đây là một ví dụ về cụm từ tìm kiếm: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Ví dụ này trả về không quá 3 bài đăng trên một blog cụ thể. Bạn cũng có thể xem trực tiếp nguồn cấp dữ liệu/mục nhập được trả về trong trình duyệt bằng cách nhấp vào đường liên kết "Xem trong trình duyệt" bên dưới vùng được đánh dấu cú pháp.

Ví dụ: Cách cập nhật bài đăng

  1. Tìm phần tử <link> có biểu tượng rel="edit" trong bài đăng mà bạn muốn cập nhật. Nội dung sẽ có dạng như sau: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    Dán URL href vào ô nhập "Nhập nguồn cấp dữ liệu Google".

  2. Sao chép XML của mục hiện có bằng cách nhấp vào "view plain" (xem văn bản thuần tuý) ở đầu bảng điều khiển được đánh dấu cú pháp. Chỉ sao chép nội dung phản hồi, không sao chép tiêu đề.
  3. Thay đổi trình đơn thả xuống phương thức HTTP thành PUT.
  4. Nhấp vào "enter post data" (nhập dữ liệu bài đăng) bên dưới trình đơn thả xuống đó rồi dán XML <entry> vào cửa sổ bật lên.
  5. Nhấp vào nút "thực thi".

Máy chủ sẽ phản hồi bằng 200 OK.

Lưu ý: Thay vì sao chép đường liên kết edit theo cách thủ công, hãy bỏ đánh dấu hộp đánh dấu "Cú pháp nổi bật?". Sau khi truy vấn, bạn sẽ có thể nhấp vào các đường liên kết trong phần nội dung phản hồi XML.

Kết luận

Các công nghệ như Giao thức xuất bản Atom/AtomPub (giao thức cơ bản của API Dữ liệu của Google) và OAuth giúp thúc đẩy sự phát triển của web. Khi ngày càng nhiều trang web bắt đầu áp dụng các tiêu chuẩn này, chúng ta, những nhà phát triển, sẽ là người hưởng lợi. Việc tạo ra một ứng dụng đột phá bỗng trở nên dễ dàng hơn.

Nếu bạn có câu hỏi hoặc nhận xét về OAuth Playground hoặc việc sử dụng OAuth với các API của Google, vui lòng truy cập vào Diễn đàn hỗ trợ API G Suite và API Marketplace.

Tài nguyên