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

Để 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 yêu cầu mã 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ã thông báo đến API của Google mà bạn muốn truy cập. Để xem phần minh hoạ có tính tương tác về việc 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 chính bạn), hãy thử nghiệm Playground 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 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. Ở cấp độ cao, hãy 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 đăng nhập OAuth 2.0 như mã ứng dụng khách và mật khẩu ứng dụng mà cả Google và ứng dụng của bạn đã biết. Tập hợp các giá trị này sẽ khác nhau tuỳ theo 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ó 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 nhận đượ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 khác nhau vào nhiều API. Một tham số biến có tên là scope sẽ kiểm soát nhóm 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 của bạn 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ỳ theo loại ứng dụng mà bạn đang xây dựng. 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ị mà không có trình duyệt nào sử dụng yêu cầu dịch vụ web.

Một số yêu cầu yêu cầu 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 hay 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, 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ó 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 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 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 quyền 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. Tắt mọi tính năng của ứng dụng không hoạt động được khi 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, 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ể ánh xạ nhiều giá trị chuỗi phạm vi đến 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 ứng dụng yêu cầu người dùng cấp quyền truy cập một phạm vi https://www.google.com/m8/feeds/; phương thức Google People API people.updateContact đòi hỏi 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 Google API 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 áp dụng một phương pháp REST để tránh tạo các tên tham số URI không cần thiết.

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

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) là một mật khẩu ứng dụng khách mà bạn sẽ nhúng vào mã nguồn của ứng dụng. (Trong trường hợp này, rõ ràng là khoá bí mật ứng dụng không được coi là khoá 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 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 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ẽ 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, đổi mã đó để lấy mã thông báo và 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 đã 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 một 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 nên 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ủ ủy 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 bài viết 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ó giới hạn đầu vào

Đ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ó đầ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ố, trong đó 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 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ò URL của Google theo 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ộ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ẽ sử dụng mã làm mới để lấy một 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ủ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 từ máy chủ đến 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 thay vì của từng người dùng cuối. Ứ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 là 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 phải có sự đồng ý của người dùng.)

Thông tin đăng nhập của tài khoản dịch vụ (bạn lấy từ Google API Console) bao gồm địa chỉ email được tạo và duy nhất, mã ứng dụng khách và ít nhất một cặp khoá 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 một JWT đã ký và tạo yêu cầu mã 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 OAuth 2.0 của Google. Máy chủ này sẽ trả về mã truy cập. Ứng dụng dùng mã thông báo này để truy cập vào một 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 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 đ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, theo 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ã 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ã truy cập OAuth 2.0 của Google API, nhưng có giới hạn kích thước mã thông báo khác. Để 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 các giới hạn này và ứng dụng của bạn phải hỗ trợ nhiều kích thước mã thông báo tương ứng.

Làm mới thời 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ấ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 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à "Thử nghiệm" sẽ được cấp một 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 phạm vi userinfo.email, userinfo.profile, openid hoặc tương đương của OpenID Connect).

Hiện tại, mỗi Tài khoản Google chỉ được có tối đa 100 mã làm mới/mã ứ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. Hạn mức này không áp dụng cho tài khoản dịch vụ.

Ngoài ra, cũng có 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ả khách hà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ử một cách triển khai có thể vượt quá giới hạn này.

Nếu bạn cần cấp quyền cho nhiều chương trình, máy hoặc thiết bị, thì có một giải pháp là giới hạn số lượng ứng dụng khách mà bạn cho phép 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à dùng những đặc quyền đó để 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 dùng 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 của 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 hết thời lượng phiên, các lệnh gọi API sẽ xảy ra lỗi tương tự như những gì 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 với loại lỗi invalid_grant; có thể sử 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"). Thời gian khởi động lại phiên có thể rất giới hạn (trong khoảng 4 giờ), quá trình xác thực phải được xử lý rất giới hạn trong 4 giờ.

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 xác thực 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 chính sách kiểm soát phiên cho 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 dành cho 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.