Sử dụng OAuth với API Dữ liệu của Google

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ị cho các nhà phát triển. Chúng tôi bắt đầu thấy một số tiêu chuẩn mở đang được áp dụng trên web và như bạn đã biết, Google luôn là một người hâm mộ tiêu chuẩn mở và thúc đẩy cộng đồng nguồn mở.

Gần đây, tất cả API Dữ liệu của Google đều đã hỗ trợ OAuth, một giao thức mở nhằm chuẩn hóa cách các ứng dụng web và máy tính 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 tiện để xác thực API theo cách chuẩn và an toàn. Là các lập trình viên, chúng tôi được dạy cách sử dụng lại mã mỗi khi 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 dễ dàng tạo công cụ hoạt động với nhiều dịch vụ từ nhiều nhà cung cấp khác nhau.

Đối tượng người xem

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

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

Một thuật ngữ nhỏ

Tìm hiểu về OAuth là việc tìm hiểu các thuật ngữ tương ứng. 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 rất nhiều vào một số định nghĩa nhất định, vì vậy, hãy cho biết rõ ý nghĩa của từng định nghĩa trong bối cảnh triển khai OAuth của Google.

  1. "khiêu vũ qua 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. Mã thông báo yêu cầu (OAuth)

    Mã thông báo ban đầu để cho Google biết ứ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 điệu nhảy OAuth là cho phép người dùng cấp quyền truy cập vào dữ liệu của họ theo cách thủ công. Nếu bước này thành công, thì mã thông báo yêu cầu sẽ được uỷ quyền.

  3. Mã thông báo truy cập (OAuth)

    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ó mã thông báo này, người dùng sẽ không cần thực hiện lại bước nhảy OAuth, trừ khi mã thông báo bị thu hồi.

    Điểm giống với AuthSub:
    Mã truy cập OAuth giống như mã bảo mật phiên AuthSub.

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

    Đây là các URI bắt buộc để xác thực ứng dụng và nhận mã truy cập. Có tổng cộng 3 – 1 cho mỗi bước của 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
    Cho phép 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

    Điểm giống với AuthSub:
    Việc đổi mã thông báo yêu cầu được uỷ quyền cho mã truy cập tương tự như việc nâng cấp một mã AuthSub dùng một lần lên mã phiên hoạt động dài hạn tại https://www.google.com/accounts/AuthSubRequestToken và https://www.google.com/accounts/AuthSubSessionToken. Đ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 quá trình mã thông báo từ trang uỷ quyền AuthSubRequestToken.

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

    Trong trường hợp của API dữ liệu của Google, 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 điểm cuối OAuth. Một ví dụ khác về nhà cung cấp dịch vụ OAuth là GCM.

  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 linh hoạt ở chỗ nó 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/máy tính để bàn, nhưng Google chỉ hỗ trợ OAuth cho các ứng dụng web.

Bắt đầu

Đăng ký

Bạn chỉ cần thực hiện một số bước thiết lập nhỏ trước khi có thể bắt đầu sử dụng OAuth bằng API Dữ liệu của Google. Vì tất cả các yêu cầu OAuth đều phải được ký số, trước tiên, bạn cần đăng ký miền của mình và tải chứng chỉ công khai lên Google. Hãy xem phần Đăng ký các ứng dụng dựa trên nền tảng 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 việc đó.

Yêu cầu ký

Sau khi miền của bạn được đăng ký, bạn có thể bắt đầu ký 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ư (sử dụng RSA_SHA1). Kết quả là giá trị bạn đặt cho oauth_signature.

Yêu cầu mẫu

GET một 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
Chuỗi cơ sở mẫu 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 ý: Thông tin này chỉ nhằm mục đích đại diện. 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á 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ì dưới dạng một phần của URL yêu cầu.

Để biết thêm thông tin về việc ký yêu cầu bằng OAuth, hãy xem bài viết Ký yêu cầu OAuth.

Sự khác biệt so với AuthSub:
Để so sánh, dưới đây là ví dụ tương tự về cách sử dụng AuthSub an toàn:

Định dạng chuỗi cơ sở base_string = http-method http-request-URL timestamp nonce
Chuỗi cơ sở mẫu 
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 yêu cầu ký bằng AuthSub, hãy xem bài viết 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 cao. So với các API xác thực khác của Google, tôi đồng ý. Bạn có thể nhận thấy lợi ích của OAuth khi mở rộng ứng dụng của mình để sử dụng các dịch vụ khác (không phải Google). Việc viết một đoạn mã xác thực duy nhất hoạt động được với nhiều nhà cung cấp dịch vụ và API của họ nghe rất thú vị. Bạn sẽ tự cảm ơn sau này khi tìm hiểu giao thức.

OAuth Playground là công cụ tôi tạo để giúp nhà phát triển khắc phục tình trạng tai nạn OAuth. Bạn có thể sử dụng Playground để giúp gỡ lỗi, kiểm tra cách triển khai của riêng bạn hoặc thử nghiệm với API Dữ liệu của Google.

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

  1. Hình 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 đó lên mã truy cập.
  2. Hiển thị đúng chuỗi cơ sở chữ ký cho mỗi yêu cầu.
  3. Hiển thị tiêu đề Authorization chính xác cho từng yêu cầu.
  4. Hình minh họa 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 đã được xác thực ngay trong trình duyệt.
  6. Cho phép bạn kiểm tra oauth_consumer_key (miền đã đăng ký) và khoá riêng tư của riêng bạn.
  7. Khám phá những dịch vụ của Nguồn cấp dữ liệu của Google mà bạn có thể dùng cho oauth_token.

Chạy bản demo

Bước 1: Chọn(các) Phạm vi của bạn

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

Điểm giống với 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 thông số này theo đề xuất trong thông số kỹ thuật OAuth.

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

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

Lưu ý: oauth_signature_method và oauth_consumer_key là các 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 sử dụng HMAC-SHA1 cho oauth_signature_method. Trong trường hợp đó, Playground sẽ hiển thị thêm các ô để bạn nhập oauth_consumer_key và bí mật của người tiêu dùng. Bạn có thể tìm thấy những giá trị này trên trang https://www.google.com/accounts/ManageDomains cho miền mà bạn đã đăng ký.

Sự 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. Tham số này nằm trong tham số URL next. Có một thông số như vậy trong OAuth: oauth_consumer_key. Đặt miền này theo miền đã đăng ký.

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

Có 3 bước để nhận 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 cho Google biết ứng dụng của bạn đang bắt đầu bước nhảy OAuth.

Đầu tiên, nhấp vào nút "Yêu cầu mã thông báo" trong hộp "Lấy mã thông báo".

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

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

Tiếp theo, nhấp vào nút "Uỷ quyền" trong hộp "Lấy 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 về OAuth Playground.

Điểm giống với AuthSub:
Trang uỷ quyền này giống với AuthSub.

Điểm khác biệt với AuthSub:
Tham số URL next của AuthSub giống với tham số oauth_callback. Điểm khác biệt là trong OAuth, oauth_callback 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 ủy quyền và người dùng có thể thực hiện không đồng bộ quá trình nâng cấp mã thông báo lên https://www.google.com/accounts/OAuthGetAccessToken.

Mẹo: Bạn nên chỉ định URL oauth_callback nếu đang viết ứng dụng web vì URL này cung cấp trải nghiệm người dùng tốt hơn.

Cuối cùng, nhấp vào nút "Truy cập mã thông báo" trong hộp "Nhận mã thông báo".

Hành động này sẽ nâng cấp mã yêu cầu được uỷ quyền (như được ghi chú trong nhãn "mã truy cập 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 bước nhảy OAuth.

Giờ đây, chúng ta có thể làm điều gì đó thú vị!

Sử dụng mã truy cập

Bây giờ, bạn đã có thể 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 ba phương thức HTTP cuối cùng này khi bạn đang làm việc với dữ liệu thực của mình!

Mẹo: Để khám phá các 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".

Dưới đây là truy vấn mẫu: 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ể trực tiếp xem 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 cú pháp vùng được đánh dấu.

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

  1. Tìm phần tử <link> có rel="edit" trong bài đăng mà bạn muốn cập nhật. Thẻ 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 giá trị nhập "Nhập nguồn cấp dữ liệu trên Google".

  2. Sao chép XML của mục hiện tại bằng cách nhấp vào "xem đơn giản" ở đầu bảng điều khiển về cú pháp được đánh dấu. 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 "nhập dữ liệu bài đăng" bên dưới trình đơn thả xuống đó và 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.

Mẹo: 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?". Sau khi truy vấn, bạn sẽ có thể nhấp vào các đường liên kết trong 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 AtomPub/Atom (giao thức cơ bản của API dữ liệu của Google) và OAuth giúp thúc đẩy web. Khi ngày càng có nhiều trang web bắt đầu đón nhận các tiêu chuẩn này, nhà phát triển là những người chiến thắng. Việc tạo ứng dụng giết người đột nhiên trở nên khó khăn hơn.

Nếu bạn có câu hỏi hoặc nhận xét về OAuth Playground, hoặc dùng OAuth với 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