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

API của Google sử dụng giao thức OAuth 2.0 để xác thực và uỷ quyền. Google hỗ trợ các trường hợp OAuth 2.0 phổ biến như các ứng dụng cho máy chủ web, phía máy khách, đã cài đặt và các thiết bị đầu vào hạn chế.

Để bắt đầu, hãy lấy thông tin xác thực ứng dụng OAuth 2.0 từ Google API Console. Sau đó, ứng dụng khách của bạn sẽ 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ã thông báo từ phản hồi và gửi mã thông báo đó đến API Google mà bạn muốn truy cập. Để xem minh hoạ tương tác về cách sử dụng OAuth 2.0 với Google (bao gồm cả tùy chọn sử dụng thông tin đăng nhập của ứng dụng), hãy thử nghiệm với OAuth 2.0 Playground.

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 các đường liên kết đến nội dung chi tiết hơn. Để biết chi tiết về cách sử dụng OAuth 2.0 cho xác thực, hãy xem phần OpenID Connect.

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

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

1. Lấy thông tin xác thực OAuth 2.0 từ Google API Console.

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

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 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 dữ liệu riêng tư bằng API 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 có thể cho phép nhiều mức độ truy cập vào nhiều API. Một tham số có tên là scope kiểm soát một tập hợp các tài nguyên và thao tác mà mã truy cập cho phép. Trong yêu cầu mã thông báo truy cập, ứng dụng sẽ gửi một hoặc nhiều giá trị trong tham số scope.

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

Một số yêu cầu yêu cầu 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 không. Quá trình này được 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ó thể dùng để lấy mã truy cập) và danh sách các 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ề một lỗi.

Nhìn chung, phương pháp hay nhất là yêu cầu tăng phạm vi, tại thời điểm cần thiết, thay vì phải truy cập từ trước. Ví dụ: một ứng dụng muốn hỗ trợ lưu 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 Ủy quyền gia tăng.

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

So sánh các phạm vi 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 API Google liên quan. Tắt mọi tính năng của ứng dụng 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 yêu cầu. Tham khảo tài liệu về từng API Google để biết phạm vi cần có để truy cập. Một 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, 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ụ: API Google People có thể trả về phạm vi https://www.googleapis.com/auth/contacts khi một ứng dụng yêu cầu người dùng ủy quyền phạm vi https://www.google.com/m8/feeds/; phương thức API Google People people.updateContact yêu cầu phạm vi được cấp là https://www.googleapis.com/auth/contacts.

4. Gửi mã thông báo truy cập tới 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 Ủy quyền HTTP. 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 gửi vì các tham số URI có thể xuất hiện trong tệp nhật ký không hoàn toàn bảo mật. Ngoài ra, bạn cũng nên dùng phương pháp tốt nhất để tránh tạo các tên tham số URI không cần thiết.

Mã thông báo truy cập chỉ hợp lệ đối với 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 được cấp mã truy cập cho API Lịch Google, thì mã truy cập 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 thao tác 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 không giới hạn. Nếu ứng dụng của bạn cần quyền truy cập vào một API Google ngoài thời gian tồn tại của một mã truy cập, thì ứng dụng đó có thể nhận được mã làm mới. Mã thông báo làm mới cho phép ứng dụng của bạn lấy mã truy cập mới.

Trường hợp

Ứng dụng máy chủ web

Điểm cuối Google OAuth 2.0 hỗ trợ các ứng dụng máy chủ web sử dụng ngôn ngữ và khung như PHP, Java, 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 trình duyệt đến một URL của Google; URL này 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ý việc 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ả là một mã ủy quyền mà ứng dụng có thể trao đổi để lấy mã truy cập và mã làm mới.

Ứng dụng sẽ lưu trữ mã làm mới để sử dụng sau này và sử dụng mã truy cập để truy cập 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 một 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ã cho một mã thông báo và sử dụng mã đó để gọi một đ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 máy chủ web.

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

Điểm cuối Google OAuth 2.0 hỗ trợ các ứng dụng được cài đặt trên các 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 xác định đây là ứng dụng đã cài đặt rồi chọn ứng dụng Android, Chrome, iOS, Universal Windows Platform (UWP) hoặc ứng dụng dành cho máy tính.

Quá trình này sẽ dẫn đến một mã ứng dụng khách và trong một số trường hợp là mã ứng dụng khách bí mật mà bạn nhúng vào mã nguồn của ứng dụng. (Trong trường hợp này, bí mật ứ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 trình duyệt đến một URL của Google; URL này 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ý việc 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ả là một mã ủy quyền mà ứng dụng có thể trao đổi để lấy mã truy cập và mã làm mới.

Ứng dụng sẽ lưu trữ mã làm mới để sử dụng sau này và sử dụng mã truy cập để truy cập 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 một 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ã cho một mã thông báo và sử dụng mã đó để gọi một điểm cuối API của Google.

Để biết chi tiết, hãy xem Sử dụng OAuth 2.0 cho ứng dụng đã cài đặt.

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

Điểm cuối Google OAuth 2.0 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 trình duyệt đến một URL của Google; URL này 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ý việc 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ả là một mã truy cập mà ứng dụng cần xác thực trước khi đưa vào yêu cầu API Google. Khi mã thông báo hết hạn, ứng dụng sẽ lặp lại quy trình.

Ứng dụng JS 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 để 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.

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

Điểm cuối Google OAuth 2.0 hỗ trợ các ứng dụng chạy trên các thiết bị đầu vào giới hạn, chẳng 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 đưa ra yêu cầu dịch vụ web đối với một URL của Google để lấy mã uỷ quyền. Nội dung phản hồi chứa một vài tham số, bao gồm URL và mã mà ứng dụng hiển thị cho người dùng.

Người dùng nhận URL và mã từ thiết bị, sau đó chuyển sang một thiết bị hoặc máy tính riêng biệt có khả năng nhập phong phú hơn. Người dùng khởi chạy 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ò URL của Google trong khoảng thời gian đã chỉ định. Sau khi người dùng phê duyệt quyền truy cập, phản hồi từ máy chủ của Google sẽ chứa 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à sử dụng mã truy cập để truy cập 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 (chẳng hạn như API Dự đoán và Google Cloud Storage) có thể hành động thay mặt cho ứng dụng mà không cần truy cập thông tin người dùng. Trong các trường hợp này, ứng dụng của bạn cần chứng minh danh tính của mình với API, nhưng không cần sự đồng ý của người dùng. Tương tự như vậy, trong các trường hợp của doanh nghiệp, ứng dụng của bạn có thể yêu cầu quyền truy cập được uỷ quyền cho một số tài nguyên.

Đối với các loại tương tác từ máy chủ đến máy chủ này, bạn cần có tài khoản dịch vụ. Tài khoản này là tài khoản thuộc về ứng dụng của bạn thay vì một người dùng cuối cá nhân. Ứng dụng của bạn sẽ gọi API 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 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 Google thay mặt cho người dùng cuối và đôi khi người dùng phải đồng ý.)

Thông tin đăng nhập của tài khoản dịch vụ mà bạn nhận được từ Google API Console, bao gồm địa chỉ email duy nhất được tạo, mã ứng dụng khách và ít nhất một cặp khóa công khai/riêng tư. Bạn sử dụng mã ứng dụng khách và một khoá riêng tư để tạo JWT đã ký và tạo yêu cầu mã thông báo truy cập theo định dạng thích 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 Google OAuth 2.0. Máy chủ này sẽ trả về một mã thông báo 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 quy trình.

Ứng dụng máy chủ của bạn sử dụng JWT để yêu cầu mã thông báo từ Máy chủ uỷ quyền của Google, sau đó sử dụng mã thông báo để 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, tùy thuộc vào các giới hạn sau:

  • Mã ủy quyền: 256 byte
  • Mã thông báo truy cập: 2048 byte
  • Làm mới mã thông báo: 512 byte

Mã thông báo 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ã thông báo truy cập OAuth 2.0 của API Google nhưng có các giới hạn khác nhau 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 có 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.

Làm mới hết hạn mã thông báo

Bạn phải viết mã của mình để dự đoán khả năng mã làm mới được cấp có thể không còn hoạt động. Mã làm mới có thể ngừng hoạt động vì một trong các 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 một loại người dùng bên ngoài và trạng thái xuất bản là "Thử nghiệm" sẽ được phát hành một mã thông báo làm mới sẽ hết hạn sau 7 ngày, trừ khi phạm vi OAuth duy nhất được yêu cầu là một tập hợp con của 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 tương đương OpenID Connect).

Hiện có giới hạn 100 mã làm mới cho mỗi Tài khoản Google trên mỗi ID ứng dụng khách OAuth 2.0. Nếu đã đạt đến giới hạn này, việc tạo mã làm mới mới sẽ tự động làm mất hiệu lực của mã làm mới cũ nhất mà không có 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ó giới hạn 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ó đối với tất cả khách hà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 của nhà phát triển được sử dụng để kiểm tra việc triển khai có thể bị vượt quá.

Nếu bạn cần cấp quyền cho nhiều chương trình, máy hoặc thiết bị, một giải pháp là giới hạn số lượng máy khách mà bạn cho phép trên mỗi Tài khoản Google ở mức 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à sử dụng những đặc quyền đó để uỷ quyền cho một số khách hà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 những tổ chức dùng GCP có thể yêu cầu người dùng phải thường xuyên xác thực lại 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 tác động đến quyền truy cập vào Google Cloud Console, Google Cloud SDK (còn gọi là CLI của gcloud) 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 hết thời lượng phiên, các lệnh gọi API của bạn sẽ gặp lỗi tương tự như điều sẽ xảy ra nếu mã làm mới bị thu hồi – lệnh gọi sẽ không thành công do loại lỗi invalid_grant; có thể dùng trường error_subtype để phân biệt giữa mã thông báo bị thu hồi và lỗi do chính sách kiểm soát phiên (ví dụ: "error_subtype": "invalid_rapt"). Vì thời lượng phiên có thể rất giới hạn (trong khoảng thời gian từ 1 giờ đến 2 giờ này).

Tương tự như vậy, bạn không được sử dụng hoặc khuyến khích sử dụng thông tin xác thực người dùng để triển khai 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 diễn ra trong thời gian dài và khách hàng áp dụng chính sách kiểm soát phiên trên những người dùng đó, thì ứng dụng máy chủ sẽ không thành công vì 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.