Google cam kết nâng cao công bằng chủng tộc cho các cộng đồng Da đen. Xem làm thế nào.
Trang này được dịch bởi Cloud Translation API.
Switch to English

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

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

Để bắt đầu, hãy lấy bằng chứng xác thực ứng dụng khách OAuth 2.0 từ Google API Console . Sau đó, ứng dụng khách của bạn 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ã thông báo đến API Google mà bạn muốn truy cập. Để có minh chứng 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 khách hàng của riêng bạn), hãy thử nghiệm với Sân chơi OAuth 2.0 .

Trang này cung cấp tổng quan về các tình huống ủy quyền OAuth 2.0 mà Google hỗ trợ và cung cấp các 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 để xác thực, hãy xem OpenID Connect .

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

Tất cả các ứng dụng 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 năm bước:

1. Nhận 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 chẳng hạn như ID ứng dụng khách và bí mật ứng dụng khách mà cả Google và ứng dụng của bạn đều biết. Tập hợp các giá trị khác nhau dựa trên loại ứng dụng bạn đang xây dựng. Ví dụ, một ứng dụng JavaScript không yêu cầu bí mật, nhưng một ứng dụng máy chủ web thì có.

2. Lấy mã thông báo truy cập từ Máy chủ ủy quyền của Google.

Trước khi ứng dụng của bạn có thể truy cập dữ liệu riêng tư bằng API Google, ứng dụng phải có được mã thông báo truy cập cấp quyền truy cập vào API đó. Một mã thông báo truy cập duy nhất có thể cấp các mức độ truy cập khác nhau cho nhiều API. Một tham số biến được gọi là scope kiểm soát tập hợp tài nguyên và hoạt động mà mã thông báo truy cập cho phép. Trong quá trình yêu cầu mã thông báo 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 để thực hiện yêu cầu này và chúng khác nhau tùy thuộc vào 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 trình duyệt chuyển hướng đế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ử dụng các yêu cầu dịch vụ web.

Một số yêu cầu yêu cầu 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 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, Máy chủ ủy quyền của Google sẽ gửi cho ứng dụng của bạn mã thông báo truy cập (hoặc mã ủy quyền mà ứng dụng của bạn có thể sử dụng để lấy mã thông báo truy cập) và danh sách các phạm vi truy cập được cấp bởi mã thông báo đó. Nếu người dùng không cấp quyền, máy chủ sẽ trả về lỗi.

Thông thường, cách tốt nhất là yêu cầu phạm vi tăng dần, tại thời điểm bắt buộc phải truy cập, thay vì lên trước. Ví dụ: một ứng dụng muốn hỗ trợ lưu sự kiện vào lịch sẽ không yêu cầu quyền truy cập Lịch Google cho đến khi người dùng nhấn nút "Thêm vào Lịch"; xem Ủy quyền tăng dần .

3. Kiểm tra các phạm vi quyền truy cập được cấp bởi người dùng.

So sánh các phạm vi được bao gồm 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 các tính năng và chức năng của ứng dụng của bạn phụ thuộc vào quyền truy cập vào API Google có liên quan. Tắt bất kỳ tính năng nào 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 bao gồm 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. Tham khảo tài liệu cho từng API 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 vào 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ụ: Google People API 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 cho phạm vi https://www.google.com/m8/feeds/ ; phương thức people.updateContact của Google API 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 ứng dụng nhận được mã thông báo truy cập, ứng dụng sẽ gửi mã thông báo tới API Google trong tiêu đề 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 chúng tôi không khuyến khích việc này, vì các 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, thực hành REST tốt là tránh tạo các tên tham số URI không cần thiết. Lưu ý rằng hỗ trợ chuỗi truy vấn sẽ không còn được dùng vào ngày 1 tháng 6 năm 2021.

Mã thông báo truy cập chỉ hợp lệ cho tập hợp các hoạt động và tài nguyên được mô tả trong scope yêu cầu mã thông báo. Ví dụ: nếu mã thông báo truy cập được cấp cho API Lịch Google, nó 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ã thông báo 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ã thông báo truy cập, nếu cần.

Mã thông báo truy cập có vòng đời giới hạn. Nếu ứng dụng của bạn cần quyền truy cập vào API Google ngoài thời gian tồn tại của một mã thông báo truy cập duy nhất, nó 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 nhận được mã thông báo truy cập mới.

Các tình huống

Ứ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 các ngôn ngữ và khuôn khổ 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 URL Google; URL 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ý 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ể đổi lấy mã thông báo 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 trong tương lai và sử dụng mã truy cập để truy cập API Google. Khi mã thông báo 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ủ ủy quyền của Google, nhận mã ủy 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 Google.

Để biết chi tiết, hãy xem 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 ID ứ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 ứng dụng Android, Chrome, iOS, Universal Windows Platform (UWP) hoặc ứng dụng Máy tính để bàn làm loại ứng dụng.

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

Để biết chi tiết, hãy xem Sử dụng OAuth 2.0 cho các ứ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 URL Google; URL 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ý 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à khách hàng phải xác thực trước khi đưa nó 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 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 để gọi điểm cuối API Google.

Để biết chi tiết, hãy xem 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 hạn chế

Đ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 hạn chế như bảng điều khiển trò chơi, máy quay video và máy in.

Trình tự ủy quyền bắt đầu với việc ứng dụng thực hiện yêu cầu dịch vụ web tới URL của Google để có mã ủy 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 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 với khả năng nhập liệu phong phú hơn. Người dùng khởi chạy trình duyệt, điều hướng đến URL được chỉ định, đăng nhập và nhập mã.

Trong khi đó, ứng dụng sẽ thăm dò một URL của Google tại một khoảng thời gian nhất định. 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ã thông báo 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 trong tương lai và sử dụng mã truy cập để truy cập API Google. Khi mã thông báo 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ười dùng đăng nhập trên một thiết bị riêng có trình duyệt

Để biết chi tiết, hãy xem 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 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 phải chứng minh danh tính riêng của mình với API nhưng không cần sự đồng ý của người dùng. Tương tự, trong các tình huống 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 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ủ, 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 một 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 sự đồng ý của người dùng. (Trong các tình huống không phải tài khoản dịch vụ, ứng dụng của bạn 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 đăng nhập của tài khoản dịch vụ, mà bạn có được từ Google API Console, bao gồm địa chỉ email được tạo là duy nhất, ID khách hàng và ít nhất một cặp khóa công khai / riêng tư. Bạn sử dụng ID ứng dụng khách và một khóa cá nhân để tạo JWT đã ký và xây dựng 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 Máy chủ ủy quyền Google OAuth 2.0, máy chủ này sẽ trả về mã thông báo truy cập. Ứng dụng sử dụng mã thông báo để truy cập 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 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 điểm cuối API Google. Không có người dùng cuối nào tham gia.

Để biết chi tiết, hãy xem tài liệu dịch vụ-tài khoản .

Kích thước mã thông báo

Các mã thông báo có thể khác nhau về kích thước, tối đa 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 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 Google API OAuth 2.0 nhưng có giới hạn kích thước mã thông báo khác nhau. Để biết chi tiết, hãy xem tài liệu API .

Google bảo lưu 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ợ kích thước mã thông báo thay đổi tương ứng.

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

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

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

Dự án Google Cloud Platform có màn hình chấp thuận OAuth được định cấu hình cho kiểu người dùng bên ngoài và trạng thái xuất bản là "Đang thử nghiệm" sẽ được cấp 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 50 mã làm mới cho mỗi Tài khoản Google trên mỗi ID khách hà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 làm mất hiệu lực mã 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 các 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à 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 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 thì có thể.

Nếu bạn cần cấp quyền cho nhiều chương trình, máy móc hoặc thiết bị, một giải pháp là giới hạn số lượng khách hàng mà bạn ủy quyền cho mỗi Tài khoản Google ở ​​mức 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 chúng để ủy 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 các tổ chức GCP có thể yêu cầu xác thực lại thường xuyên người dùng khi họ truy cập 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, SDK đám mây của Google (còn được gọi là gcloud CLI) và bất kỳ ứng dụng OAuth nào của bên thứ ba yêu cầu phạm vi Nền tảng đám mây. 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, lệnh gọi API của bạn sẽ xảy ra lỗi tương tự như những gì sẽ xảy ra nếu mã thông báo làm mới bị thu hồi. Vì thời lượng phiên có thể rất hạn chế (trong khoảng từ 1 giờ đến 24 giờ), nên tình huống 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ự, 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ủ. 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 đang chạy lâu 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 đó, ứ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 khách hàng

Các thư viện khách sau tích hợp với các khuôn khổ phổ biến, giúp việc triển khai OAuth 2.0 đơn giản hơn. Nhiều tính năng sẽ được thêm vào các thư viện theo thời gian.