Tài liệu này giải thích cách triển khai hoạt động uỷ quyền OAuth 2.0 để truy cập vào các API của Google 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 một ứng dụng trong khi vẫn giữ bí mật 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 người dùng cấp quyền lưu trữ tệp trong Google Drive của họ.
Quy trình OAuth 2.0 này được gọi là quy trình cấp ngầm định. Đây là quyền được thiết kế cho các ứng dụng chỉ truy cập vào API khi người dùng đang ở trong ứng dụng. Những ứng dụng này không thể lưu trữ thông tin 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 để xác định ứng dụng của bạn và loại quyền truy cập API mà ứng dụng yêu cầu. Bạn có thể mở URL trong cửa sổ trình duyệt hiện tại hoặc một cửa sổ bật lên. Người dùng có thể xác thực bằng 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. Lệnh chuyển hướng này bao gồm một mã truy cập mà ứng dụng của bạn xác minh rồi dùng để đưa ra các 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 dùng Thư viện ứng dụng API của Google cho JavaScript để thực hiện các lệnh gọi được uỷ quyền đến Google, bạn nên dùng thư viện JavaScript Dịch vụ nhận dạng của Google để xử lý quy trình OAuth 2.0. Vui lòng xem mô hình mã thông báo của Dịch vụ nhận dạng của Google. Mô hình này dựa trên quy trình cấp ngầm định OAuth 2.0.
Đ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 Google đề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.
- API Library liệt kê tất cả những API có sẵn, được nhóm theo nhóm sản phẩm và mức độ phổ biến. Nếu API bạn muốn bật không xuất hiện trong danh sách, hãy sử dụng chức năng tìm kiếm để tìm API đó hoặc nhấp vào Xem tất cả trong nhóm sản phẩm mà API đó thuộc về.
- Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
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 uỷ quyền để xác định ứng dụng với 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 để truy cập vào các API mà bạn đã bật cho dự án đó.
- Go to the Credentials page.
- Nhấp vào Tạo ứng dụng.
- Chọn loại ứng dụng Ứng dụng web.
- Hoàn thành biểu mẫu. Những ứng dụng sử dụng JavaScript để thực hiện các yêu cầu được uỷ quyền đối với API của Google phải chỉ định các nguồn gốc JavaScript được uỷ quyền. Nguồn gốc xác định các miền mà ứng dụng của bạn có thể gửi yêu cầu đến máy chủ OAuth 2.0. Các nguồn gốc này phải tuân thủ các 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 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 sẽ cần có quyền truy cập.
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ể sử 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: Chuyển hướng đến 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 máy chủ OAuth 2.0 của Google.
Đ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
. Bạn có thể truy cập vào điểm cuối này qua HTTPS; các kết nối HTTP thuần tuý sẽ 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 đây cho các ứng dụng máy chủ web:
Thông 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 . |
||||||
redirect_uri |
Bắt buộc
Xác định vị trí mà máy chủ API chuyển hướng người dùng đến sau khi người dùng hoàn tất quy trình uỷ quyền. Giá trị phải khớp chính xác với một trong các 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 của ứng dụng khách . Nếu giá trị này không khớp với một URI chuyển hướng được uỷ quyền cho Xin lưu ý rằng lược đồ, trường hợp và dấu gạch chéo ở cuối (" |
||||||
response_type |
Bắt buộc
Các ứng dụng JavaScript cần đặt giá trị của 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. Bạn nên yêu cầu ứng dụng truy cập vào các phạm vi uỷ quyền trong 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 trong bối cảnh, thông qua uỷ quyền từng phần, bạn giúp người dùng dễ dàng hiểu được 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 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ì |
||||||
include_granted_scopes |
Không bắt buộc
Cho phép các ứng dụng sử dụng tính năng uỷ quyền từng phần để yêu cầu quyền truy cập vào các phạm vi bổ sung trong ngữ cảnh. Nếu bạn đặt giá trị của tham số này thành |
||||||
enable_granular_consent |
Không bắt buộc
Giá trị mặc định là Khi Google bật quyền chi tiết cho một ứng dụng, tham số này sẽ không còn có hiệu lực. |
||||||
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 tham số này để cung cấp một 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 hoá quy trình đăng nhập bằng cách điền sẵ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 lần thích hợp. Đặt giá trị tham số thành địa chỉ email hoặc giá trị nhận dạng |
||||||
prompt |
Không bắt buộc
Một danh sách phân tách bằng dấu cách, phân biệt chữ hoa chữ thường gồm các câu lệnh để trình bày cho người dùng. Nếu bạn 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. Hãy xem phần Yêu cầu người dùng đồng ý lại để biết thêm thông tin. Các giá trị có thể là:
|
Ví dụ về việc chuyển hướng đến máy chủ uỷ quyền của Google
Sau đây là một ví dụ về URL, có dấu ngắt dòng và khoảng trắng để dễ đọc.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& 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ã JavaScript mẫu
Đ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 cần sử dụng Thư viện ứng dụng JavaScript cho API của Google. Vì điểm cuối OAuth 2.0 này không hỗ trợ tính năng Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), nên đoạn mã sẽ tạo một biểu mẫu 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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly', '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 ý
Trong bước này, người dùng sẽ quyết định có cấp cho ứng dụng của bạn quyền truy cập được yêu cầu hay không. Ở giai đoạn này, Google sẽ hiển thị một cửa sổ đồng ý cho biết tên của ứng dụng và các dịch vụ Google API mà ứng dụng đang yêu cầu quyền truy cập bằng thông tin xác thực uỷ quyền của người dùng, cũng như bản tóm tắt về các phạm vi truy cập sẽ đượ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 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ì ứng dụng sẽ đợi phản hồi từ máy chủ OAuth 2.0 của Google cho biết có quyền truy cập nào được cấp hay không. Phản hồi đó được giải thích trong bước tiếp theo.
Lỗi
Các yêu cầu đế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 cho người dùng thay vì các quy trình xác thực và uỷ quyền dự kiến. Dưới đây là danh sách mã lỗi thường gặp và các giải pháp được đề xuất.
admin_policy_enforced
Tài khoản Google không thể uỷ quyền 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. Hãy xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát việc những ứng dụng nội bộ và ứng dụng của bên thứ ba nào truy cập vào 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 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 mã ứng dụng OAuth của bạn.
disallowed_useragent
Điểm cuối uỷ quyền xuất hiện trong một tác nhân người dùng được nhúng mà Chính sách về OAuth 2.0 của Google không cho phép.
Android
Nhà phát triển Android có thể gặp phải thông báo lỗi này khi mở 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ư Google Sign-In for Android hoặc AppAuth for Android của OpenID Foundation.
Nhà phát triển web có thể gặp phải lỗi này khi một ứng dụng Android mở một đường liên kết chung trên web 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 các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Đường liên kết đến ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Thư viện Thẻ tuỳ chỉnh của Android cũng là một lựa chọn được hỗ trợ.
iOS
Nhà phát triển iOS và macOS có thể gặp phải lỗi này khi mở yêu cầu uỷ quyền trong WKWebView
.
Thay vào đó, nhà phát triển nên dùng các thư viện iOS như Google Sign-In cho iOS hoặc AppAuth cho iOS của OpenID Foundation.
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 chung trên web 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 các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Đường liên kết chung hoặc ứng dụng trình duyệt mặc định. Thư viện SFSafariViewController
cũng là một lựa chọn được hỗ trợ.
org_internal
Mã ứng dụng OAuth trong yêu cầu thuộc một 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.
invalid_client
Nguồn gốc mà từ đó yêu cầu được đưa ra không được phép cho ứng dụng này. Xem phần origin_mismatch
.
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 khách hàng đã xoá trong vòng 30 ngày kể từ ngày xoá. Tìm hiểu thêm .
invalid_grant
Khi bạn sử dụ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 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 của mình. Nếu không, tài khoản người dùng có thể đã bị xoá hoặc vô hiệu hoá.
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 có thể không khớp với URI nguồn gốc JavaScript được uỷ quyền đã đăng ký cho mã ứng dụng OAuth. Xem xét các gốc JavaScript được phép trong .
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
.
Lược đồ, miền và/hoặc cổng của JavaScript bắt nguồn từ yêu cầu uỷ quyền có thể không khớp với URI nguồn gốc JavaScript được uỷ quyền đã đăng ký cho mã ứng dụng OAuth. Xem xét các gốc JavaScript được phép trong .
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ợ nữa. Tham khảo hướng dẫn di chuyển để cập nhật chế độ 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ố lý do sau:
- Yêu cầu không được định dạng đúng cách
- Yêu cầu thiếu các tham số bắt buộc
- Yêu cầu sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. Xác minh rằng quá trình tích hợp OAuth của bạn sử dụng một phương thức 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 sẽ gửi một phản hồi đến redirect_uri
được chỉ định trong yêu cầu mã truy cập của bạn.
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, thì phản hồi sẽ chứa thông báo lỗi. Mã truy cập hoặc thông báo lỗi được trả về trên đoạn băm của URI chuyển hướng, như minh hoạ dưới đây:
Phản hồi bằng 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 phân đoạn cũng chứa tham sốtoken_type
(luôn được đặt thànhBearer
) và tham sốexpires_in
(chỉ định thời gian tồn tạ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 tham số đó 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 của máy chủ OAuth 2.0 mẫu
Bạn có thể kiểm thử 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 của các tệp trong Google Drive và quyền truy cập chỉ đọc để xem các sự kiện trên Lịch Google:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& 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ẽ tạo ra lỗi 404 NOT FOUND
, trừ phi máy cục bộ của bạn tình cờ phân phát mộ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 trở lại ứng dụng của bạn.
Bước 4: Kiểm tra xem người dùng đã 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 những phạm vi nào đã được cấp và xử lý một cách linh hoạt những trường hợp một số quyền bị từ chối, thường là bằng cách tắt các tính năng dựa vào những phạm vi bị từ chối đó.
Tuy nhiên, vẫn có một số trường hợp ngoại lệ. Các ứng dụng Google Workspace Enterprise có quyền uỷ quyền trên toàn miền hoặc các ứng dụng được đánh dấu là Đáng tin cậy sẽ bỏ qua màn hình đồng ý cấp quyền chi tiết. Đối với những ứng dụng này, người dùng sẽ không thấy màn hình đồng ý 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.
Điểm cuối OAuth 2.0
Để 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ã truy cập. Phạm vi truy cập được cấp bởi access_token dưới dạng danh sách các chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.
Ví dụ: phản hồi mã truy cập mẫu sau đây cho biết rằng người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào quyền chỉ đọc đối với hoạt động trên Drive và sự kiện trên Lịch:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Gọi các 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 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 một thư viện ứng dụng để thiết lập các lệnh gọi đến API của Google (ví dụ: khi gọi API Tệp trên Drive).
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 lệnh gọi đến điểm cuối
drive.files
(Drive Files API) bằng cách sử dụng tiêu đề HTTP Authorization: Bearer
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 /drive/v2/files 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/drive/v2/files?access_token=access_token
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/drive/v2/files
Hoặc, bạn có thể chọn tham số chuỗi truy vấn:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Mã JavaScript mẫu
Đ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ửi yêu cầu đến một Google API. Ví dụ này không sử dụng Thư viện ứng dụng Google API cho JavaScript. Tuy nhiên, ngay cả khi bạn không sử dụng thư viện ứng dụng, thì hướng dẫn hỗ trợ CORS trong tài liệu của thư viện đó có thể sẽ giúp 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 đã nhận được để thay mặt người dùng được uỷ quyền đưa ra các yêu cầu API. Ví dụ hoàn chỉnh 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ã thông báo đó khi đưa ra yêu cầu API.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + '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ẫu mã 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 Google API cho JavaScript. Mã này dành cho một trang HTML hiển thị nút để 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 trang có lưu trữ mã truy cập API trong bộ nhớ cục bộ của trình duyệt hay không. Nếu có, nó 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 này sẽ làm theo các bước sau:
- Thao tác này sẽ chuyển hướng người dùng đến máy chủ OAuth 2.0 của Google, yêu cầu quyền truy cập vào các phạm vi
https://www.googleapis.com/auth/drive.metadata.readonly
vàhttps://www.googleapis.com/auth/calendar.readonly
. - 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 sẽ được chuyển hướng đến trang ban đầu. Trang này sẽ phân tích mã truy cập từ chuỗi giá trị nhận dạng đoạn.
- Trang này kiểm tra xem người dùng đã cấp quyền truy cập vào ứng dụng cho những phạm vi nào.
Nếu người dùng đã cấp quyền truy cập vào (các) phạm vi được yêu cầu, thì trang sẽ sử dụng mã truy cập để thực hiện yêu cầu API mẫu.
Yêu cầu API gọi phương thức
about.get
của Drive API để truy xuất thông tin về tài khoản Google Drive của người dùng được uỷ quyền.- Nếu yêu cầu thực thi thành công, phản hồi API sẽ được ghi vào nhật ký trong bảng điều khiển gỡ lỗi của trình duyệt.
Bạn có thể thu hồi quyền truy cập vào ứng dụng thông qua trang Quyền của Tài khoản Google. Ứng dụng này sẽ xuất hiện dưới dạng OAuth 2.0 Demo for Google API Docs.
Để chạy mã này cục bộ, bạn cần đặt các giá trị cho biến YOUR_CLIENT_ID
và YOUR_REDIRECT_URI
tương ứng với thông tin uỷ quyền của bạn. Bạn nên đặt biến YOUR_REDIRECT_URI
thành cùng một URL nơi trang đang được phân phát. Giá trị phải khớp chính xác với một trong các 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
. 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 redirect_uri_mismatch
. Dự án của bạn cũng phải 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']) { // User authorized the request. Now, check which scopes were granted. if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) { // User authorized read-only Drive activity permission. // Calling the APIs, etc. var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + '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 { // User didn't authorize read-only Drive activity permission. // Update UX and application accordingly console.log('User did not authorize read-only Drive activity permission.'); } // Check if user authorized Calendar read permission. if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. console.log('User authorized Calendar read permission.'); } else { // User didn't authorize Calendar read permission. // Update UX and application accordingly console.log('User did not authorize Calendar read permission.'); } } 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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly', '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 bảo mật 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 RFC 3986 phần 3 để biết định nghĩa về miền, máy chủ lưu trữ và lượ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 lược đồ HTTPS, không phải HTTP thuần tuý. URI máy chủ cục bộ (bao gồm cả URI địa chỉ IP máy chủ cục bộ) được miễn áp dụng quy tắc này. |
Máy chủ lưu trữ |
Máy chủ lưu trữ không được là địa chỉ IP thô. Địa chỉ IP máy chủ cục bộ được miễn áp dụng quy tắc này. |
Miền |
“googleusercontent.com” .goo.gl ) trừ phi ứng dụng sở hữu miền đó. |
Userinfo |
Nguồn gốc JavaScript không được chứa thành phần phụ userinfo. |
Đườ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ự, bao gồm:
|
Uỷ quyền gia tăng
Trong giao thức OAuth 2.0, ứng dụng của bạn yêu cầu cấp quyền truy cập vào các tài nguyên được xác định theo phạm vi. Bạn nên yêu cầu uỷ quyền cho các tài nguyên vào thời điểm cần thiết để mang lại trải nghiệm tốt nhất cho người dùng. Để cho phép hoạt động đó, máy chủ uỷ quyền của Google hỗ trợ việc uỷ quyền gia tăng. Tính năng này cho phép bạn yêu cầu các phạm vi khi cần và nếu người dùng cấp quyền cho phạm vi mới, thì tính năng này sẽ trả về một mã uỷ quyền có thể được trao đổ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ụ: một ứng dụng cho phép mọi người nghe thử các bản nhạc và tạo bản phối có thể chỉ cần rất ít tài nguyên tại thời điểm đăng nhập, có lẽ chỉ cần tên của người đăng nhập. Tuy nhiên, để lưu một bản phối hoàn chỉnh, bạn cần có quyền truy cập vào Google Drive của họ. Hầu hết mọi người sẽ thấy việc này là bình thường nếu họ chỉ được yêu cầu cấp quyền truy cập vào Google Drive của mình vào thời điểm ứng dụng thực sự cần quyền truy cập đó.
Trong trường hợp này, tại thời điểm đăng nhập, ứng dụng có thể yêu cầu các phạm vi openid
và profile
để thực hiện quy trình đăng nhập cơ bản, sau đó yêu cầu phạm vi https://www.googleapis.com/auth/drive.file
tại thời điểm yêu cầu đầu tiên để lưu một bản phối.
Các quy tắc sau đây áp dụng cho mã truy cập nhận được từ một quy trình uỷ quyền gia tăng:
- 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 kết hợp trong quy trình uỷ quyền mới.
- Khi bạn 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 sẽ đại diện cho hoạt động uỷ quyền kết hợp và có thể dùng cho bất kỳ giá trị
scope
nào có trong phản hồi. - Uỷ quyền kết hợp bao gồm tất cả các phạm vi mà người dùng đã cấp cho dự án API, ngay cả khi các quyền đượ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 máy tính của một ứng dụng, sau đó cấp một phạm vi khác cho cùng một ứng dụng thông qua ứng dụng di động, thì 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 uỷ quyền kết hợp, thì quyền truy cập vào tất cả các phạm vi uỷ quyền đó thay mặt cho người dùng được liên kết sẽ bị thu hồi đồng thời.
Các mẫu mã bên dưới 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 giúp ứng dụng của bạn không phải quản lý nhiều mã truy cập.
Điểm cuối OAuth 2.0
Để thêm phạm vi vào mã truy cập hiện có, hãy thêm tham số include_granted_scopes
vào yêu cầu của bạn đối vớ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 đó. Đoạn mã giả định rằng bạn đã lưu trữ các 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. (Đoạn mã ví dụ hoàn chỉnh lưu trữ danh sách các phạm vi mà mã thông báo truy cập hợp lệ bằng cách đặt thuộc tính oauth2-test-params.scope
trong bộ nhớ cục bộ của trình duyệt.)
Đ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 dùng cho một truy vấn cụ thể. Nếu mã truy cập không bao gồm phạm vi đó, 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 ví dụ hoàn chỉnh).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; 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 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 yêu cầu API để đảm bảo các quyền đã cấp cho ứng dụng trước đó sẽ bị xoá.
Điểm cuối OAuth 2.0
Để 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ã thông báo 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.
Đ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 dùng Thư viện ứng dụng Google API 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ợ tính năng Chia sẻ tài nguyên trên nhiều nguồn (CORS), nên mã này sẽ tạo một 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 yêu cầu.
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
Một bước bổ sung mà bạn nên thực hiện để bảo vệ tài khoản của người dùng là triển khai tính năng Bảo vệ trên nhiều tài khoản bằng cách sử dụng Dịch vụ bảo vệ trên 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 về sự kiện bảo mật. Thông báo này 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 tuỳ thuộc vào cách bạn quyết định phản hồi các sự kiện.
Sau đây là một số ví dụ về các loại sự kiện mà Dịch vụ bảo vệ trên nhiều tài khoản của Google gửi đến ứ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
Hãy xem trang Bảo vệ tài khoản người dùng bằng tính năng 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à danh sách đầy đủ các sự kiện có sẵn.