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 phổ biến của OAuth 2.0, chẳng hạn như các trường hợp cho máy chủ web, phía máy khách, ứng dụng đã cài đặt và ứng dụng thiết bị có giới hạn đầu vào.

Để 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ã 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 bản minh hoạ tương tác về việc sử dụng OAuth 2.0 với Google (bao gồm cả tuỳ chọn sử dụng thông tin xác thực ứng dụng của riêng bạn), 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 đườ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 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 API của Google bằng OAuth 2.0. Nhìn chung, bạn cần làm theo 5 bước sau:

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, chẳng hạn như mã ứng dụng khách và khoá bí mật của ứng dụng mà cả Google và ứng dụng của bạn đều biết. Tập hợp giá trị sẽ thay đổi tuỳ thuộc vào loại ứng dụng mà 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ó.

Bạn phải tạo một ứng dụng khách 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ã thông báo 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 có một mã thông báo truy cập cấp quyền truy cập vào API đó. Một mã truy cập có thể cấp nhiều mức độ truy cập vào nhiều API. Tham số biến có tên scope kiểm soát tập hợp tài nguyên và thao tác mà mã thông báo truy cập cho phép. Trong quá trình yêu cầu mã truy cập, ứng dụng sẽ gửi một hoặc nhiều giá trị trong thông số scope.

Có một số cách để đưa ra yêu cầu này và các cách này khác nhau tuỳ theo 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ã thông báo truy cập bằng cách sử dụng lệnh chuyển hướng trình duyệt đến Google, trong khi một ứng dụng được cài đặt trên thiết bị không có trình duyệt sẽ sử dụng các yêu cầu dịch vụ web.

Một số yêu cầu yêu cầu phải thực hiện bước xác thực khi 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 đượ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, thì 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ể sử dụng để lấy mã truy cập) và danh sách các phạm vi truy cập do mã đó 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, bạn nên yêu cầu phạm vi tăng dần, tại thời điểm cần quyền truy cập, thay vì yêu cầu 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"; hãy xem phần Uỷ 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 có trong phản hồi mã thông báo 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, tuỳ thuộc vào quyền truy cập vào một API liên quan của Google. Tắt mọi tính năng của ứng dụng không thể hoạt độ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 được yêu cầu. 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. Một API có thể ánh xạ nhiều giá trị chuỗi phạm vi đến 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ụ: 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 cho phép 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ã truy cập đến một API.

Sau khi nhận được mã truy cập, ứng dụng sẽ gửi mã đó đến một API của Google trong tiêu đề 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ể kết thúc trong các tệp nhật ký không hoàn toàn an toàn. Ngoài ra, bạn nên tránh tạo tên tham số URI không cần thiết khi sử dụng REST.

Mã thông báo truy cập chỉ hợp lệ cho tập hợp các 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ã này 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 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 có 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 hoạt động của một mã truy cập, thì ứ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 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ã 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 phải 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 vào API của Google. Sau khi mã truy cập hết hạn, ứng dụng sẽ 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 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 chỉ định rằng đây là Ứng dụng đã cài đặt, sau đó chọn Android, Ứng dụng Chrome, iOS, Nền tảng Windows phổ quát (UWP) hoặc Ứng dụng máy tính làm loại ứng dụng.

Quá trình này sẽ tạo ra một mã ứng dụng khách và trong một số trường hợp, một mã xác thực ứ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 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ý 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ả là một mã uỷ 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 phải 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 vào API của Google. Sau khi mã truy cập hết hạn, ứng dụng sẽ sử dụng mã làm mới để lấy mã mới.

Ứng dụng của bạn sẽ 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, đổi mã lấy mã thông báo và sử dụng mã thông báo đó để 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 đã 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 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ã thông báo 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 quy 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 đó để 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ó đầu vào bị hạn chế

Đ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ị có phương thức nhập hạn chế, 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 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 chứa một số tham số, trong đó có URL và mã mà ứng dụng hiển thị với 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 biệt có nhiều chức năng nhập 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ò ý kiến một URL của Google theo một khoảng thời gian cụ thể. 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ã truy cập và mã làm mới. Ứng dụng phải 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 vào API của Google. Sau khi mã thông báo truy cập hết hạn, ứng dụng sẽ sử dụng mã thông báo làm mới để lấy mã thông báo mới.

Người dùng đăng nhập trên một thiết bị riêng 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ư API dự đoán và Google Cloud Storage có thể thay mặt 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 của chính ứng dụng đó với API, nhưng không cần có 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ủa bạn 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 tương tác giữa máy chủ này, bạn cần có một tài khoản dịch vụ. Đây là tài khoản thuộc về ứng dụng của bạn thay vì thuộc về một người dùng cuối cá nhân. Ứng dụng của bạn thay mặt tài khoản dịch vụ gọi các API của Google và không yêu cầu người dùng đồ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ẽ thay mặt người dùng cuối gọi các API của Google và đôi khi cần 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 nhận được từ Google API Consolebao gồm một địa chỉ email được tạo duy nhất, mã ứng dụng và ít nhất một cặp khoá công khai/riêng tư. Bạn sử dụng mã ứng dụng 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 ở đị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ày tới Máy chủ uỷ quyền 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 vào 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 này.

Ứ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 đ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

Kích thước của mã thông báo có thể khác nhau, tối đa là các giới hạn sau:

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

Mã thông báo truy cập do 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ó giới hạn kích thước mã thông báo khác nhau. Để 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 phạm vi 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 biến đổi cho phù hợp.

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

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

Một dự án trên Google Cloud Platform có màn hình đồ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 phát hành là "Thử nghiệm" sẽ được cấp mã thông báo làm mới hết hạn trong 7 ngày, trừ phi các 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 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 mã ứng dụng khách OAuth 2.0. Nếu đạt đến giới hạn, việc tạo mã thông báo làm mới mới sẽ tự động vô hiệu hoá mã thông báo làm mới cũ nhất mà không cần 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, chúng tôi cũng đưa ra giới hạn lớn hơn về tổng số mã 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 thông 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 dùng để kiểm thử việc triển khai có thể sẽ vượt quá.

Nếu 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 ở 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 họ để uỷ quyền cho một số ứng dụng khách.

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

Quản trị viên của các tổ chức GCP có thể yêu cầu người dùng xác thực lại thường xuyên trong khi truy cập vào các tài nguyên GCP bằng cách sử dụ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 có 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ư khi mã thông báo 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ã 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 hạn chế (từ 1 giờ đến 24 giờ), nên bạn phải xử lý trường hợp này một cách linh hoạt bằng cách khởi động lại phiên xác thực.

Tương tự, bạn không được sử dụng hoặc khuyến khích việc 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 xác thực 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 trên 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 này dành cho quản trị viên.

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. Chúng tôi sẽ bổ sung thêm các tính năng khác vào thư viện theo thời gian.