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, chẳng hạn như các trường hợp dành cho ứng dụng máy chủ web, phía máy khách, đã cài đặt và thiết bị đầu vào giới hạn ứng dụng.
Để bắt đầu, hãy lấy thông tin đăng nhập ứng dụng OAuth 2.0 từ Bảng điều khiển API của Google. Sau đó, ứng dụng 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 của Google mà bạn muốn truy cập. Để xem bản minh hoạ 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 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 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 sẽ thực hiện 5 bước:
1. Lấy thông tin đăng nhập OAuth 2.0 từ Bảng điều khiển API của Google.
Truy cập vào Bảng điều khiển API của Google để lấy thông tin đăng nhập OAuth 2.0, chẳng hạn 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 các giá trị sẽ khác nhau 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 mật khẩu, 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 của bạn sẽ chạy, ví dụ:
-
Đối với ứng dụng Android, hãy sử dụng loại ứng dụng
Android . -
Đối với ứng dụng iOS và macOS, hãy sử dụng
loại ứng dụng iOS . -
code
Đối với ứng dụng web phía máy chủ hoặc JavaScript, hãy sử dụng loại ứng dụng
Web . Không sử dụng loại ứng dụng này cho bất kỳ ứng dụng nào khác, chẳng hạn như ứng dụng gốc hoặc ứng dụng di động. - chrome_extension Đối với tiện ích Chrome, hãy sử dụng loại ứng dụng Tiện ích Chrome.
-
tv
Đối với các thiết bị đầu vào giới hạn, chẳng hạn như TV hoặc thiết bị nhúng, hãy sử dụng loại ứng dụng
TV và thiết bị đầu vào giới hạn . - host Đối với các tương tác giữa máy chủ với máy chủ, hãy sử dụng tài khoản dịch vụ. Không cần có Mã ứng dụng OAuth.
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 mã 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. Một tham số biến có tên là scope kiểm soát tập hợp
các tài nguyên và thao tác mà mã truy cập cho phép. Trong quá trình 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ó nhiều cách để đưa ra yêu cầu này và các cách này sẽ khác nhau tuỳ thuộc vào loại ứng dụng 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 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 các yêu cầu dịch vụ web. Để biết thêm thông tin về cách đưa ra yêu cầu, hãy xem Scenarios và hướng dẫn triển khai chi tiết cho từng loại ứng dụng.
Một số yêu cầu cần có 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 liệu 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ể dùng để lấy mã truy cập) và danh sách các phạm vi truy cập do mã thông báo đó cấp. Nếu người dùng không cấp quyền, thì máy chủ sẽ trả về lỗi.
Bạn nên yêu cầu phạm vi theo từng bước, vào thời điểm cần truy cập, thay vì yêu cầu trước. Ví dụ: ứng dụng muốn hỗ trợ lưu sự kiện vào lịch không nên yêu cầu quyền truy cập vào Lịch Google cho đến khi người dùng nhấn vào nút "Thêm vào Lịch"; hãy xem Uỷ quyền theo từng bước.
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ã truy cập với các phạm vi cần thiết để truy cập 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 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 có trong yêu cầu của bạn có thể không khớp với phạm vi có 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 cho 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ể 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ụ: Google People API 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 uỷ quyền
cho phạm vi https://www.google.com/m8/feeds/; phương thức
people.updateContact
của Google People API 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 ứng dụng lấy được mã truy cập, ứng dụng sẽ gửi mã đó đến một API của 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ì các tham số URI có thể xuất hiện 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 theo phương pháp hay nhất về REST.
Mã truy cập chỉ hợp lệ đối 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 Google Calendar API, thì mã đó sẽ không cấp quyền truy cập vào Google Contacts API. Tuy nhiên, bạn có thể gửi mã truy cập đó đến Google Calendar API 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 giới hạn. Nếu cần truy cập vào một API của Google ngoài thời gian tồn tại 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ã làm mới mã thông báo cho phép ứng dụng của bạn lấy mã truy cập mới.
Scenarios
Các trường hợp này mô tả cách sử dụng OAuth 2.0 để yêu cầu mã uỷ quyền và lấy mã truy cập cũng như mã làm mới cho nhiều loại ứng dụ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ý quy trình 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 token.
Ứ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 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.
Để 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 tạo mã ứng dụng thông qua Bảng điều khiển API của Google, hãy chỉ định rằng đây là Ứng dụng đã cài đặt, sau đó chọn Ứng dụng Android, Tiện ích Chrome, Ứng dụng iOS, hoặc Ứng dụng dành cho máy tính làm loại ứng dụng.
Quá trình này sẽ tạo ra mã ứng dụng và trong một số trường hợp là mật khẩu ứng dụng 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 rõ ràng không được coi là mật khẩu.)
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ý quy trình 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. Ứng dụng nên xác thực mã truy cập trước khi đưa mã đó vào yêu cầu API của Google request. Khi mã thông báo hết hạn, ứng dụng sẽ lặp lại quy trình.
Bạn có thể chọn để máy chủ phụ trợ đổi mã uỷ quyền lấy mã làm mới, lưu trữ mã đó ở một vị trí an toàn. Sau khi mã truy cập hết hạn, máy chủ phụ trợ sẽ sử dụng mã làm mới để lấy mã mới cho ứng dụng.
Để biết thông tin chi tiết, hãy xem bài viết Uỷ quyền truy cập vào dữ liệu người dùng của Google cho Android, và OAuth 2.0 cho ứng dụng iOS và ứng dụng dành cho máy tính.
Ứ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ý quy trình 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 mã đó 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.
Để biết thông tin chi tiết, hãy xem bài viết Using OAuth 2.0 for Applications phía máy khách.
Ứng dụng trên thiết bị đầ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, 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 khi ứng dụng đưa ra 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 a 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 biệt có nhiều tính năng đầu vào hơn. Người dùng chạy trình duyệt, chuyển đến URL đã chỉ định, đăng nhập và nhập mã.
Trong khi đó, ứng dụng sẽ thăm dò một 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ã truy cập và mã làm mới token. Ứ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 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.
Để biết thông tin chi tiết, hãy xem bài viết 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ể thay mặt ứng dụng của bạn hoạt động 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 riêng mình 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 dành cho 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ủ với 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ì thuộc về 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à không cần 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 các 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 lấy từ Bảng điều khiển API của Google bao gồm địa chỉ email đã 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ã 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 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 sử dụng mã thông báo để 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.
Để 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ó nhiều kích thước, tối đa theo các giới hạn sau:
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 API Google nhưng có các giới hạn về 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 có 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ợ các kích thước mã thông báo thay đổi tương ứng.
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ã 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 những lý do sau:
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 phát hành là "Đang thử nghiệm" sẽ được cấp mã làm mới hết hạn sau 7 ngày, trừ phi các phạm vi OAuth được yêu cầu chỉ 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 OpenID Connect tương đương).
Hiện tại, mỗi Tài khoản Google có giới hạn 100 mã làm mới cho mỗi mã ứng dụng 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ã làm mới 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òn có một giới hạn lớn hơn về tổng số mã làm mới mà 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 của nhà phát triển dùng để kiểm thử quá trình triển khai có thể vượt quá.
Nếu bạn cần uỷ quyền cho 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 ứng dụng mà bạn uỷ quyền cho mỗi Tài khoản Google là 15 hoặc 20. Nếu bạn 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.
Xử lý các chính sách kiểm soát phiên cho 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 người dùng xác thực lại thường xuyên khi
họ truy cập vào tài nguyê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 Bảng điều khiển Google Cloud,
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 a
người dùng có 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 của bạn sẽ gặp lỗi tương tự như trường hợp 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; bạn 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"). 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 phù hợp 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 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ủ triển khai. 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 thao tác 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ì 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 triển khai OAuth 2.0 dễ dàng hơn. Các tính năng khác sẽ được thêm vào thư viện theo thời gian.
- Thư viện xác thực của Google cho Java
- Thư viện ứng dụng API của Google cho Python
- Thư viện ứng dụng API của Google cho Dart
- Thư viện ứng dụng API của Google cho Go
- Thư viện ứng dụng API của Google cho .NET
- Thư viện ứng dụng API của Google cho Ruby
- Thư viện ứng dụng API của Google cho PHP
- Thư viện ứng dụng API của Google cho JavaScript
- GTMAppAuth – Thư viện ứng dụng OAuth cho Mac và iOS