Tài liệu này giải thích cách các ứng dụng được cài đặt trên các thiết bị như điện thoại, máy tính bảng và máy tính sử dụng các điểm cuối OAuth 2.0 của Google để cho phép truy cập vào YouTube Analytics API hoặc YouTube Reporting API.
OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với một ứng dụng mà vẫn giữ kín tên người dùng, mật khẩu và các thông tin khác. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để được cấp quyền truy xuất dữ liệu YouTube Analytics của một kênh.
Các ứng dụng đã cài đặt được phân phối cho từng thiết bị và giả định rằng những ứng dụng này không thể giữ bí mật. Chúng có thể truy cập vào các API của Google trong khi người dùng đang ở trong ứng dụng hoặc khi ứng dụng đang chạy ở chế độ nền.
Quy trình uỷ quyền này tương tự như quy trình được dùng cho các ứng dụng máy chủ web. Điểm khác biệt chính là các ứng dụng đã cài đặt phải mở trình duyệt hệ thống và cung cấp một URI chuyển hướng cục bộ để xử lý các phản hồi từ máy chủ uỷ quyền của Google.
Thư viện và mẫu
Đối với các ứng dụng iOS, bạn nên sử dụng phiên bản mới nhất của SDK Đăng nhập bằng Google cho iOS. SDK xử lý việc uỷ quyền cho người dùng và dễ triển khai hơn so với giao thức cấp thấp được mô tả trong hướng dẫn này.
Đối với các ứng dụng chạy trên những thiết bị không hỗ trợ trình duyệt hệ thống hoặc có khả năng nhập liệu hạn chế (chẳng hạn như TV, máy chơi trò chơi, camera hoặc máy in), hãy xem OAuth 2.0 cho TV và thiết bị hoặc Đăng nhập trên TV và thiết bị đầu vào hạn chế.
Điều kiện tiên quyết
Bật API cho dự án của bạn
Mọi ứng dụng gọi API của Google đều cần bật các API đó trong API Console.
Cách bật một API cho dự án:
- Open the API Library trong Google API Console.
- If prompted, select a project, or create a new one.
- Sử dụng trang Thư viện để tìm và bật YouTube Analytics API cũng như API Báo cáo của YouTube. Nhiều ứng dụng truy xuất dữ liệu trong YouTube Analytics cũng tương tác với YouTube Data API. Tìm mọi API khác mà ứng dụng của bạn sẽ sử dụng và bật cả những API đó.
Tạo thông tin xác thực uỷ quyền
Mọi ứng dụng sử dụng OAuth 2.0 để truy cập vào các API của Google đều phải có thông tin xác thực uỷ quyền để xác định ứng dụng cho máy chủ OAuth 2.0 của Google. Các bước sau đây giải thích cách tạo thông tin đăng nhập cho dự án của bạn. Sau đó, các ứng dụng của bạn có thể sử dụng thông tin đăng nhập này để truy cập vào các API mà bạn đã bật cho dự án đó.
- Go to the Clients page.
- Nhấp vào Tạo ứng dụng.
- Các phần sau đây mô tả các loại ứng dụng mà máy chủ uỷ quyền của Google hỗ trợ. Chọn loại ứng dụng khách được đề xuất cho ứng dụng của bạn, đặt tên cho ứng dụng khách OAuth và đặt các trường khác trong biểu mẫu cho phù hợp.
iOS
- Chọn loại ứng dụng iOS.
- Nhập tên cho ứng dụng OAuth. Tên này xuất hiện trên Clients page của dự án để xác định ứng dụng khách.
- Nhập giá trị nhận dạng gói cho ứng dụng của bạn. Mã nhận dạng gói là giá trị của khoá CFBundleIdentifier trong tệp tài nguyên danh sách thuộc tính thông tin của ứng dụng (info.plist). Giá trị này thường xuất hiện trong ngăn General (Chung) hoặc ngăn Signing & Capabilities (Ký và chức năng) của trình chỉnh sửa dự án Xcode. Mã nhận dạng gói cũng xuất hiện trong phần Thông tin chung của trang Thông tin ứng dụng cho ứng dụng trên trang web App Store Connect của Apple.
Xác nhận rằng bạn đang sử dụng đúng mã nhận dạng gói cho ứng dụng của mình, vì bạn sẽ không thể thay đổi mã này nếu đang sử dụng tính năng App Check.
- (Không bắt buộc)
Nhập mã App Store của ứng dụng nếu ứng dụng được xuất bản trong App Store của Apple. Mã cửa hàng là một chuỗi số có trong mọi URL của Apple App Store.
- Mở ứng dụng Apple App Store trên thiết bị iOS hoặc iPadOS.
- Tìm ứng dụng của bạn.
- Chọn nút Chia sẻ (biểu tượng hình vuông và mũi tên lên).
- Chọn Sao chép đường liên kết.
- Dán đường liên kết đó vào một trình chỉnh sửa văn bản. Mã nhận dạng App Store là phần cuối cùng của URL.
Ví dụ:
https://apps.apple.com/app/google/id284815942
- (Không bắt buộc)
Nhập mã nhóm của bạn. Hãy xem phần Tìm mã nhận dạng nhóm trong tài liệu về Tài khoản nhà phát triển của Apple để biết thêm thông tin.
Lưu ý: Bạn phải điền vào trường Team ID nếu đang bật App Check cho ứng dụng của mình. - (Không bắt buộc)
Bật App Check cho ứng dụng iOS. Khi bạn bật App Check, dịch vụ Chứng thực ứng dụng của Apple sẽ được dùng để xác minh rằng các yêu cầu OAuth 2.0 bắt nguồn từ ứng dụng OAuth của bạn là chính hãng và đến từ ứng dụng của bạn. Điều này giúp giảm nguy cơ giả mạo ứng dụng. Tìm hiểu thêm về cách bật tính năng Kiểm tra ứng dụng cho ứng dụng iOS của bạn.
- Nhấp vào Tạo.
UWP
- Chọn loại ứng dụng Universal Windows Platform.
- Nhập tên cho ứng dụng OAuth. Tên này xuất hiện trên Clients page của dự án để xác định ứng dụng khách.
- Nhập mã nhận dạng gồm 12 ký tự của ứng dụng trên Microsoft Store. Bạn có thể tìm thấy giá trị này trong Microsoft Partner Center trên trang Nhận dạng ứng dụng trong phần Quản lý ứng dụng.
- Nhấp vào Tạo.
Đối với các ứng dụng UWP, URI chuyển hướng được tạo bằng cách sử dụng Mã nhận dạng bảo mật gói (SID) duy nhất của ứng dụng. Bạn có thể tìm thấy Package SID của ứng dụng trong tệp Package.appxmanifest trong dự án Visual Studio.
Khi tạo mã ứng dụng khách trong Google Cloud Console, bạn phải chỉ định URI chuyển hướng theo định dạng sau, sử dụng giá trị chữ thường của SID gói:
ms-app://YOUR_APP_PACKAGE_SID
Đối với các ứng dụng UWP, giản đồ URI tuỳ chỉnh không được dài hơn 39 ký tự, như được chỉ định trong tài liệu của Microsoft.
Xác định phạm vi truy cập
Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào những tài nguyên cần thiết, đồng thời cho phép người dùng kiểm soát mức độ truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể có mối quan hệ nghịch đảo giữa số lượng phạm vi được yêu cầu và khả năng nhận được sự đồng ý của người dùng.
Trước khi bắt đầu triển khai quy trình uỷ quyền OAuth 2.0, bạn nên xác định những phạm vi mà ứng dụng của bạn cần có quyền truy cập.
YouTube Analytics API sử dụng các phạm vi sau:
| Phạm vi | Mô tả |
|---|---|
https://www. |
Quản lý tài khoản YouTube của bạn |
https://www. |
Xem tài khoản YouTube của bạn |
https://www. |
Xem và quản lý tài sản cũng như nội dung được kết hợp của bạn trên YouTube |
https://www. |
Xem báo cáo của YouTube Analytics về tài chính và phi tài chính cho nội dung trên YouTube |
https://www. |
Xem báo cáo Analytics trên YouTube dành cho nội dung YouTube của bạn |
YouTube Reporting API sử dụng các phạm vi sau:
| Phạm vi | Mô tả |
|---|---|
https://www. |
Xem báo cáo của YouTube Analytics về tài chính và phi tài chính cho nội dung trên YouTube |
https://www. |
Xem báo cáo Analytics trên YouTube dành cho nội dung YouTube của bạn |
Tài liệu Phạm vi API OAuth 2.0 chứa danh sách đầy đủ các phạm vi mà bạn có thể dùng để truy cập vào các API của Google.
Lấy mã truy cập OAuth 2.0
Các bước sau đây cho biết cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để nhận được sự đồng ý của người dùng nhằm thực hiện một yêu cầu API thay cho người dùng. Ứng dụng của bạn phải có sự đồng ý đó thì mới có thể thực thi yêu cầu Google API cần có sự uỷ quyền của người dùng.
Bước 1: Tạo trình xác minh mã và thử thách
Google hỗ trợ giao thức Khoá bằng chứng để trao đổi mã (PKCE) nhằm giúp quy trình cài đặt ứng dụng an toàn hơn. Một trình xác minh mã riêng biệt được tạo cho mọi yêu cầu uỷ quyền và giá trị đã chuyển đổi của trình xác minh này (gọi là "code_challenge") sẽ được gửi đến máy chủ uỷ quyền để lấy mã uỷ quyền.
Tạo trình xác minh mã
code_verifier là một chuỗi ngẫu nhiên mật mã có entropy cao, sử dụng các ký tự không dành riêng [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", có độ dài tối thiểu là 43 ký tự và độ dài tối đa là 128 ký tự.
Trình xác minh mã phải có đủ tính ngẫu nhiên để khiến việc đoán giá trị trở nên bất khả thi.
Tạo thử thách mã
Chúng tôi hỗ trợ 2 phương thức tạo thử thách mã.
| Phương thức tạo mã xác thực | |
|---|---|
| S256 (nên dùng) | Thử thách mã là hàm băm SHA256 được mã hoá Base64URL (không có khoảng đệm) của trình xác minh mã.
|
| plain | Thử thách mã có cùng giá trị với trình xác minh mã được tạo ở trên.
|
Bước 2: Gửi yêu cầu đến máy chủ OAuth 2.0 của Google.
Để có được quyền truy cập người dùng, hãy gửi yêu cầu đến máy chủ xác thực của Google tại https://accounts.google.com/o/oauth2/v2/auth. Điểm cuối này xử lý việc tra cứu phiên hoạt động, xác thực người dùng và lấy sự đồng ý của người dùng. Điểm cuối này chỉ có thể truy cập được qua SSL và từ chối các kết nối HTTP (không phải SSL).
Máy chủ uỷ quyền hỗ trợ các tham số chuỗi truy vấn sau cho các ứng dụng đã cài đặt:
| Thông số | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Bắt buộc
Mã định danh khách hàng cho ứng dụng của bạn. Bạn có thể tìm thấy giá trị này trong Cloud Console Clients page. |
||||||||||||||||||
redirect_uri |
Bắt buộc
Xác định cách máy chủ ủy quyền của Google gửi phản hồi đến ứng dụng của bạn. Có một số tùy chọn chuyển hướng khả dụng cho các ứng dụng đã cài đặt và bạn sẽ thiết lập tùy chọn này.thông tin xác thực ủy quyền với một phương pháp chuyển hướng cụ thể trong tâm trí. Giá trị phải khớp chính xác với một trong các URI chuyển hướng được ủy quyền cho máy khách OAuth 2.0 mà bạn đã cấu hình trong Cloud Console
Clients pagecủa máy khách. Nếu giá trị này không khớp với một URI được uỷ quyền, bạn sẽ gặp lỗi Bảng dưới đây hiển thị giá trị tham số
|
||||||||||||||||||
response_type |
Bắt buộc
Xác định xem điểm cuối Google OAuth 2.0 có trả về mã uỷ quyền hay không. Đặt giá trị tham số thành |
||||||||||||||||||
scope |
Bắt buộc
Một danh sách các phạm vi được phân tách bằng dấu cách, xác định những tài nguyên mà ứng dụng của bạn có thể truy cập thay cho người dùng. Những giá trị này thông báo cho màn hình đồng ý mà Google hiển thị cho người dùng. Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào những tài nguyên cần thiết, đồng thời cho phép người dùng kiểm soát mức độ truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có mối quan hệ tỷ lệ nghịch giữa số lượng phạm vi được yêu cầu và khả năng nhận được sự đồng ý của người dùng. YouTube Analytics API sử dụng các phạm vi sau:
YouTube Reporting API sử dụng các phạm vi sau:
Tài liệu Phạm vi API OAuth 2.0 cung cấp danh sách đầy đủ các phạm vi mà bạn có thể sử dụng để truy cập vào các API của Google. |
||||||||||||||||||
code_challenge |
Recommended (Nên dùng)
Chỉ định một |
||||||||||||||||||
code_challenge_method |
Recommended (Nên dùng)
Chỉ định phương thức được dùng để mã hoá một |
||||||||||||||||||
state |
Recommended (Nên dùng)
Chỉ định mọi giá trị chuỗi mà ứng dụng của bạn dùng để duy trì trạng thái giữa yêu cầu uỷ quyền và phản hồi của máy chủ uỷ quyền.
Máy chủ trả về chính xác giá trị mà bạn gửi dưới dạng một cặp Bạn có thể sử dụng tham số này cho nhiều mục đích, chẳng hạn như chuyển hướng người dùng đến tài nguyên chính xác trong ứng dụng của bạn, gửi số chỉ dùng một lần và giảm thiểu hành vi giả mạo yêu cầu trên nhiều trang web. Vì |
||||||||||||||||||
login_hint |
Không bắt buộc
Nếu ứng dụng của bạn biết người dùng nào đang cố gắng xác thực, nó có thể sử dụng tham số này để cung cấp gợi ý cho Máy chủ xác thực của Google. Máy chủ sử dụng gợi ý này để đơn giản hóa quy trình đăng nhập bằng cách tự động điền vào trường email trong biểu mẫu đăng nhập hoặc bằng cách chọn phiên đăng nhập nhiều tài khoản phù hợp. Đặt giá trị tham số thành địa chỉ email hoặc mã định danh |
||||||||||||||||||
URL uỷ quyền mẫu
Các tab bên dưới hiển thị các URL ủy quyền mẫu cho các tùy chọn URI chuyển hướng khác nhau.
Mỗi URL yêu cầu quyền truy cập vào một phạm vi cho phép truy xuất báo cáo YouTube Analytics của người dùng.Các URL giống hệt nhau ngoại trừ giá trị của tham số redirect_uri. Các URL cũng chứa các tham số bắt buộc response_type và client_id cũng như tham số tùy chọn state. Mỗi URL đều chứa dấu xuống dòng và khoảng trắng để dễ đọc.
Lược đồ URI tùy chỉnh
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Địa chỉ IP vòng lặp
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Bước 3: Google yêu cầu người dùng đồng ý
Ở bước này, người dùng quyết định có cấp quyền truy cập được yêu cầu cho ứng dụng của bạn hay không. Ở giai đoạn này, Google sẽ hiển thị cửa sổ yêu cầu sự đồng ý, trong đó nêu tên ứng dụng của bạn và các dịch vụ API của Google mà ứng dụng đang yêu cầu quyền truy cập, cùng với thông tin xác thực của người dùng và tóm tắt phạm vi quyền truy cập được cấp. Sau đó, người dùng có thể đồng ý cấp quyền truy cập vào một hoặc nhiều phạm vi được ứng dụng của bạn yêu cầu hoặc từ chối yêu cầu đó.
Ứng dụng của bạn không cần làm gì ở giai đoạn này vì nó đang chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu quyền truy cập có được cấp hay không. Câu trả lời đó được giải thích ở bước tiếp theo.
Lỗi
Các yêu cầu gửi đến điểm cuối ủy quyền OAuth 2.0 của Google có thể hiển thị các thông báo lỗi cho người dùng thay vì quy trình xác thực và ủy quyền như mong đợi. Các mã lỗi thường gặp và giải pháp được đề xuất là:
admin_policy_enforced
Tài khoản Google không thể xác thực một hoặc nhiều phạm vi được yêu cầu do chính sách của quản trị viên Google Workspace. Xem bài viết trợ giúp Quản trị viên Google Workspace Kiểm soát ứng dụng bên thứ ba và ứng dụng nội bộ nào truy cập dữ liệu Google Workspace để biết thêm thông tin về cách quản trị viên có thể hạn chế quyền truy cập vào tất cả các phạm vi hoặc các phạm vi nhạy cảm và bị hạn chế cho đến khi quyền truy cập được cấp rõ ràng cho ID máy khách OAuth của bạn.
disallowed_useragent
Điểm cuối xác thực được hiển thị bên trong một trình duyệt nhúng mà Google không cho phép.Chính sách OAuth 2.0 .
Các nhà phát triển iOS và macOS có thể gặp lỗi này khi mở yêu cầu ủy quyền trongWKWebView.
Thay vào đó, các nhà phát triển nên sử dụng các thư viện iOS như Google Sign-In for iOS hoặc AppAuth for iOS của OpenID Foundation.
Các nhà phát triển web có thể gặp lỗi này khi ứng dụng iOS hoặc macOS mở một liên kết web thông thường trong trình duyệt nhúng và người dùng điều hướng đến điểm cuối xác thực OAuth 2.0 của Google từ trang web của bạn. Các nhà phát triển nên cho phép các liên kết chung mở trong trình xử lý liên kết mặc định của hệ điều hành, bao gồm cả hai.Liên kết phổ quát trình xử lý hoặc ứng dụng trình duyệt mặc định.SFSafariViewController Sử dụng thư viện cũng là một tùy chọn được hỗ trợ.
org_internal
ID máy khách OAuth trong yêu cầu là một phần của dự án giới hạn quyền truy cập vào Tài khoản Google trong một Tổ chức Google Cloud cụ thể. Để biết thêm thông tin về lựa chọn cấu hình này, hãy xem phần Loại người dùng trong bài viết trợ giúp Thiết lập màn hình đồng ý của OAuth.
deleted_client
Ứng dụng OAuth đang được dùng để đưa ra yêu cầu đã bị xoá. Bạn có thể xoá theo cách thủ công hoặc tự động trong trường hợp các ứng dụng không dùng đến . Bạn có thể khôi phục các ứng dụng khách đã xoá trong vòng 30 ngày kể từ ngày xoá. Tìm hiểu thêm .
invalid_grant
Nếu bạn đang sử dụng trình xác minh mã và thử thách, tham số code_callenge không hợp lệ hoặc bị thiếu. Hãy đảm bảo rằng tham số code_challenge được thiết lập chính xác.
Khi làm mới mã truy cập, mã có thể đã hết hạn hoặc đã bị vô hiệu hóa. Xác thực lại người dùng và yêu cầu người dùng đồng ý để lấy mã thông báo mới. Nếu bạn vẫn gặp lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã được định cấu hình đúng cách và bạn đang sử dụng đúng mã thông báo và tham số trong yêu cầu. Nếu không, tài khoản người dùng có thể đã bị xoá hoặc vô hiệu hoá.
redirect_uri_mismatch
redirect_uri được truyền trong yêu cầu uỷ quyền không khớp với URI chuyển hướng được uỷ quyền cho mã ứng dụng OAuth. Xem xét các URI chuyển hướng được uỷ quyền trong Google Cloud Console
Clients page.
Giá trị redirect_uri được truyền vào có thể không hợp lệ đối với loại máy khách.
Tham số redirect_uri có thể đề cập đến quy trình OAuth ngoài băng tần (OOB) đã ngừng hoạt động và không còn được hỗ trợ. Tham khảo hướng dẫn di chuyển để cập nhật quy trình tích hợp.
invalid_request
Đã xảy ra lỗi với yêu cầu mà bạn gửi. Điều này có thể là do một số nguyên nhân:
- Yêu cầu không được định dạng đúng cách
- Yêu cầu bị thiếu các tham số bắt buộc
- Yêu cầu này sử dụng phương thức xác thực mà Google không hỗ trợ. Hãy xác minh rằng quá trình tích hợp OAuth của bạn sử dụng phương pháp tích hợp được khuyến nghị.
- Đã sử dụng một lược đồ tùy chỉnh không được hỗ trợ cho URI chuyển hướng. Nếu bạn thấy thông báo lỗi Không hỗ trợ lược đồ URI tùy chỉnh trên ứng dụng Android hoặc Chrome, hãy tìm hiểu thêm về các giải pháp thay thế cho lược đồ URI tùy chỉnh.
Bước 4: Xử lý phản hồi từ máy chủ OAuth 2.0
Cách thức ứng dụng của bạn nhận được phản hồi xác thực phụ thuộc vào...lược đồ URI chuyển hướng mà nó sử dụng. Bất kể phương thức nào, phản hồi sẽ chứa mã xác thực (code) hoặc lỗi (error). Ví dụ, error=access_denied cho biết người dùng đã từ chối yêu cầu.
Nếu người dùng cấp quyền truy cập vào ứng dụng của bạn, bạn có thể đổi mã xác thực lấy mã truy cập và mã làm mới như mô tả ở bước tiếp theo.
Bước 5: Trao đổi mã uỷ quyền để lấy mã làm mới và mã truy cập
Để đổi mã uỷ quyền lấy mã truy cập, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt các tham số sau:
| Trường | |
|---|---|
client_id |
Mã ứng dụng khách nhận được từ Cloud Console Clients page. |
client_secret |
Không bắt buộc
Mã bí mật của khách hàng nhận được từ Cloud Console Clients page. |
code |
Mã xác thực được trả về từ yêu cầu ban đầu. |
code_verifier |
Trình xác minh mã bạn đã tạo ở Bước 1. |
grant_type |
Theo định nghĩa trong đặc tả OAuth 2.0, giá trị của trường này phải được đặt thành authorization_code. |
redirect_uri |
Một trong các URI chuyển hướng được liệt kê cho dự án của bạn trong Cloud Console
Clients page cho client_id đã cho. |
Đoạn mã sau đây hiển thị một yêu cầu mẫu:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google phản hồi yêu cầu này bằng cách trả về một đối tượng JSON chứa mã truy cập có thời hạn ngắn và mã làm mới.
Phản hồi bao gồm các trường sau:
Đoạn mã sau đây hiển thị một ví dụ về phản hồi:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Bước 6: Kiểm tra xem người dùng đã được cấp quyền truy cập vào những phạm vi nào.
Khi yêu cầu nhiều quyền (phạm vi), người dùng có thể không cấp cho ứng dụng của bạn quyền truy cập vào tất cả các quyền đó. Ứng dụng của bạn phải xác minh xem phạm vi quyền nào thực sự đã được cấp và xử lý khéo léo các tình huống khi một số quyền bị từ chối, thông thường bằng cách vô hiệu hóa các tính năng phụ thuộc vào các phạm vi quyền bị từ chối đó.
Tuy nhiên, vẫn có những ngoại lệ. Ứng dụng Google Workspace Enterprise vớiủy quyền trên toàn miền hoặc các ứng dụng được đánh dấu làĐáng tin cậy , bỏ qua màn hình xác nhận quyền truy cập chi tiết. Đối với các ứng dụng này, người dùng sẽ không thấy màn hình yêu cầu cấp quyền chi tiết. Thay vào đó, ứng dụng của bạn sẽ nhận được tất cả các phạm vi được yêu cầu hoặc không nhận được phạm vi nào.
Để biết thêm thông tin chi tiết, hãy xem bài viết Cách xử lý các quyền ở cấp độ chi tiết.
Để kiểm tra xem người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào một phạm vi cụ thể hay chưa, hãy kiểm tra trường scope trong phản hồi mã thông báo truy cập. Phạm vi quyền truy cập được cấp bởi access_token được thể hiện dưới dạng một danh sách các chuỗi ký tự phân cách bằng dấu cách và phân biệt chữ hoa chữ thường.
Ví dụ, phản hồi mã truy cập mẫu sau đây cho thấy người dùng đã cấp cho ứng dụng của bạn quyền truy cập chỉ đọc vào hoạt động Drive và sự kiện Lịch:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Gọi API của Google
Sau khi ứng dụng của bạn nhận được mã truy cập, bạn có thể dùng mã này để thực hiện các lệnh gọi đến một API của Google thay cho một tài khoản người dùng nhất định nếu(các) phạm vi truy cập mà API yêu cầu đã được cấp. Để thực hiện việc này, hãy thêm mã truy cập vào yêu cầu gửi đến API bằng cách thêm tham số truy vấn access_token hoặc giá trị tiêu đề HTTP Authorization Bearer. Khi có thể, bạn nên dùng tiêu đề HTTP vì chuỗi truy vấn thường xuất hiện trong nhật ký máy chủ. Trong hầu hết các trường hợp, bạn có thể sử dụng thư viện máy khách để thiết lập các cuộc gọi đến API của Google (ví dụ: khi gọi API YouTube Analytics).
Lưu ý rằng API YouTube Analytics không hỗ trợ quy trình tài khoản dịch vụ. API báo cáo của YouTube chỉ hỗ trợ tài khoản dịch vụ cho những chủ sở hữu nội dung YouTube sở hữu và quản lý nhiều kênh YouTube, chẳng hạn như các hãng thu âm và hãng phim.
Bạn có thể dùng thử tất cả các API của Google và xem phạm vi của các API đó tại OAuth 2.0 Playground.
Ví dụ về HTTP GET
Một cuộc gọi tới
reports.query điểm cuối (API YouTube Analytics) sử dụngAuthorization: Bearer Tiêu đề HTTP có thể trông như sau. Xin lưu ý rằng bạn cần chỉ định mã truy cập của riêng mình:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Sau đây là một lệnh gọi đến cùng một API cho người dùng đã xác thực bằng cách sử dụng tham số chuỗi truy vấn access_token:
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Ví dụ về curl
Bạn có thể kiểm thử các lệnh này bằng ứng dụng dòng lệnh curl. Sau đây là ví dụ sử dụng lựa chọn tiêu đề HTTP (nên dùng):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Hoặc, bạn có thể chọn tham số chuỗi truy vấn:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Làm mới mã truy cập
Mã truy cập sẽ hết hạn định kỳ và trở thành thông tin đăng nhập không hợp lệ cho một yêu cầu API có liên quan. Bạn có thể làm mới mã truy cập mà không cần nhắc người dùng cấp quyền (kể cả khi người dùng không có mặt) nếu bạn yêu cầu quyền truy cập ngoại tuyến vào các phạm vi được liên kết với mã thông báo.
Để làm mới mã truy cập, ứng dụng của bạn sẽ gửi một yêu cầu HTTPS POST đến máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token) có chứa các tham số sau:
| Trường | |
|---|---|
client_id |
Mã ứng dụng khách nhận được từ API Console. |
client_secret |
Không bắt buộc
Khoá bí mật của ứng dụng khách nhận được từ API Console.
(Biểu tượng |
grant_type |
Như được xác định trong quy cách OAuth 2.0, giá trị của trường này phải được đặt thành refresh_token. |
refresh_token |
Mã làm mới được trả về từ quá trình trao đổi mã uỷ quyền. |
Đoạn mã sau đây cho thấy một yêu cầu mẫu:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Miễn là người dùng chưa thu hồi quyền truy cập đã cấp cho ứng dụng, máy chủ mã thông báo sẽ trả về một đối tượng JSON chứa mã truy cập mới. Đoạn mã sau đây cho thấy một phản hồi mẫu:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "token_type": "Bearer" }
Xin lưu ý rằng có giới hạn về số lượng mã làm mới sẽ được cấp; một giới hạn cho mỗi tổ hợp ứng dụng/người dùng và một giới hạn khác cho mỗi người dùng trên tất cả các ứng dụng. Bạn nên lưu mã thông báo làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng chúng miễn là chúng còn hiệu lực. Nếu ứng dụng của bạn yêu cầu quá nhiều mã làm mới, thì ứng dụng có thể gặp phải những giới hạn này. Trong trường hợp đó, các mã làm mới cũ hơn sẽ ngừng hoạt động.
Thu hồi mã thông báo
Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào phần Cài đặt tài khoản. Hãy xem phần Xoá quyền truy cập của trang web hoặc ứng dụng trong tài liệu hỗ trợ Các trang web và ứng dụng của bên thứ ba có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.
Ứng dụng cũng có thể thu hồi quyền truy cập đã cấp cho ứng dụng đó theo phương thức có lập trình. Việc thu hồi theo chương trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá một ứng dụng hoặc các tài nguyên API mà ứng dụng yêu cầu đã thay đổi đáng kể. Nói cách khác, một phần của quy trình xoá có thể bao gồm một yêu cầu API để đảm bảo các quyền đã cấp cho ứng dụng trước đó sẽ bị xoá.
Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng của bạn sẽ gửi yêu cầu đến https://oauth2.googleapis.com/revoke và đưa mã thông báo vào làm một tham số:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Mã thông báo có thể là mã thông báo truy cập hoặc mã làm mới. Nếu mã thông báo là mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.
Nếu yêu cầu thu hồi được xử lý thành công, thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, mã trạng thái HTTP 400 sẽ được trả về cùng với mã lỗi.
Phương pháp chuyển hướng ứng dụng
Lược đồ URI tuỳ chỉnh
Các lược đồ URI tùy chỉnh là một hình thức liên kết sâu sử dụng lược đồ do người dùng tự định nghĩa để mở ứng dụng của bạn.
Giải pháp thay thế cho việc sử dụng lược đồ URI tùy chỉnh trên ứng dụng Chrome
Sử dụng API Nhận dạng Chrome để nhận phản hồi OAuth 2.0 trực tiếp vào ứng dụng của bạn, loại bỏ nhu cầu sử dụng URI chuyển hướng.
Địa chỉ IP vòng lặp (macOS, Linux, máy tính Windows)
Để nhận mã uỷ quyền bằng URL này, ứng dụng của bạn phải đang theo dõi trên máy chủ web cục bộ. Bạn có thể làm việc này trên nhiều nền tảng, nhưng không phải nền tảng nào cũng hỗ trợ. Tuy nhiên, nếu nền tảng của bạn hỗ trợ, thì đây là cơ chế được đề xuất để lấy mã uỷ quyền.
Khi nhận được phản hồi uỷ quyền, để có khả năng sử dụng tốt nhất, ứng dụng của bạn nên phản hồi bằng cách hiển thị một trang HTML hướng dẫn người dùng đóng trình duyệt và quay lại ứng dụng của bạn.
| Cách sử dụng được đề xuất | Các ứng dụng dành cho máy tính chạy macOS, Linux và Windows (nhưng không phải Universal Windows Platform) |
| Giá trị biểu mẫu | Đặt loại ứng dụng thành Ứng dụng dành cho máy tính. |
Sao chép/dán theo cách thủ công (Không dùng nữa)
Bảo vệ ứng dụng của bạn
Xác minh quyền sở hữu ứng dụng cho Chrome
Bạn có thể xác minh quyền sở hữu ứng dụng để giảm nguy cơ bị mạo danh ứng dụng.
Để hoàn tất quy trình xác minh, bạn sẽ sử dụng tài khoản nhà phát triển trên Cửa hàng Chrome trực tuyến. Bạn phải đáp ứng các yêu cầu sau đây để xác minh thành công:
- Bạn phải có một mục đã đăng ký trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến có cùng mã nhận dạng mục với ứng dụng OAuth của Tiện ích Chrome mà bạn đang hoàn tất quy trình xác minh.
- Bạn phải là nhà xuất bản của mặt hàng trên Cửa hàng Chrome trực tuyến. Tìm hiểu thêm về cách quản lý quyền truy cập trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến.
Trong mục Verify App Ownership (Xác minh quyền sở hữu ứng dụng) của ứng dụng Chrome Extension, hãy nhấp vào nút Verify Ownership (Xác minh quyền sở hữu) để hoàn tất quy trình xác minh.
Lưu ý: Sau khi cấp quyền truy cập vào tài khoản, hãy đợi vài phút rồi mới hoàn tất quy trình xác minh.
Nếu xác minh thành công, bạn sẽ nhận được một thông báo xác nhận rằng quy trình xác minh đã thành công. Nếu không, một lời nhắc lỗi sẽ xuất hiện.
Để khắc phục lỗi xác minh không thành công, hãy thử các cách sau:
- Đảm bảo rằng có một mục đã đăng ký trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến có cùng mã nhận dạng mục với ứng dụng OAuth của Tiện ích Chrome mà bạn đang hoàn tất quy trình xác minh.
- Đảm bảo rằng bạn là nhà xuất bản của ứng dụng, tức là bạn phải là nhà xuất bản cá nhân của ứng dụng hoặc là thành viên của nhóm nhà xuất bản ứng dụng. Tìm hiểu thêm về tính năng quản lý quyền truy cập trong Trang tổng quan dành cho nhà phát triển của Cửa hàng Chrome trực tuyến.
- Nếu bạn vừa cập nhật danh sách người phát hành nhóm, hãy xác minh rằng danh sách thành viên phát hành nhóm đã được đồng bộ hóa trong Bảng điều khiển dành cho nhà phát triển của Chrome Web Store. Tìm hiểu thêm Về việc đồng bộ hóa danh sách thành viên nhà xuất bản của bạn.
Kiểm tra ứng dụng (chỉ dành cho iOS)
Tính năng Kiểm tra ứng dụng giúp bảo vệ các ứng dụng iOS của bạn khỏi việc sử dụng trái phép bằng cách sử dụng dịch vụ Chứng thực ứng dụng của Apple để xác minh rằng các yêu cầu được gửi đến các điểm cuối Google OAuth 2.0 bắt nguồn từ các ứng dụng chính hãng của bạn. Điều này giúp giảm nguy cơ giả mạo ứng dụng.
Bật tính năng Kiểm tra ứng dụng cho thiết bị iOS của bạn.
Để kích hoạt thành công tính năng Kiểm tra ứng dụng cho máy khách iOS của bạn, cần đáp ứng các yêu cầu sau:- Bạn phải chỉ định ID nhóm cho ứng dụng iOS của mình.
- Bạn không được sử dụng ký tự đại diện trong ID gói vì nó có thể trỏ đến nhiều ứng dụng khác nhau. Điều này có nghĩa là ID gói không được bao gồm ký hiệu dấu sao (*).
Sau khi bật App Check, bạn sẽ bắt đầu thấy các chỉ số liên quan đến yêu cầu OAuth từ ứng dụng khách của mình trong chế độ chỉnh sửa của ứng dụng khách OAuth. Các yêu cầu từ các nguồn chưa được xác minh sẽ không bị chặn cho đến khi bạn thực thi Kiểm tra ứng dụng. Thông tin trên trang giám sát số liệu có thể giúp bạn xác định thời điểm bắt đầu thực thi.
Bạn có thể gặp lỗi liên quan đến tính năng Kiểm tra ứng dụng khi bật Kiểm tra ứng dụng cho ứng dụng iOS của mình. Để khắc phục các lỗi này, hãy thử các bước sau:
- Hãy kiểm tra xem ID gói và ID nhóm bạn đã chỉ định có hợp lệ hay không.
- Hãy đảm bảo rằng bạn không sử dụng ký tự đại diện cho ID gói.
Bắt buộc kiểm tra ứng dụng cho ứng dụng khách iOS của bạn
Việc bật Kiểm tra ứng dụng cho ứng dụng của bạn không tự động chặn các yêu cầu không được nhận dạng. Để kích hoạt tính năng bảo vệ này, hãy vào chế độ chỉnh sửa của ứng dụng iOS trên thiết bị của bạn. Tại đó, bạn sẽ thấy các chỉ số Kiểm tra ứng dụng ở bên phải trang, bên dưới phần Google Identity for iOS. Các chỉ số bao gồm thông tin sau:- Số lượng yêu cầu đã xác minh – những yêu cầu có mã thông báo App Check hợp lệ. Sau khi bạn bật tính năng kiểm tra ứng dụng (App Check), chỉ những yêu cầu thuộc danh mục này mới được chấp nhận.
- Số lượng yêu cầu chưa được xác minh: có thể là yêu cầu của khách hàng đã lỗi thời - các yêu cầu thiếu mã thông báo Kiểm tra Ứng dụng; các yêu cầu này có thể đến từ phiên bản cũ hơn của ứng dụng của bạn không bao gồm triển khai Kiểm tra Ứng dụng.
- Số lượng yêu cầu chưa được xác minh: yêu cầu nguồn gốc không xác định - các yêu cầu thiếu mã thông báo Kiểm tra ứng dụng và có vẻ như không đến từ ứng dụng của bạn.
- Số lượng yêu cầu chưa được xác minh: yêu cầu không hợp lệ - các yêu cầu có mã thông báo Kiểm tra Ứng dụng không hợp lệ, có thể đến từ một máy khách không xác thực đang cố gắng mạo danh ứng dụng của bạn hoặc từ các môi trường mô phỏng.
Để bắt buộc kiểm tra ứng dụng, hãy nhấp vào nút ENFORCE và xác nhận lựa chọn của bạn. Khi quá trình thực thi được kích hoạt, tất cả các yêu cầu chưa được xác minh từ khách hàng của bạn sẽ bị từ chối.
Lưu ý: sau khi bạn bật chế độ thực thi, có thể mất đến 15 phút thì các thay đổi mới có hiệu lực.
Không bắt buộc sử dụng App Check cho ứng dụng iOS
Việc hủy bỏ xác thực ứng dụng cho ứng dụng của bạn sẽ dừng việc thực thi và cho phép tất cả các yêu cầu từ máy khách của bạn đến các điểm cuối Google OAuth 2.0, bao gồm cả các yêu cầu chưa được xác minh.
Để hủy kích hoạt Kiểm tra ứng dụng cho ứng dụng iOS của bạn, hãy điều hướng đến chế độ chỉnh sửa của ứng dụng iOS và nhấp vào nút UNENFORCE rồi xác nhận lựa chọn của bạn.
Lưu ý: Sau khi hủy kích hoạt Kiểm tra ứng dụng, có thể mất đến 15 phút để các thay đổi có hiệu lực.
Tắt tính năng Kiểm tra ứng dụng cho thiết bị iOS của bạn.
Việc tắt tính năng Kiểm tra ứng dụng (App Check) cho ứng dụng của bạn sẽ dừng tất cả quá trình giám sát của Kiểm tra ứng dụng.thực thi . Hãy cân nhắc việc không bắt buộc Kiểm tra ứng dụng để bạn có thể tiếp tục theo dõi các chỉ số cho khách hàng của mình.
Để tắt Kiểm tra ứng dụng cho ứng dụng iOS của bạn, hãy điều hướng đến chế độ chỉnh sửa của ứng dụng iOS và tắt nút chuyển đổi Bảo vệ ứng dụng OAuth của bạn khỏi bị lạm dụng với Firebase App Check.
Lưu ý: Sau khi tắt Kiểm tra ứng dụng, có thể mất đến 15 phút để các thay đổi có hiệu lực.
Truy cập theo thời gian
Quyền truy cập theo thời gian cho phép người dùng cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu của họ trong một khoảng thời gian giới hạn để hoàn thành một hành động nào đó. Tính năng cấp quyền truy cập theo thời gian có sẵn trong một số sản phẩm của Google trong quá trình xác nhận quyền, cho phép người dùng tùy chọn cấp quyền truy cập trong một khoảng thời gian giới hạn. Một ví dụ là API về khả năng chuyển dữ liệu cho phép chuyển dữ liệu một lần.
Khi người dùng cấp cho ứng dụng của bạn quyền truy cập dựa trên thời gian, mã thông báo làm mới sẽ hết hạn sau khoảng thời gian được chỉ định. Lưu ý rằng mã thông báo làm mới có thể bị vô hiệu hóa sớm hơn trong những trường hợp cụ thể; xem các trường hợp này để biết chi tiết. Trường refresh_token_expires_in được trả về trong phản hồi trao đổi mã ủy quyền thể hiện thời gian còn lại cho đến khi mã thông báo làm mới hết hạn trong những trường hợp như vậy.
Tài liệu đọc thêm
Tiêu chuẩn thực hành tốt nhất hiện hành của IETF OAuth 2.0 cho ứng dụng gốc thiết lập nhiều tiêu chuẩn thực hành tốt nhất được ghi lại ở đây.
Triển khai bảo vệ tài khoản chéo
Một bước bổ sung bạn nên thực hiện để bảo vệ tài khoản người dùng là triển khai tính năng Bảo vệ liên tài khoản bằng cách sử dụng Dịch vụ Bảo vệ liên tài khoản của Google. Dịch vụ này cho phép bạn đăng ký nhận thông báo về sự kiện bảo mật. Thông báo này cung cấp cho ứng dụng của bạn thông tin về những thay đổi lớn đối với tài khoản người dùng. Sau đó, bạn có thể sử dụng thông tin đó để hành động tùy thuộc vào cách bạn quyết định phản ứng với các sự kiện.
Một số ví dụ về các loại sự kiện được Dịch vụ Bảo vệ Tài khoản Liên kết của Google gửi đến ứng dụng của bạn là:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Xem trang Bảo vệ tài khoản người dùng bằng Bảo vệ liên tài khoản để biết thêm thông tin về cách triển khai Bảo vệ liên tài khoản và danh sách đầy đủ các sự kiện có sẵn.