Sử dụng OAuth 2.0 để truy cập API Google

Các API của Google dùng giao thức OAuth 2.0 để xác thực và uỷ quyền. Google hỗ trợ các tình huống phổ biến của OAuth 2.0, chẳng hạn như các tình huống dành cho máy chủ web, ứng dụng phía máy khách, ứng dụng đã cài đặt và ứng dụng có đầu vào giới hạn.

Để bắt đầu, hãy lấy thông tin đăng nhập của ứng dụng OAuth 2.0 từ Google API Console. Sau đó, ứng dụng khách của bạn yêu cầu một mã truy cập từ Máy chủ uỷ quyền của Google, trích xuất một mã thông báo từ phản hồi rồi gửi mã thông báo đó đến API của Google mà bạn muốn truy cập. Để có phần minh hoạ có tính tương tác về cách sử dụng OAuth 2.0 với Google (bao gồm cả lựa chọn sử dụng thông tin đăng nhập ứng dụng của riêng bạn), hãy thử nghiệm với Play OAuth 2.0.

Trang này cung cấp thông tin tổng quan về các trường hợp uỷ quyền OAuth 2.0 mà Google hỗ trợ, đồng thời cung cấp đường liên kết đến nội dung chi tiết hơn. Để biết thông tin chi tiết về cách sử dụng OAuth 2.0 để xác thực, hãy xem bài viết OpenID Connect.

Các bước cơ bản

Tất cả ứng dụng đều tuân theo mẫu cơ bản khi truy cập API của Google bằng OAuth 2.0. Ở cấp độ cao, bạn sẽ làm theo 5 bước:

1. Lấy thông tin đăng nhập OAuth 2.0 từ Google API Console.

Truy cập Google API Console để lấy thông tin đăng nhập OAuth 2.0, chẳng hạn như mã ứng dụng khách và mật khẩu ứng dụng khách mà cả Google và ứng dụng của bạn đã biết. Tập hợp các giá trị sẽ khác nhau tuỳ theo loại ứng dụng bạn đang xây dựng. Ví dụ: ứng dụng JavaScript không yêu cầu khoá bí mật nhưng ứng dụng máy chủ web thì có yêu cầu bí mật.

Bạn phải tạo một ứng dụng OAuth phù hợp với nền tảng mà ứng dụng của bạn sẽ chạy, ví dụ:

2. Lấy mã truy cập từ Máy chủ uỷ quyền của Google.

Trước khi có thể truy cập vào dữ liệu riêng tư bằng API của Google, ứng dụng của bạn phải lấy được mã truy cập cấp quyền truy cập vào API đó. Một mã truy cập duy nhất có thể cấp quyền truy cập ở nhiều mức độ vào nhiều API. Tham số biến có tên là scope kiểm soát tập hợp tài nguyên và thao tác mà mã truy cập cho phép. Trong yêu cầu mã truy cập, ứng dụng sẽ gửi một hoặc nhiều giá trị trong tham số scope.

Có một số cách để đưa ra yêu cầu này và chúng sẽ khác nhau tuỳ thuộc vào loại ứng dụng bạn đang xây dựng. Ví dụ: một ứng dụng JavaScript có thể yêu cầu mã truy cập bằng cách dùng một trình duyệt chuyển hướng đến Google, trong khi một ứng dụng được cài đặt trên thiết bị mà không có trình duyệt nào sử dụng các yêu cầu dịch vụ web.

Một số yêu cầu đòi hỏi một bước xác thực trong đó người dùng đăng nhập bằng Tài khoản Google của họ. Sau khi đăng nhập, người dùng sẽ được hỏi xem họ có sẵn sàng cấp một hoặc nhiều quyền mà ứng dụng của bạn đang yêu cầu hay không. Quá trình này gọi là sự đồng ý của người dùng.

Nếu người dùng cấp ít nhất một quyền, Máy chủ uỷ quyền của Google sẽ gửi cho ứng dụng của bạn một mã truy cập (hoặc mã uỷ quyền mà ứng dụng của bạn có thể dùng để lấy mã truy cập) và danh sách phạm vi truy cập mà mã thông báo đó đã cấp. Nếu người dùng không cấp quyền, máy chủ sẽ trả về lỗi.

Nhìn chung, phương pháp hay nhất là yêu cầu phạm vi theo mức độ tăng dần (tại thời điểm cần truy cập) thay vì từ trước. Ví dụ: một ứng dụng muốn hỗ trợ lưu một sự kiện vào lịch không được yêu cầu quyền truy cập vào Lịch Google cho đến khi người dùng nhấn nút "Thêm vào Lịch"; xem phần Uỷ quyền gia tăng.

3. Kiểm tra phạm vi truy cập mà người dùng đã cấp.

So sánh các phạm vi có trong phản hồi của mã truy cập với các phạm vi cần thiết để truy cập vào các tính năng và chức năng của ứng dụng phụ thuộc vào quyền truy cập vào một API Google có liên quan. Vô hiệu hoá mọi tính năng của ứng dụng sẽ không hoạt động được nếu không có quyền truy cập vào API liên quan.

Phạm vi trong yêu cầu của bạn có thể không khớp với phạm vi trong phản hồi của bạn, ngay cả khi người dùng đã cấp tất cả các phạm vi được yêu cầu. Hãy tham khảo tài liệu về từng API của Google để biết các phạm vi cần thiết để truy cập. API có thể liên kết nhiều giá trị chuỗi phạm vi với một phạm vi truy cập duy nhất, trả về cùng một chuỗi phạm vi cho tất cả các giá trị được phép trong yêu cầu. Ví dụ: Google People API có thể trả về một phạm vi là https://www.googleapis.com/auth/contacts khi một ứng dụng yêu cầu người dùng uỷ quyền một phạm vi là https://www.google.com/m8/feeds/; phương thức API Google People people.updateContact yêu cầu một phạm vi đã cấp là https://www.googleapis.com/auth/contacts.

4. Gửi mã truy cập đến một API.

Sau khi nhận được mã truy cập, ứng dụng sẽ gửi mã thông báo đó đến API Google trong tiêu đề của yêu cầu uỷ quyền HTTP. Bạn có thể gửi mã thông báo dưới dạng tham số chuỗi truy vấn URI, nhưng bạn không nên làm như vậy vì tham số URI có thể được đưa vào các tệp nhật ký không hoàn toàn an toàn. Ngoài ra, bạn nên sử dụng REST để tránh tạo tên tham số URI không cần thiết.

Mã truy cập chỉ hợp lệ cho tập hợp thao tác và tài nguyên được mô tả trong scope của yêu cầu mã thông báo. Ví dụ: nếu mã truy cập được cấp cho API Lịch Google, thì mã đó sẽ không cấp quyền truy cập vào API Danh bạ Google. Tuy nhiên, bạn có thể gửi mã truy cập đó đến API Lịch Google nhiều lần cho các hoạt động tương tự.

5. Làm mới mã truy cập, nếu cần.

Mã truy cập có thời gian tồn tại giới hạn. Nếu cần quyền truy cập vào một API của Google sau thời gian tồn tại của một mã truy cập, ứng dụng của bạn có thể nhận được mã làm mới. Mã làm mới cho phép ứng dụng của bạn lấy mã truy cập mới.

Tình huống

Ứng dụng máy chủ web

Điểm cuối OAuth 2.0 của Google hỗ trợ các ứng dụng máy chủ web sử dụng các ngôn ngữ và khung như PHP, Java, Go, Python, Ruby và ASP.NET.

Trình tự uỷ quyền bắt đầu khi ứng dụng của bạn chuyển hướng một trình duyệt đến một URL của Google; URL đó bao gồm các tham số truy vấn cho biết loại quyền truy cập đang được yêu cầu. Google xử lý hoạt động xác thực người dùng, lựa chọn phiên và sự đồng ý của người dùng. Kết quả thu được là một mã uỷ quyền mà ứng dụng có thể đổi lấy mã truy cập và mã làm mới.

Ứng dụng nên lưu trữ mã làm mới để sử dụng sau này và dùng mã truy cập để truy cập vào một API của Google. Sau khi mã truy cập hết hạn, ứng dụng sẽ dùng mã làm mới để lấy mã mới.

Ứng dụng của bạn gửi yêu cầu mã thông báo đến Máy chủ uỷ quyền của Google, nhận mã uỷ quyền, trao đổi mã đó để lấy mã thông báo và sử dụng mã thông báo đó để gọi điểm cuối API của Google.

Để biết thông tin chi tiết, hãy xem bài viết Sử dụng OAuth 2.0 cho ứng dụng máy chủ web.

Các ứng dụng đã cài đặt

Điểm cuối OAuth 2.0 của Google hỗ trợ các ứng dụng được cài đặt trên thiết bị như máy tính, thiết bị di động và máy tính bảng. Khi bạn tạo mã ứng dụng khách thông qua Google API Console, hãy chỉ định rằng đây là Ứng dụng đã cài đặt, sau đó chọn loại ứng dụng dành cho Android, ứng dụng Chrome, iOS, Universal Windows Platform (UWP) hoặc ứng dụng Máy tính.

Quá trình này sẽ dẫn đến một ID ứng dụng khách và (trong một số trường hợp) là mật khẩu ứng dụng khách mà bạn nhúng vào mã nguồn của ứng dụng. (Trong trường hợp này, mật khẩu ứng dụng khách rõ ràng không được coi là bí mật.)

Trình tự uỷ quyền bắt đầu khi ứng dụng của bạn chuyển hướng một trình duyệt đến một URL của Google; URL đó bao gồm các tham số truy vấn cho biết loại quyền truy cập đang được yêu cầu. Google xử lý hoạt động xác thực người dùng, lựa chọn phiên và sự đồng ý của người dùng. Kết quả thu được là một mã uỷ quyền mà ứng dụng có thể đổi lấy mã truy cập và mã làm mới.

Ứng dụng nên lưu trữ mã làm mới để sử dụng sau này và dùng mã truy cập để truy cập vào một API của Google. Sau khi mã truy cập hết hạn, ứng dụng sẽ dùng mã làm mới để lấy mã mới.

Ứng dụng của bạn gửi yêu cầu mã thông báo đến Máy chủ uỷ quyền của Google, nhận mã uỷ quyền, trao đổi mã đó để lấy mã thông báo và sử dụng mã thông báo đó để gọi điểm cuối API của Google.

Để biết thông tin chi tiết, hãy xem phần Sử dụng OAuth 2.0 cho các ứng dụng đã cài đặt.

Ứng dụng phía máy khách (JavaScript)

Điểm cuối OAuth 2.0 của Google hỗ trợ các ứng dụng JavaScript chạy trong trình duyệt.

Trình tự uỷ quyền bắt đầu khi ứng dụng của bạn chuyển hướng một trình duyệt đến một URL của Google; URL đó bao gồm các tham số truy vấn cho biết loại quyền truy cập đang được yêu cầu. Google xử lý hoạt động xác thực người dùng, lựa chọn phiên và sự đồng ý của người dùng.

Kết quả sẽ là một mã truy cập mà ứng dụng phải xác thực trước khi đưa vào yêu cầu API của Google. Khi mã thông báo hết hạn, ứng dụng sẽ lặp lại quá trình này.

Ứng dụng JS của bạn gửi yêu cầu mã thông báo đến Máy chủ uỷ quyền của Google, nhận mã thông báo, xác thực mã thông báo và sử dụng mã thông báo này để gọi điểm cuối API của Google.

Để biết thông tin chi tiết, hãy xem phần Sử dụng OAuth 2.0 cho ứng dụng phía máy khách.

Các ứng dụng trên thiết bị có đầu vào giới hạn

Điểm cuối OAuth 2.0 của Google hỗ trợ các ứng dụng chạy trên các thiết bị đầu vào giới hạn như máy chơi trò chơi, máy quay video và máy in.

Trình tự uỷ quyền bắt đầu bằng việc ứng dụng gửi yêu cầu dịch vụ web đến một URL của Google để lấy mã uỷ quyền. Phản hồi này chứa một số tham số, bao gồm cả URL và mã mà ứng dụng hiển thị cho người dùng.

Người dùng lấy URL và mã từ thiết bị, sau đó chuyển sang một thiết bị hoặc máy tính riêng có khả năng nhập dữ liệu phong phú hơn. Người dùng chạy một trình duyệt, chuyển đến URL được chỉ định, đăng nhập và nhập mã.

Trong khi đó, ứng dụng thăm dò một URL trên Google theo khoảng thời gian được chỉ định. Sau khi người dùng phê duyệt quyền truy cập, phản hồi từ máy chủ Google sẽ chứa một mã truy cập và mã làm mới. Ứng dụng nên lưu trữ mã làm mới để sử dụng sau này và dùng mã truy cập để truy cập vào một API của Google. Sau khi mã truy cập hết hạn, ứng dụng sẽ dùng mã làm mới để lấy mã mới.

Người dùng đăng nhập trên một thiết bị riêng biệt có trình duyệt

Để biết thông tin chi tiết, hãy xem phần Sử dụng OAuth 2.0 cho thiết bị.

Tài khoản dịch vụ

Các API của Google như Prediction API và Google Cloud Storage có thể hoạt động thay cho ứng dụng của bạn mà không cần truy cập vào thông tin người dùng. Trong những trường hợp này, ứng dụng của bạn cần chứng minh danh tính riêng của ứng dụng đó với API, nhưng không cần sự đồng ý của người dùng. Tương tự, trong các trường hợp doanh nghiệp, ứng dụng có thể yêu cầu quyền truy cập được uỷ quyền vào một số tài nguyên.

Đối với các loại hình tương tác giữa các máy chủ này, bạn cần có tài khoản dịch vụ. Đây là tài khoản thuộc về ứng dụng của bạn chứ không phải của một người dùng cuối cá nhân. Ứng dụng của bạn gọi các API của Google thay mặt cho tài khoản dịch vụ và bạn không cần phải có sự đồng ý của người dùng. (Trong các trường hợp không phải tài khoản dịch vụ, ứng dụng của bạn sẽ gọi API của Google thay mặt cho người dùng cuối và đôi khi cần phải có sự đồng ý của người dùng.)

Thông tin xác thực của tài khoản dịch vụ mà bạn lấy từ Google API Console, bao gồm một địa chỉ email được tạo riêng biệt, một mã ứng dụng khách và ít nhất một cặp khoá công khai/riêng tư. Bạn dùng mã ứng dụng khách và một khoá riêng tư để tạo một JWT đã ký và tạo một yêu cầu mã truy cập ở định dạng phù hợp. Sau đó, ứng dụng của bạn sẽ gửi yêu cầu mã thông báo đến Máy chủ uỷ quyền của Google OAuth 2.0. Máy chủ này sẽ trả về một mã truy cập. Ứng dụng sử dụng mã thông báo để truy cập API của Google. Khi mã thông báo hết hạn, ứng dụng sẽ lặp lại quá trình này.

Ứng dụng máy chủ của bạn dùng JWT để yêu cầu một mã thông báo từ Máy chủ uỷ quyền của Google, sau đó dùng mã này để gọi một điểm cuối API của Google. Không có người dùng cuối nào tham gia.

Để biết thông tin chi tiết, hãy xem tài liệu về tài khoản dịch vụ.

Kích thước mã thông báo

Mã thông báo có thể có kích thước khác nhau, với các giới hạn như sau:

  • Mã uỷ quyền: 256 byte
  • Mã truy cập: 2048 byte
  • Mã làm mới: 512 byte

Mã truy cập mà API Dịch vụ mã thông báo bảo mật của Google Cloud trả về có cấu trúc tương tự như mã truy cập OAuth 2.0 của Google API nhưng có giới hạn khác về kích thước mã thông báo. Để biết thông tin chi tiết, hãy xem tài liệu về API.

Google giữ quyền thay đổi kích thước mã thông báo trong những giới hạn này và ứng dụng của bạn phải hỗ trợ kích thước mã thông báo thay đổi tương ứng.

Thời hạn của mã làm mới

Bạn phải viết mã để dự đoán khả năng mã làm mới đã cấp có thể không còn hoạt động nữa. Mã làm mới có thể ngừng hoạt động vì một trong những lý do sau:

Một dự án Google Cloud Platform có màn hình xin phép bằng OAuth được định cấu hình cho loại người dùng bên ngoài và trạng thái xuất bản là "Testing" sẽ được cấp mã làm mới sẽ hết hạn sau 7 ngày, trừ phi phạm vi OAuth duy nhất được yêu cầu là một tập hợp con gồm tên, địa chỉ email và hồ sơ người dùng (thông qua các phạm vi userinfo.email, userinfo.profile, openid hoặc các phạm vi tương đương OpenID Connect).

Hiện tại, mỗi Tài khoản Google chỉ được có tối đa 100 mã thông báo làm mới cho mỗi ID ứng dụng khách OAuth 2.0. Nếu đã đạt đến giới hạn, việc tạo mã làm mới mới sẽ tự động vô hiệu hoá mã làm mới cũ nhất mà không cảnh báo. Giới hạn này không áp dụng cho tài khoản dịch vụ.

Ngoài ra, còn có một hạn mức lớn hơn về tổng số mã thông báo làm mới mà một tài khoản người dùng hoặc tài khoản dịch vụ có thể có trên tất cả ứng dụng. Hầu hết người dùng bình thường sẽ không vượt quá giới hạn này, nhưng tài khoản nhà phát triển dùng để kiểm thử một cách triển khai thì có thể.

Nếu bạn cần cấp quyền cho nhiều chương trình, máy hoặc thiết bị, có một giải pháp là giới hạn số lượng ứng dụng mà bạn cho phép trên mỗi Tài khoản Google xuống còn 15 hoặc 20. Nếu là quản trị viên Google Workspace, bạn có thể tạo thêm người dùng có đặc quyền quản trị và dùng những người dùng này để uỷ quyền cho một số ứng dụng.

Xử lý các chính sách kiểm soát phiên cho các tổ chức Google Cloud Platform (GCP)

Quản trị viên của các tổ chức GCP có thể yêu cầu thường xuyên xác thực lại người dùng khi họ truy cập vào các tài nguyên trên GCP bằng tính năng kiểm soát phiên của Google Cloud. Chính sách này ảnh hưởng đến quyền truy cập vào Google Cloud Console, Google Cloud SDK (còn gọi là gcloud CLI) và mọi ứng dụng OAuth của bên thứ ba yêu cầu phạm vi Cloud Platform. Nếu người dùng đã áp dụng chính sách kiểm soát phiên thì khi thời lượng phiên hết hạn, các lệnh gọi API sẽ gặp lỗi tương tự như khi mã làm mới bị thu hồi – lệnh gọi sẽ không thành công với loại lỗi invalid_grant; trường error_subtype có thể được dùng để phân biệt giữa mã bị thu hồi và lỗi do chính sách kiểm soát phiên (ví dụ: "error_subtype": "invalid_rapt"). Thời lượng phiên khởi động lại có thể rất giới hạn (từ 1 giờ chỉ cần xác thực hoàn toàn trong thời gian khởi động lại phiên là 2 giờ).

Tương tự, bạn không được sử dụng hoặc khuyến khích sử dụng thông tin đăng nhập của người dùng để triển khai từ máy chủ đến máy chủ. Nếu thông tin đăng nhập của người dùng được triển khai trên máy chủ cho các công việc hoặc hoạt động chạy trong thời gian dài và khách hàng áp dụng các chính sách kiểm soát phiên cho những người dùng đó, thì ứng dụng máy chủ sẽ không thành công vì sẽ không có cách nào để xác thực lại người dùng khi thời lượng phiên hết hạn.

Để biết thêm thông tin về cách giúp khách hàng của bạn triển khai tính năng này, hãy tham khảo bài viết trợ giúp tập trung vào quản trị viên này.

Thư viện ứng dụng

Các thư viện ứng dụng sau đây tích hợp với các khung phổ biến, giúp việc triển khai OAuth 2.0 trở nên đơn giản hơn. Các tính năng khác sẽ được thêm vào thư viện theo thời gian.