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

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

Để bắt đầu, hãy lấy thông tin đăng nhập ứng dụng OAuth 2.0 từ Google API Console. Sau đó, ứng dụng khách sẽ yêu cầu mã thông báo truy cập từ Máy chủ ủy quyền của Google, trích xuất mã thông báo từ phản hồi và gửi mã đó đến API Google mà bạn muốn truy cập. Để có minh họa tương tác về việc sử dụng OAuth 2.0 với Google (bao gồm 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 ủy quyền OAuth 2.0 mà Google hỗ trợ và 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 cho quá trình xác thực, hãy xem 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 API Google bằng OAuth 2.0. Ở cấp độ cao, bạn 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 để nhận thông tin đăng nhập OAuth 2.0 như mã ứng dụng và 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ị sẽ khác nhau tùy theo loại ứng dụng 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ó.

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

Có nhiều cách để đưa ra yêu cầu này. Những yêu cầu này sẽ khác nhau tùy theo loại ứng dụng bạn đang tạo. Ví dụ: ứng dụng JavaScript có thể yêu cầu mã truy cập bằng cách sử dụng lệnh chuyển hướng trình duyệt đến Google, trong khi ứng dụng được 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 mà 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 đượ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 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ủ ủy 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ột mã ủy 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 do mã đó cấp. Nếu người dùng không cấp quyền này, máy chủ sẽ trả về 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 yêu cầu quyền truy cập, thay vì lên trước. Ví dụ: một ứng dụng muốn hỗ trợ việc 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 phần Ủy 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 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, tùy thuộc vào quyền truy cập vào API Google có liên quan. Tắt mọi tính năng của ứng dụng mà 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 nội dung phản hồi, ngay cả khi người dùng cấp tất cả các phạm vi đã yêu cầu. Hãy tham khảo tài liệu về từng API Google để biết các phạm vi cần thiết để 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 là https://www.googleapis.com/auth/contacts khi một ứng dụng yêu cầu người dùng ủy quyền trong phạm vi https://www.google.com/m8/feeds/; phương thức API của Google People people.updateContact yêu cầu phạm vi https://www.googleapis.com/auth/contacts được cấp.

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

Sau khi nhận được mã truy cập, ứng dụng sẽ gửi mã đó đến một API Google trong tiêu đề yêu cầu Ủy quyền HTTP. Bạn có thể gửi mã thông báo dưới dạng thông số chuỗi truy vấn URI. Tuy nhiên, bạn không nên gửi thông số này vì thông số URI có thể trở thành tệp nhật ký không hoàn toàn an toàn. Ngoài ra, bạn cũng nên dùng phương thức Kiến trúc chuyển trạng thái đại diện (REST) để tránh tạo tên thông số URI không cần thiết.

Mã truy cập chỉ hợp lệ với 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ã đó 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 để thực hiện các thao tác tương tự.

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

Mã thông báo truy cập có giới hạn vòng đời. Nếu cần quyền truy cập vào một API Google sau suốt thời gian hoạt động của một mã truy cập, ứng dụng của bạn có thể lấy 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, chẳng hạn như PHP, Java, Python, Ruby và ASP.NET.

Trình tự ủy 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 đó bao gồm các tham số truy vấn cho biết loại quyền truy cập được yêu cầu. Google xử lý việc xác thực người dùng, lựa chọn phiên hoạt động 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 thành 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 trong tương lai 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 yêu cầu mã thông báo đến Máy chủ ủy quyền của Google,
 nhận mã ủy 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 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 đây là ứng dụng Đã cài đặt, sau đó chọn ứng dụng Android, Chrome, iOS, Universal Windows Platform (UWP) hoặc loại ứ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ột 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ự ủy 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 đó bao gồm các tham số truy vấn cho biết loại quyền truy cập được yêu cầu. Google xử lý việc xác thực người dùng, lựa chọn phiên hoạt động 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 thành 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 trong tương lai 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 yêu cầu mã thông báo đến Máy chủ ủy quyền của Google,
 nhận mã ủy 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ự ủy 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 đó bao gồm các tham số truy vấn cho biết loại quyền truy cập được yêu cầu. Google xử lý việc xác thực người dùng, lựa chọn phiên hoạt động và sự đồng ý của người dùng.

Kết quả là một mã truy cập mà ứng dụng phải xác thực trước khi đưa mã vào một 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.

Ứng dụng JS của bạn gửi một yêu cầu mã thông báo đến Máy chủ ủy quyền của Google,
                  nhận được một 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 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 phía máy khách.

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

Đ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 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 từ 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ố, bao gồm URL và mã mà ứng dụng hiển thị cho người dùng.

Người dùng nhận được URL và mã từ thiết bị, sau đó chuyển sang một thiết bị hoặc máy tính khác với khả năng nhập 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 sẽ thăm dò ý kiến của một URL 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 trong tương lai 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ụ

Những API của Google như API dự đoán và Google Cloud Storage có thể hoạt động 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 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 doanh nghiệp, ứng dụng của bạn có thể yêu cầu quyền truy cập được ủy quyền cho một số tài nguyên.

Đối với những loại tương tác từ máy chủ đến máy chủ, 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ì một người dùng cuối riêng lẻ. Ứng dụng của bạn gọi API Google thay mặt cho tài khoản dịch vụ và không cần phải có sự đồng ý của người dùng. (Trong các trường hợp không có 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 có sự đồng ý của người dù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 Consolesẽ bao gồm một địa chỉ email duy nhất, một 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 khóa riêng để 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 gửi yêu cầu mã thông báo đến Máy chủ ủy quyền Google OAuth 2.0 để trả về mã truy cập. Ứng dụng sẽ 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ủ ủy quyền của Google, sau đó sử dụng mã thông báo này để gọi một điểm cuối API của Google. Không
                    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ể khác nhau về kích thước, cho đến 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ã truy cập do Google Cloud cung cấp API API bảo mật có cấu trúc tương tự như mã truy cập OAuth 2.0 của API Google nhưng có giới hạn về kích thước mã. Để 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 có thể thay đổi cho phù hợp.

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

Bạn phải viết mã của mình để dự đoán khả năng một mã làm mới được 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 các lý do sau:

  • Người dùng đã thu hồi quyền truy cập của ứng dụng.
  • Mã thông báo làm mới đã không được sử dụng trong sáu tháng.
  • Người dùng đã thay đổi mật khẩu và mã làm mới chứa các phạm vi Gmail.
  • Tài khoản người dùng đã vượt quá số lượng mã làm mới (trực tiếp) được cấp tối đa.
  • Người dùng thuộc một tổ chức Google Cloud Platform đang thực hiện các chính sách kiểm soát phiên hoạt động.

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à "Test" được cấp một mã thông báo làm mới sẽ hết hạn sau 7 ngày.

Hiện có giới hạn là 50 mã làm mới cho mỗi Tài khoản Google trên mỗi mã ứng dụng 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 vô hiệu hóa 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 các tài khoản dịch vụ.

Ngoài ra, cũng có giới hạn lớn hơn đối với tổng số mã thông báo được 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ả cá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 một tài khoản nhà phát triển được dùng để thử nghiệm cách triển khai có thể thực hiện việc này.

Nếu bạn cần cho phép nhiều chương trình, máy hoặc thiết bị, thì một giải pháp là giới hạn số lượng máy khách mà bạn ủy quyền cho 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 của quản trị viên và sử dụng những đặc quyền này để cho phép một số khách hàng.

Xử lý các chính sách kiểm soát phiên đối với các tổ chức sử dụng 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 trong khi họ truy cập vào các tài nguyên GCP bằng tính năng kiểm soát phiên 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à 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 hoạt động 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_token; có thể dùng loại lỗi phụ để phân biệt mã thông báo thu hồi và lỗi do chính sách kiểm soát phiên. Vì thời lượng phiên có thể rất hạn chế (từ 1 giờ đến 24 giờ), nên trường hợp này phải được xử lý khéo léo bằng cách khởi động lại phiên xác thực.

Tương tự như vậy, bạn không được 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 máy chủ sang 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ủ để thực hiện các công việc hoặc thao tác 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ực hiện được 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 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 các thư viện theo thời gian.