Tài liệu này giải thích cách triển khai việc uỷ quyền của OAuth 2.0 để truy cập YouTube Data API từ một ứng dụng web JavaScript. OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với ứng dụng trong khi vẫn giữ tên người dùng, mật khẩu và các thông tin khác của ứng dụng riêng tư thông tin. Ví dụ: một ứng dụng có thể dùng OAuth 2.0 để có được quyền để truy xuất dữ liệu YouTube của một kênh.
Quy trình OAuth 2.0 này được gọi là quy trình cấp quyền ngầm ẩn. Ứng dụng được thiết kế cho các ứng dụng chỉ truy cập API khi người dùng có mặt ở ứng dụng. Các các ứng dụng không thể lưu trữ thông tin bí mật.
Trong quy trình này, ứng dụng của bạn sẽ mở một URL của Google sử dụng các tham số truy vấn để nhận dạng ứng dụng và loại quyền truy cập API mà ứng dụng yêu cầu. Bạn có thể mở URL trong trình duyệt hiện tại hoặc cửa sổ bật lên. Người dùng có thể xác thực với Google và cấp các quyền được yêu cầu. Sau đó, Google sẽ chuyển hướng người dùng quay lại ứng dụng của bạn. Hoạt động chuyển hướng này bao gồm mã truy cập ứng dụng của bạn xác minh rồi dùng để đưa ra yêu cầu API.
Thư viện ứng dụng API của Google và Dịch vụ nhận dạng của Google
Nếu bạn sử dụng thư viện ứng dụng API của Google cho JavaScript để thực hiện cuộc gọi được uỷ quyền tới Google, bạn nên sử dụng Thư viện JavaScript cho Dịch vụ nhận dạng của Google để xử lý quy trình OAuth 2.0. Vui lòng xem Google Dịch vụ nhận dạng mã thông báo, tức là dựa trên quy trình cấp quyền ngầm của OAuth 2.0.
Điều kiện tiên quyết
Bật API cho dự án của bạn
Bất kỳ ứng dụng nào gọi Google API đều cần bật các API đó trong API Console.
Cách bậ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 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ác API đó.
Tạo thông tin xác thực cho phép
Mọi ứng dụng sử dụng OAuth 2.0 để truy cập API Google đều phải có thông tin xác thực uỷ quyền xác định ứng dụng tới máy chủ OAuth 2.0 của Google. Các bước sau đây sẽ giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, ứng dụng của bạn có thể sử dụng thông tin xác thực để truy cập API mà bạn đã bật cho dự án đó.
- Go to the Credentials page.
- Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
- Chọn loại ứng dụng Web application (Ứng dụng web).
- Hoàn thành biểu mẫu. Ứng dụng sử dụng JavaScript để đưa ra các yêu cầu API của Google được uỷ quyền phải chỉ định nguồn gốc JavaScript được phép. Nguồn gốc xác định miền từ mà ứng dụng của bạn có thể gửi yêu cầu đến máy chủ OAuth 2.0. Những nguồn gốc này phải tuân thủ tuân theo quy tắc xác thực của Google.
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 các tài nguyên mà ứng dụng cần trong khi cho phép người dùng kiểm soát lượng truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể là mối quan hệ nghịch đảo giữa số phạm vi được yêu cầu và khả năng lấy sự đồng ý của người dùng.
Trước khi bắt đầu triển khai việc uỷ quyền OAuth 2.0, bạn nên xác định các phạm vi mà ứng dụng của bạn cần có quyền để truy cập.
YouTube Data API phiên bản 3 sử dụng các phạm vi sau:
| Kính ngắm | |
|---|---|
| https://www.googleapis.com/auth/youtube | Quản lý tài khoản YouTube của bạn |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | Xem danh sách các hội viên đang hoạt động trên kênh của bạn, cấp độ hiện tại của họ và thời điểm họ trở thành hội viên |
| https://www.googleapis.com/auth/youtube.force-ssl | Xem, chỉnh sửa và xóa vĩnh viễn các video, mức xếp hạng, ý kiến nhận xét và phụ đề của bạn trên YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Xem tài khoản YouTube của bạn |
| https://www.googleapis.com/auth/youtube.upload | Quản lý video trên YouTube của bạn |
| https://www.googleapis.com/auth/youtubepartner | 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.googleapis.com/auth/youtubepartner-channel-audit | Xem thông tin riêng tư trên kênh YouTube của bạn có liên quan trong quá trình kiểm tra với đối tác YouTube |
Tài liệu về Phạm vi API của OAuth 2.0 chứa thông tin đầy đủ danh sách phạm vi mà bạn có thể dùng để truy cập 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 để lấy sự đồng ý của người dùng để thực hiện yêu cầu API thay mặt cho người dùng đó. Ứng dụng của bạn phải có trước khi có thể thực thi yêu cầu API của Google cần người dùng cho phép.
Bước 1: Chuyển hướng tới máy chủ OAuth 2.0 của Google
Để yêu cầu quyền truy cập vào dữ liệu của người dùng, hãy chuyển hướng người dùng đến OAuth 2.0 của Google máy chủ.
Điểm cuối OAuth 2.0
Tạo một URL để yêu cầu quyền truy cập từ điểm cuối OAuth 2.0 của Google tại
https://accounts.google.com/o/oauth2/v2/auth. Có thể truy cập vào điểm cuối này qua HTTPS;
các kết nối HTTP đơn thuần bị từ chối.
Máy chủ uỷ quyền của Google hỗ trợ các tham số chuỗi truy vấn sau cho web ứng dụng máy chủ:
| Tham số | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Bắt buộc
Mã ứng dụng khách cho ứng dụng của bạn. Bạn có thể tìm thấy giá trị này trong API Console Credentials page. |
||||||||||||||||
redirect_uri |
Bắt buộc
Xác định nơi máy chủ API chuyển hướng người dùng sau khi người dùng hoàn tất
quy trình uỷ quyền. Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được phép cho
ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong
API Console
Credentials page. Nếu giá trị này không khớp với
URI chuyển hướng được uỷ quyền cho Lưu ý rằng giao thức |
||||||||||||||||
response_type |
Bắt buộc
Các ứng dụng JavaScript cần đặt giá trị của thông số thành |
||||||||||||||||
scope |
Bắt buộc
Đáp phân tách bằng dấu cách danh sách phạm vi xác định tài nguyên mà ứng dụng của bạn có thể truy cập trên thay mặt cho người dùng. Các giá trị này cho biết màn hình xin phép 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 mà ứng dụng cần đồng thời vẫn cho phép người dùng kiểm soát lượng quyền truy cập mà họ cấp cho . Do đó, có mối quan hệ nghịch đảo giữa số phạm vi được yêu cầu và khả năng có được sự đồng ý của người dùng. YouTube Data API phiên bản 3 sử dụng các phạm vi sau:
Tài liệu về Phạm vi API của OAuth 2.0 cung cấp danh sách đầy đủ các phạm vi mà bạn có thể dùng để truy cập các API của Google. Ứng dụng của bạn nên yêu cầu quyền truy cập vào phạm vi uỷ quyền theo ngữ cảnh bất cứ khi nào có thể. Bằng cách yêu cầu quyền truy cập vào dữ liệu người dùng theo bối cảnh, thông qua uỷ quyền gia tăng, bạn giúp người dùng dễ dàng hiểu lý do ứng dụng của bạn cần quyền truy cập mà ứng dụng đang yêu cầu. |
||||||||||||||||
state |
Recommended (Nên dùng)
Chỉ định bất kỳ giá trị chuỗi nào mà ứng dụng của bạn sử 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ề giá trị chính xác mà bạn gửi dưới dạng một cặp Bạn có thể sử dụng thông số này cho một số mục đích, chẳng hạn như hướng người dùng đến
tài nguyên chính xác trong ứng dụng, gửi số chỉ dùng một lần và giảm thiểu yêu cầu trên nhiều trang web
giả mạo. Vì có thể đoán được |
||||||||||||||||
include_granted_scopes |
Không bắt buộc
Cho phép các ứng dụng sử dụng chế độ uỷ quyền gia tăng để yêu cầu quyền truy cập vào các
phạm vi theo ngữ cảnh. Nếu bạn đặt giá trị của thông số này thành |
||||||||||||||||
enable_granular_consent |
Không bắt buộc
Giá trị mặc định là Khi Google bật các quyền chi tiết cho một ứng dụng, tham số này sẽ không không còn tác dụng. |
||||||||||||||||
login_hint |
Không bắt buộc
Nếu biết người dùng nào đang cố gắng xác thực, ứng dụng của bạn có thể sử dụng thông 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 giản hoá quy trình đăng nhập bằng cách điền sẵn 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 thích hợp. Đặt giá trị thông số thành một địa chỉ email hoặc giá trị nhận dạng |
||||||||||||||||
prompt |
Không bắt buộc
Danh sách câu lệnh, phân tách bằng dấu cách, phân biệt chữ hoa chữ thường để trình bày cho người dùng. Nếu không chỉ định tham số này, người dùng sẽ chỉ được nhắc vào lần đầu tiên dự án của bạn yêu cầu quyền truy cập. Xem Nhắc tôi đồng ý lại để biết thêm thông tin. Các giá trị có thể là:
|
||||||||||||||||
Mẫu chuyển hướng đến máy chủ uỷ quyền của Google
Dưới đây là ví dụ về URL, có ngắt dòng và khoảng trắng để dễ đọc. Các yêu cầu URL
quyền truy cập vào phạm vi cho phép truy xuất dữ liệu YouTube của người dùng. Chiến lược này sử dụng các giá trị gia tăng
uỷ quyền (include_granted_scopes=true) để đảm bảo rằng mã truy cập mới
bao gồm mọi phạm vi mà trước đây người dùng đã cấp quyền truy cập cho ứng dụng. Một số tài khoản khác
các tham số cũng được đặt trong ví dụ này.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& client_id=client_id
Sau khi bạn tạo URL yêu cầu, hãy chuyển hướng người dùng đến URL đó.
Mã mẫu JavaScript
Đoạn mã JavaScript sau đây cho biết cách bắt đầu quy trình uỷ quyền trong JavaScript mà không sử dụng Thư viện ứng dụng API của Google cho JavaScript. Vì OAuth này Điểm cuối 2.0 không hỗ trợ Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), đoạn mã sẽ tạo một biểu mẫu này mở yêu cầu đến điểm cuối đó.
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauthSignIn() {
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create <form> element to submit parameters to OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': 'YOUR_CLIENT_ID',
'redirect_uri': 'YOUR_REDIRECT_URI',
'response_type': 'token',
'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
'include_granted_scopes': 'true',
'state': 'pass-through value'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
Bước 2: Google nhắc người dùng đồng ý
Ở bước này, người dùng sẽ quyết định xem có cấp cho ứng dụng của bạn quyền truy cập mà bạn yêu cầu hay không. Lúc này giai đoạn này, Google sẽ cho thấy một cửa sổ đồng ý cho thấy tên ứng dụng của bạn và Google API các dịch vụ mà nhà cung cấp đó đang yêu cầu cấp quyền truy cập bằng thông tin xác thực ủy quyền của người dùng và phần tóm tắt các phạm vi truy cập đã được cấp. Chiến lược phát hành đĩa đơn 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 mà ứ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ì đang chờ phản hồi từ Máy chủ OAuth 2.0 của Google cho biết liệu có bất kỳ quyền truy cập nào được cấp hay không. Câu trả lời đó được giải thích bằng bước sau đây.
Lỗi
Các yêu cầu gửi đến điểm cuối uỷ quyền OAuth 2.0 của Google có thể hiển thị thông báo lỗi mà người dùng nhìn thấy thay vì các quy trình xác thực và uỷ quyền dự kiến. Các mã lỗi phổ biến và nội dung đề xuất được liệt kê dưới đây.
admin_policy_enforced
Tài khoản Google không thể cho phép một hoặc nhiều phạm vi đã yêu cầu do các chính sách của quản trị viên Google Workspace của họ. Xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát bên thứ ba và các ứng dụng nội bộ truy cập vào dữ liệu trong 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 dữ liệu nhạy cảm và phạm vi bị hạn chế cho đến khi bạn cấp quyền truy cập rõ ràng cho mã ứng dụng khách OAuth.
disallowed_useragent
Điểm cuối uỷ quyền được hiển thị trong một tác nhân người dùng được nhúng bởi Chính sách của OAuth 2.0.
Android
Nhà phát triển Android có thể gặp phải thông báo lỗi này khi mở các yêu cầu uỷ quyền trong
android.webkit.WebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện Android như
Tính năng Đăng nhập bằng Google dành cho Android hoặc tài khoản OpenID Foundation
AppAuth cho Android.
Các nhà phát triển web có thể gặp phải lỗi này khi ứng dụng Android mở một đường liên kết trang web chung trong một tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển nên cho phép mở các đường liên kết chung trong trình xử lý đường liên kết mặc định của hệ điều hành của Google, bao gồm cả Đường liên kết trong ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Chiến lược phát hành đĩa đơn Thẻ tuỳ chỉnh trong Android thư viện cũng là một tuỳ chọn được hỗ trợ.
iOS
Nhà phát triển iOS và macOS có thể gặp lỗi này khi mở các yêu cầu uỷ quyền trong
WKWebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện iOS như
Tính năng Đăng nhập bằng Google cho iOS hoặc tài khoản OpenID Foundation
AppAuth cho iOS.
Các nhà phát triển web có thể gặp phải lỗi này khi một ứng dụng iOS hoặc macOS mở một đường liên kết trang web chung trong
tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ
trang web của bạn. Nhà phát triển nên cho phép mở các đường liên kết chung trong trình xử lý đường liên kết mặc định của
hệ điều hành của Google, bao gồm cả
Đường liên kết phổ quát
hoặc ứng dụng trình duyệt mặc định. Chiến lược phát hành đĩa đơn
SFSafariViewController
thư viện cũng là một tuỳ chọn được hỗ trợ.
org_internal
Mã ứng dụng OAuth trong yêu cầu là một phần của một dự án giới hạn quyền truy cập vào Tài khoản Google trong một cụ thể Tổ chức Google Cloud. Để biết thêm thông tin về tuỳ chọn cấu hình này, hãy xem Loại người dùng trong bài viết trợ giúp về Thiết lập màn hình xin phép bằng OAuth.
invalid_client
Nguồn gốc mà yêu cầu được thực hiện không được phép đối với ứng dụng này. Xem
origin_mismatch.
invalid_grant
Khi sử dụng chức năng uỷ quyền gia tăng, mã thông báo có thể đã hết hạn hoặc đã không còn hiệu lực. Xác thực người dùng một lần nữa và yêu cầu người dùng đồng ý để lấy mã thông báo mới. Nếu bạn đang tiếp tục để xem lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã được định cấu hình chính xác và bạn bằng cách sử dụng đúng mã thông báo và tham số trong yêu cầu của bạn. Nếu không, tài khoản người dùng có thể phải đã bị xóa hoặc vô hiệu hóa.
origin_mismatch
Lược đồ, miền và/hoặc cổng của JavaScript bắt nguồn từ yêu cầu uỷ quyền không được khớp với một URI gốc JavaScript được uỷ quyền đã đăng ký cho mã ứng dụng khách OAuth. Đã uỷ quyền xem xét Nguồn gốc JavaScript trong Google API Console Credentials page.
redirect_uri_mismatch
redirect_uri đã chuyển trong yêu cầu uỷ quyền không khớp với với
chuyển hướng URI cho mã ứng dụng khách OAuth. Xem lại các URI chuyển hướng được uỷ quyền trong
Google API Console Credentials page.
Lược đồ, miền và/hoặc cổng của JavaScript bắt nguồn từ yêu cầu uỷ quyền không được khớp với một URI gốc JavaScript được uỷ quyền đã đăng ký cho mã ứng dụng khách OAuth. Bài đánh giá nguồn gốc JavaScript được cho phép trong Google API Console Credentials page.
Tham số redirect_uri có thể tham chiếu đến luồng OAuth ngoài băng tần (OOB) đã
không được dùng nữa và không còn được hỗ trợ nữa. Tham khảo
hướng dẫn di chuyển để cập nhật
tích hợp.
invalid_request
Đã xảy ra lỗi với yêu cầu của bạn. Điều này có thể là do một số lý do:
- Yêu cầu không được định dạng đúng
- Yêu cầu thiếu thông số bắt buộc
- Yêu cầu này sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. Xác minh OAuth của bạn sử dụng phương pháp tích hợp được đề xuất
Bước 3: Xử lý phản hồi của máy chủ OAuth 2.0
Điểm cuối OAuth 2.0
Máy chủ OAuth 2.0 gửi phản hồi tới redirect_uri được chỉ định trong
yêu cầu mã truy cập.
Nếu người dùng phê duyệt yêu cầu, thì phản hồi sẽ chứa mã truy cập. Nếu người dùng không phê duyệt yêu cầu, phản hồi có chứa thông báo lỗi. Mã truy cập hoặc thông báo lỗi sẽ được trả về trên mảnh băm của URI chuyển hướng, như minh hoạ dưới đây:
Phản hồi về mã truy cập:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Ngoài tham số
access_token, chuỗi mảnh cũng chứa tham sốtoken_type, luôn được đặt thànhBearervà tham sốexpires_inchỉ định vòng đời của mã thông báo (tính bằng giây). Nếu tham sốstateđã được chỉ định trong yêu cầu mã truy cập thì giá trị của mã đó cũng được đưa vào phản hồi.- Phản hồi lỗi:
https://oauth2.example.com/callback#error=access_denied
Phản hồi mẫu của máy chủ OAuth 2.0
Bạn có thể kiểm tra quy trình này bằng cách nhấp vào URL mẫu sau. URL này yêu cầu quyền truy cập chỉ đọc để xem siêu dữ liệu cho tệp trong Google Drive của bạn:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& client_id=client_id
Sau khi hoàn tất quy trình OAuth 2.0, bạn sẽ được chuyển hướng đến
http://localhost/oauth2callback. URL đó sẽ mang lại
404 NOT FOUND lỗi trừ phi máy cục bộ của bạn tình cờ phân phát tệp tại
địa chỉ đó. Bước tiếp theo cung cấp thêm thông tin chi tiết về thông tin được trả về trong
URI khi người dùng được chuyển hướng quay lại ứng dụng của bạn.
Gọi API của Google
Điểm cuối OAuth 2.0
Sau khi ứng dụng của bạn nhận được mã truy cập, bạn có thể sử dụng mã này để thực hiện lệnh gọi đến Google
thay mặt cho một
tài khoản người dùng nếu(các) phạm vi quyền 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 trong yêu cầu gửi đến API bằng cách bao gồm truy vấn access_token
hoặc một giá trị Bearer của tiêu đề HTTP Authorization. Nếu có thể,
nên ưu tiên sử dụng tiêu đề HTTP vì chuỗi truy vấn thường hiển thị trong nhật ký máy chủ. Trong hầu hết
bạn có thể sử dụng thư viện ứng dụng để thiết lập lệnh gọi đến các API của Google (ví dụ: khi
gọi API Phát trực tiếp trên YouTube).
Lưu ý rằng API phát trực tiếp trên YouTube không hỗ trợ quy trình tài khoản dịch vụ. Từ đó
không phải là cách để liên kết Tài khoản dịch vụ với tài khoản YouTube, cố gắng uỷ quyền cho các yêu cầu bằng tài khoản này
luồng sẽ tạo ra lỗi NoLinkedYouTubeAccount.
Bạn có thể dùng thử tất cả API của Google và xem phạm vi của chúng ở Nền tảng OAuth 2.0.
Ví dụ về HTTP GET
Lệnh gọi đến
liveBroadcasts.list
điểm cuối (API Phát trực tiếp trên YouTube) bằng HTTP Authorization: Bearer
có thể có dạ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/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Dưới đây là lệnh gọi đến cùng một API cho người dùng đã được xác thực bằng access_token
tham số chuỗi truy vấn:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
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à một
ví dụ sử dụng tuỳ chọn tiêu đề HTTP (ưu tiên):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Hoặc, một cách khác là tuỳ chọn tham số chuỗi truy vấn:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Mã mẫu JavaScript
Đoạn mã dưới đây minh hoạ cách sử dụng CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc) để gửi đến một API của Google. Ví dụ này không sử dụng Thư viện ứng dụng API của Google cho JavaScript. Tuy nhiên, ngay cả khi bạn không dùng thư viện ứng dụng, Hướng dẫn Hỗ trợ về CORS (Chia sẻ tài nguyên giữa nhiều nguồn gốc) trong tài liệu của thư viện đó có thể sẽ giúp ích cho bạn để hiểu rõ hơn về các yêu cầu này.
Trong đoạn mã này, biến access_token đại diện cho mã thông báo mà bạn có
thu được để gửi yêu cầu API thay mặt cho người dùng được uỷ quyền. Các tính năng hoàn chỉnh
ví dụ minh hoạ cách lưu trữ mã thông báo đó trong bộ nhớ cục bộ của trình duyệt và truy xuất mã
khi đưa ra yêu cầu API.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
console.log(xhr.response);
};
xhr.send(null);
Ví dụ đầy đủ
Điểm cuối OAuth 2.0
Mã mẫu này minh hoạ cách hoàn tất quy trình OAuth 2.0 trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google dành cho JavaScript. Mã này dành cho trang HTML hiển thị nút để hãy thử một yêu cầu API. Nếu bạn nhấp vào nút này, mã sẽ kiểm tra xem liệu trang đã lưu trữ Mã truy cập API trong bộ nhớ cục bộ của trình duyệt. Nếu có thì lệnh này sẽ thực thi yêu cầu API. Nếu không, nó sẽ bắt đầu quy trình OAuth 2.0.
Đối với quy trình OAuth 2.0, trang sẽ làm theo các bước sau:
- URL này hướng người dùng đến máy chủ OAuth 2.0 của Google. Máy chủ này yêu cầu quyền truy cập vào
Phạm vi
https://www.googleapis.com/auth/youtube.force-ssl. - Sau khi cấp (hoặc từ chối) quyền truy cập vào một hoặc nhiều phạm vi được yêu cầu, người dùng được chuyển hướng đến trang gốc, giúp phân tích cú pháp mã truy cập từ chuỗi giá trị nhận dạng mảnh.
Trang sử dụng mã truy cập để tạo yêu cầu API mẫu.
Yêu cầu API này gọi
liveBroadcasts.listcủa API Dữ liệu YouTube để truy xuất danh sách chương trình phát sóng video cho kênh YouTube của người dùng được uỷ quyền.- Nếu yêu cầu được thực thi thành công, thì phản hồi của API sẽ được ghi vào phần gỡ lỗi của trình duyệt Google Play.
Bạn có thể thu hồi quyền truy cập vào ứng dụng thông qua Quyền cho Tài khoản Google. Ứng dụng sẽ được liệt kê là Bản minh hoạ OAuth 2.0 cho Tài liệu API của Google.
Để chạy mã này cục bộ, bạn cần đặt giá trị cho YOUR_CLIENT_ID và
biến YOUR_REDIRECT_URI tương ứng với
uỷ quyền thông tin xác thực. Biến YOUR_REDIRECT_URI
phải được đặt thành cùng một URL nơi trang đang được phân phát. Giá trị này phải khớp chính xác với một trong
URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong
API Console Credentials page. Nếu
giá trị này không khớp với URI được uỷ quyền, bạn sẽ nhận được redirect_uri_mismatch
. Dự án của bạn cũng phải có
đã bật API thích hợp cho yêu cầu này.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
'state': state,
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>
Quy tắc xác thực nguồn gốc JavaScript
Google áp dụng các quy tắc xác thực sau đây cho nguồn gốc JavaScript để giúp nhà phát triển đảm bảo an toàn cho các ứng dụng của họ. Nguồn gốc JavaScript của bạn phải tuân thủ các quy tắc này. Hãy xem phần 3 của RFC 3986 để biết định nghĩa về miền, máy chủ lưu trữ và giao thức, được đề cập bên dưới.
| Các quy tắc xác thực | |
|---|---|
| Lược đồ |
Nguồn gốc JavaScript phải sử dụng giao thức HTTPS, không phải HTTP thuần tuý. URI của máy chủ cục bộ (bao gồm URI địa chỉ IP localhost) được miễn quy tắc này. |
| Máy chủ lưu trữ |
Máy chủ không được là địa chỉ IP thô. Địa chỉ IP của máy chủ cục bộ được miễn tuân theo quy tắc này. |
| Miền |
“googleusercontent.com”.goo.gl)
trừ phi ứng dụng sở hữu miền đó. |
| Thông tin người dùng |
Nguồn gốc JavaScript không được chứa thành phần phụ thông tin người dùng. |
| Đường dẫn |
Nguồn gốc JavaScript không được chứa thành phần đường dẫn. |
| Cụm từ tìm kiếm |
Nguồn gốc JavaScript không được chứa thành phần truy vấn. |
| Mảnh |
Nguồn gốc JavaScript không được chứa thành phần phân đoạn. |
| Ký tự |
Nguồn gốc JavaScript không được chứa một số ký tự nhất định, bao gồm:
|
Uỷ quyền tăng dần
Trong giao thức OAuth 2.0, ứng dụng của bạn sẽ yêu cầu cấp quyền để truy cập vào các tài nguyên, tức là được xác định theo phạm vi. Đây được xem là phương pháp yêu cầu uỷ quyền mang lại trải nghiệm người dùng tốt nhất để có được các tài nguyên vào đúng thời điểm bạn cần. Để bật hoạt động đó, máy chủ uỷ quyền của Google hỗ trợ uỷ quyền gia tăng. Tính năng này cho phép bạn yêu cầu phạm vi khi cần và nếu người dùng cấp quyền cho phạm vi mới, sẽ trả về mã uỷ quyền có thể là đã đổi lấy một mã thông báo chứa tất cả các phạm vi mà người dùng đã cấp cho dự án.
Ví dụ: giả sử một ứng dụng truy xuất dữ liệu cho kênh YouTube của người dùng đã xác thực và cũng
cho phép người dùng truy xuất dữ liệu YouTube Analytics thông qua một luồng đặc biệt. Trong trường hợp này, khi đăng nhập
lần, ứng dụng chỉ có thể yêu cầu quyền truy cập vào https://www.googleapis.com/auth/youtube.force-ssl
phạm vi. Tuy nhiên, nếu người dùng này cố gắng truy cập vào dữ liệu Analytics cho kênh của họ, thì ứng dụng cũng có thể
yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/yt-analytics.readonly.
Các quy tắc sau áp dụng cho mã truy cập có được từ việc uỷ quyền tăng dần:
- Bạn có thể dùng mã thông báo này để truy cập vào các tài nguyên tương ứng với bất kỳ phạm vi nào được đưa vào uỷ quyền kết hợp mới.
- Khi bạn sử dụng mã làm mới cho hoạt động uỷ quyền kết hợp để lấy mã truy cập,
mã truy cập đại diện cho sự uỷ quyền kết hợp và có thể được dùng cho bất kỳ
scopegiá trị được đưa vào phản hồi. - Hoạt động uỷ quyền kết hợp bao gồm tất cả phạm vi mà người dùng đã cấp cho dự án API ngay cả khi nếu khoản tài trợ được yêu cầu từ các ứng dụng khác nhau. Ví dụ: nếu người dùng cấp quyền truy cập vào một phạm vi bằng cách sử dụng ứng dụng trên máy tính để bàn của một ứng dụng, sau đó cấp một phạm vi khác cho ứng dụng đó qua ứng dụng di động, uỷ quyền kết hợp sẽ bao gồm cả hai phạm vi.
- Nếu bạn thu hồi một mã thông báo đại diện cho một yêu cầu uỷ quyền kết hợp, thì bạn có thể truy cập vào tất cả những dữ liệu đó phạm vi uỷ quyền thay mặt cho người dùng được liên kết được thu hồi đồng thời.
Các mã mẫu dưới đây cho biết cách thêm phạm vi vào mã truy cập hiện có. Phương pháp này cho phép ứng dụng của bạn để tránh phải quản lý nhiều mã truy cập.
Điểm cuối OAuth 2.0
Trong ví dụ này, ứng dụng gọi yêu cầu quyền truy cập để truy xuất dữ liệu YouTube của người dùng cùng với bất kỳ quyền truy cập nào khác mà người dùng đó đã cấp cho ứng dụng.
Để thêm phạm vi vào một mã truy cập hiện có, hãy thêm include_granted_scopes
trong yêu cầu gửi tới máy chủ OAuth 2.0 của Google.
Đoạn mã sau đây minh hoạ cách thực hiện việc này. Đoạn mã giả định rằng bạn đã lưu trữ
phạm vi mà mã truy cập của bạn hợp lệ trong bộ nhớ cục bộ của trình duyệt. (Các
mã ví dụ hoàn chỉnh lưu trữ danh sách các phạm vi mà mã truy cập
hợp lệ bằng cách đặt thuộc tính oauth2-test-params.scope trong tập dữ liệu cục bộ của trình duyệt
storage.)
Đoạn mã này so sánh các phạm vi mà mã truy cập hợp lệ với phạm vi bạn muốn sử dụng
cho một truy vấn cụ thể. Nếu mã truy cập không bao gồm phạm vi đó, thì quy trình OAuth 2.0 sẽ bắt đầu.
Ở đây, hàm oauth2SignIn giống với hàm được cung cấp trong
bước 2 (và được cung cấp sau trong phần hoàn chỉnh
ví dụ).
var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
var scopes = params['scope'].split(' ');
for (var s = 0; s < scopes.length; s++) {
if (SCOPE == scopes[s]) {
current_scope_granted = true;
}
}
}
if (!current_scope_granted) {
oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
// Since you already have access, you can proceed with the API request.
}
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 Account Settings (Cài đặt tài khoản). Xem Xoá phần truy cập trang web hoặc ứng dụng trong mục Trang web bên thứ ba & các ứng dụng 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 cách lập trình. Việc thu hồi có lập trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá ứng dụng hoặc tài nguyên API mà một ứ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 yêu cầu API để đảm bảo các quyền trước đó được cấp cho ứng dụng sẽ bị xoá.
Điểm cuối OAuth 2.0
Để thu hồi mã thông báo theo cách lập trình, ứng dụng sẽ đưa ra yêu cầu
https://oauth2.googleapis.com/revoke và bao gồm mã thông báo dưới dạng tham số:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
Mã này có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo là một 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 việc 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
có mã lỗi.
Đoạn mã JavaScript sau đây cho biết cách thu hồi mã thông báo trong JavaScript mà không cần sử dụng
Thư viện ứng dụng API của Google dành cho JavaScript. Vì điểm cuối OAuth 2.0 của Google để thu hồi
mã thông báo không hỗ trợ Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), mã sẽ tạo biểu mẫu và gửi
biểu mẫu đến điểm cuối thay vì sử dụng phương thức XMLHttpRequest() để đăng
của bạn.
function revokeAccess(accessToken) {
// Google's OAuth 2.0 endpoint for revoking access tokens.
var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
// Create <form> element to use to POST data to the OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'post');
form.setAttribute('action', revokeTokenEndpoint);
// Add access token to the form so it is set as value of 'token' parameter.
// This corresponds to the sample curl request, where the URL is:
// https://oauth2.googleapis.com/revoke?token={token}
var tokenField = document.createElement('input');
tokenField.setAttribute('type', 'hidden');
tokenField.setAttribute('name', 'token');
tokenField.setAttribute('value', accessToken);
form.appendChild(tokenField);
// Add form to page and submit it to actually revoke the token.
document.body.appendChild(form);
form.submit();
}
Triển khai tính năng Bảo vệ nhiều tài khoản
Bạn nên thực hiện thêm một bước để bảo vệ đang triển khai tính năng Nhiều tài khoản Bảo vệ bằng cách sử dụng Dịch vụ bảo vệ nhiều 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 sự kiện bảo mật nhằm cung cấp thông tin cho ứng dụng của bạn 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 này để thực hiện hành động tùy thuộc vào cách bạn quyết định phản hồi sự kiện.
Dưới đây là một số ví dụ về các loại sự kiện mà Dịch vụ bảo vệ nhiều tài khoản của Google gửi tới ứng dụng của bạn:
-
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 Bảo vệ tài khoản người dùng bằng trang Bảo vệ nhiều tài khoản để biết thêm thông tin về cách triển khai tính năng Bảo vệ nhiều tài khoản và để biết danh sách đầy đủ các sự kiện hiện có.