OAuth 2.0 dành cho TV và ứng dụng thiết bị đầu vào hạn chế

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 API của Google thông qua các ứng dụng chạy trên các thiết bị như TV, máy chơi trò chơi và máy in. Cụ thể hơn, quy trình này được thiết kế cho các thiết bị không có quyền truy cập cho một trình duyệt hoặc bị hạn chế khả năng nhập.

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ữ cho tên người dùng, mật khẩu và các thông tin khác ở chế độ riêng tư. Ví dụ: ứng dụng truyền hình có thể dùng OAuth 2.0 để có quyền truy cập chọn một tệp được lưu trữ trên Google Drive.

Do các ứng dụng dùng quy trình này được phân phối đến các thiết bị riêng lẻ, nên giả định rằng ứng dụng không thể giữ bí mật. Chúng có thể truy cập API của Google trong khi người dùng có tại ứng dụng hoặc khi ứng dụng đang chạy trong nền.

Lựa chọn thay thế

Nếu bạn đang viết một ứng dụng cho một nền tảng như Android, iOS, macOS, Linux hoặc Windows (bao gồm cả Universal Windows Platform), có quyền truy cập vào trình duyệt và dữ liệu đầu vào đầy đủ các khả năng, sử dụng quy trình OAuth 2.0 cho thiết bị di động và máy tính để bàn. (Bạn nên sử dụng luồng đó ngay cả khi ứng dụng của bạn là một dòng lệnh mà không có giao diện đồ hoạ).

Nếu bạn chỉ muốn đăng nhập người dùng bằng Tài khoản Google của họ và sử dụng Mã thông báo giá trị nhận dạng JWT để lấy thông tin cơ bản về hồ sơ người dùng, xem bài viết Đăng nhập trên TV và Thiết bị đầu vào bị hạn chế.

Đ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:

  1. Open the API Library trong Google API Console.
  2. If prompted, select a project, or create a new one.
  3. API Library liệt kê tất cả các API có sẵn, được nhóm theo sản phẩm gia đình và độ nổi tiếng. Nếu API bạn muốn bật không hiển thị trong danh sách, hãy sử dụng tính năng tìm kiếm để tìm biểu tượng hoặc nhấp vào Xem tất cả trong nhóm sản phẩm chứa mục đó.
  4. Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

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 đó.

  1. Go to the Credentials page.
  2. Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
  3. Chọn loại ứng dụng TV và các thiết bị đầu vào bị giới hạn.
  4. Đặt tên cho ứng dụng OAuth 2.0 rồi nhấp vào Create (Tạo).

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.

Xem danh sách Phạm vi được phép cho các ứng dụng hoặc thiết bị đã cài đặt.

Lấy mã truy cập OAuth 2.0

Mặc dù ứng dụng của bạn chạy trên một thiết bị có khả năng nhập hạn chế, người dùng vẫn phải quyền truy cập riêng vào một thiết bị có khả năng nhập dữ liệu phong phú hơn để hoàn tất quy trình cấp phép này. Quy trình này có các bước sau:

  1. Ứng dụng của bạn gửi yêu cầu tới máy chủ uỷ quyền của Google để xác định các phạm vi mà ứng dụng của bạn sẽ yêu cầu quyền truy cập.
  2. Máy chủ sẽ phản hồi bằng một số thông tin được dùng trong các bước tiếp theo, chẳng hạn như mã thiết bị và mã người dùng.
  3. Bạn hiển thị thông tin mà người dùng có thể nhập trên một thiết bị riêng để cho phép .
  4. Ứng dụng của bạn bắt đầu thăm dò máy chủ cấp phép của Google để xác định xem người dùng có đang đã cấp phép cho ứng dụng của bạn.
  5. Người dùng chuyển sang một thiết bị có khả năng nhập phong phú hơn, khởi chạy trình duyệt web, chuyển đến URL hiển thị ở bước 3 và nhập mã cũng xuất hiện ở bước 3. Chiến lược phát hành đĩa đơn người dùng khi đó có thể cấp (hoặc từ chối) quyền truy cập vào ứng dụng của bạn.
  6. Phản hồi tiếp theo cho yêu cầu thăm dò ý kiến của bạn chứa các mã thông báo mà ứng dụng của bạn cần cho phép yêu cầu thay mặt người dùng. (Nếu người dùng từ chối truy cập vào ứng dụng của bạn, phản hồi không chứa mã thông báo.)

Hình ảnh dưới đây minh hoạ quá trình này:

Người dùng đăng nhập trên một thiết bị khác có trình duyệt

Các phần sau đây sẽ giải thích chi tiết các bước này. Dựa trên nhiều tính năng và thời gian chạy môi trường mà thiết bị có thể có, các ví dụ trong tài liệu này sử dụng thuộc tính curl tiện ích dòng lệnh. Những ví dụ này phải dễ chuyển đổi sang nhiều ngôn ngữ và thời gian chạy.

Bước 1: Yêu cầu mã thiết bị và mã người dùng

Ở bước này, thiết bị của bạn gửi yêu cầu POST qua HTTP tới máy chủ uỷ quyền của Google tại https://oauth2.googleapis.com/device/code giúp xác định ứng dụng của bạn cũng như phạm vi truy cập mà ứng dụng của bạn muốn thay mặt người dùng truy cập. Bạn nên truy xuất URL này từ Tài liệu khám phá sử dụng thuộc tính Giá trị siêu dữ liệu device_authorization_endpoint. Bao gồm yêu cầu HTTP sau đây thông số:

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.
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. Xem Danh sách Phạm vi được phép cho các ứng dụng hoặc thiết bị đã cài đặt.

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.

Ví dụ

Đoạn mã sau đây cho thấy một yêu cầu mẫu:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

Ví dụ dưới đây cho thấy lệnh curl để gửi cùng một yêu cầu:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

Bước 2: Xử lý phản hồi của máy chủ uỷ quyền

Máy chủ uỷ quyền sẽ trả về một trong các phản hồi sau:

Phản hồi thành công

Nếu yêu cầu hợp lệ, phản hồi của bạn sẽ là đối tượng JSON chứa các thông tin sau thuộc tính:

Thuộc tính
device_code Giá trị mà Google chỉ định riêng để xác định thiết bị chạy ứng dụng yêu cầu uỷ quyền. Người dùng sẽ cho phép thiết bị đó từ một thiết bị khác có các gói khả năng nhập. Ví dụ: người dùng có thể sử dụng máy tính xách tay hoặc điện thoại di động để cấp quyền ứng dụng chạy trên TV. Trong trường hợp này, device_code sẽ xác định TV.

Mã này cho phép thiết bị đang chạy ứng dụng xác định một cách an toàn xem người dùng đã cấp quyền hay chưa hoặc bị từ chối quyền truy cập.
expires_in Khoảng thời gian, tính bằng giây, mà device_code và user_code là hợp lệ. Nếu, trong thời gian đó, người dùng không hoàn tất và thiết bị của bạn cũng không thăm dò ý kiến để truy xuất thông tin về quyết định của người dùng, bạn có thể cần phải bắt đầu lại quá trình này từ bước 1.
interval Khoảng thời gian (tính bằng giây) mà thiết bị sẽ chờ giữa các lần yêu cầu thăm dò ý kiến. Để ví dụ: nếu giá trị là 5, thiết bị của bạn sẽ gửi yêu cầu thăm dò ý kiến đến máy chủ uỷ quyền của Google 5 giây một lần. Xem bước 3 để biết thêm chi tiết.
user_code Một giá trị phân biệt chữ hoa chữ thường giúp xác định cho Google biết phạm vi của ứng dụng yêu cầu quyền truy cập. Giao diện người dùng của bạn sẽ hướng dẫn người dùng nhập giá trị này vào thiết bị riêng biệt với khả năng nhập phong phú hơn. Sau đó, Google sử dụng giá trị này để hiển thị tập hợp phạm vi chính xác khi nhắc người dùng cấp quyền truy cập vào ứng dụng của bạn.
verification_url Một URL mà người dùng phải truy cập trên một thiết bị khác để nhập user_code và cấp hoặc từ chối cấp quyền truy cập vào ứng dụng của bạn. Giao diện người dùng của bạn cũng sẽ hiển thị giá trị này.

Đoạn mã sau đây cho thấy một phản hồi mẫu:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Phản hồi vượt quá hạn mức

Nếu các yêu cầu mã thiết bị của bạn vượt quá hạn mức được liên kết với mã ứng dụng khách, bạn sẽ nhận được phản hồi 403, có chứa lỗi sau:

{
  "error_code": "rate_limit_exceeded"
}

Trong trường hợp đó, hãy sử dụng chiến lược thời gian đợi để giảm tỷ lệ yêu cầu.

Bước 3: Hiển thị mã người dùng

Hiển thị verification_url và user_code có được ở bước 2 vào thuộc tính người dùng. Cả hai giá trị này đều có thể chứa bất kỳ ký tự nào in được từ bộ ký tự US-ASCII. Nội dung mà bạn hiển thị cho người dùng sẽ hướng dẫn người dùng điều hướng đến verification_url trên một thiết bị khác rồi nhập user_code.

Thiết kế giao diện người dùng (UI) của bạn theo các quy tắc sau:

  • user_code
    • user_code phải được hiển thị trong trường có thể xử lý 15 "W" kích thước ký tự. Nói cách khác, nếu bạn có thể cho thấy mã WWWWWWWWWWWWWWW chính xác, giao diện người dùng của bạn hợp lệ. Bạn nên sử dụng giá trị chuỗi đó khi thử nghiệm user_code hiển thị trong giao diện người dùng.
    • user_code có phân biệt chữ hoa chữ thường và bạn không được sửa đổi theo bất kỳ cách nào, chẳng hạn như như thay đổi cách viết hoa hoặc chèn các ký tự định dạng khác.
  • verification_url
    • Không gian nơi bạn hiển thị verification_url phải đủ rộng để xử lý chuỗi URL dài 40 ký tự.
    • Bạn không nên sửa đổi verification_url theo bất kỳ cách nào, ngoại trừ việc không bắt buộc xoá giao thức hiển thị. Nếu bạn định loại bỏ lược đồ (ví dụ: https://) khỏi URL vì lý do hiển thị, hãy đảm bảo ứng dụng của bạn có thể xử lý cả hai biến thể http và https.

Bước 4: Thăm dò máy chủ uỷ quyền của Google

Vì người dùng sẽ sử dụng một thiết bị riêng để chuyển đến verification_url và cấp (hoặc từ chối) quyền truy cập, thiết bị yêu cầu sẽ không tự động được thông báo khi người dùng phản hồi yêu cầu truy cập. Vì lý do đó, thiết bị yêu cầu cần thăm dò máy chủ uỷ quyền để xác định thời điểm người dùng đã phản hồi yêu cầu.

Thiết bị yêu cầu sẽ tiếp tục gửi yêu cầu thăm dò ý kiến cho đến khi nhận được phản hồi cho biết người dùng đã phản hồi yêu cầu truy cập hoặc cho đến khi device_code và user_code đã lấy được trong bước 2 đã hết hạn. interval được trả về trong bước 2 chỉ định lượng thời gian (tính bằng giây) để chờ giữa các lần yêu cầu.

URL của điểm cuối tới cuộc thăm dò ý kiến là https://oauth2.googleapis.com/token. Yêu cầu thăm dò ý kiến chứa các tham số sau:

Tham số
client_id 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.
client_secret Mật khẩu ứng dụng khách cho client_id đã cung cấp. Bạn có thể tìm thấy giá trị này trong API Console Credentials page.
device_code device_code được máy chủ uỷ quyền trả về trong bước 2.
grant_type Đặt giá trị này thành urn:ietf:params:oauth:grant-type:device_code.

Ví dụ

Đ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=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Ví dụ dưới đây cho thấy lệnh curl để gửi cùng một yêu cầu:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Bước 5: Người dùng trả lời yêu cầu truy cập

Hình ảnh sau đây hiển thị một trang tương tự như những gì người dùng thấy khi họ điều hướng tới verification_url mà bạn đã hiển thị trong bước 3:

Kết nối thiết bị bằng cách nhập mã

Sau khi nhập user_code và nếu chưa đăng nhập thì hãy đăng nhập vào Google, người dùng thấy màn hình xin phép như màn hình dưới đây:

Ví dụ về màn hình xin phép cho ứng dụng thiết bị

Bước 6: Xử lý phản hồi cho các yêu cầu thăm dò ý kiến

Máy chủ uỷ quyền của Google phản hồi từng yêu cầu thăm dò ý kiến bằng một trong các lệnh sau phản hồi:

Đã nhận được lợi ích mới

Nếu người dùng đã cấp quyền truy cập vào thiết bị (bằng cách nhấp vào Allow trên màn hình đồng ý), thì phản hồi sẽ chứa mã truy cập và mã làm mới. Mã thông báo này cho phép thiết bị của bạn truy cập vào API của Google thay mặt người dùng. (scope trong phản hồi xác định API nào thiết bị nào có thể truy cập).

Trong trường hợp này, phản hồi của API chứa các trường sau:

Trường
access_token Mã thông báo mà ứng dụng của bạn gửi để cho phép yêu cầu API của Google.
expires_in Thời gian hoạt động còn lại của mã truy cập tính bằng giây.
refresh_token Mã thông báo mà bạn có thể dùng để lấy mã truy cập mới. Mã làm mới có hiệu lực cho đến khi người dùng thu hồi quyền truy cập. Xin lưu ý rằng mã làm mới luôn được trả về cho thiết bị.
scope Phạm vi truy cập mà access_token đã cấp được biểu thị dưới dạng danh sách chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.
token_type Loại mã thông báo được trả về. Tại thời điểm này, giá trị của trường này luôn được đặt thành Bearer.

Đoạn mã sau đây cho thấy một phản hồi mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Mã truy cập có thời hạn tồn tại có giới hạn. Nếu ứng dụng của bạn cần quyền truy cập vào một API trong một thời gian dài một khoảng thời gian nhất định, ứng dụng có thể sử dụng mã làm mới để có được quyền truy cập mới mã thông báo. Nếu cần loại quyền truy cập này thì ứng dụng của bạn sẽ lưu trữ mã làm mới cho để sử dụng sau này.

Truy cập bị từ chối

Nếu người dùng từ chối cấp quyền truy cập vào thiết bị, thì phản hồi của máy chủ có một 403 Mã trạng thái phản hồi HTTP (Forbidden). Phản hồi chứa lỗi sau:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Đang chờ cho phép

Nếu người dùng chưa hoàn tất quy trình cấp phép, thì máy chủ sẽ trả về 428 Mã trạng thái phản hồi HTTP (Precondition Required). Phản hồi chứa lỗi sau:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Cuộc thăm dò ý kiến quá thường xuyên

Nếu thiết bị gửi yêu cầu thăm dò quá thường xuyên, thì máy chủ sẽ trả về một 403 Mã trạng thái phản hồi HTTP (Forbidden). Phản hồi có chứa những nội dung sau lỗi:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Các lỗi khác

Máy chủ uỷ quyền cũng trả về lỗi nếu yêu cầu thăm dò ý kiến thiếu bất kỳ thông tin bắt buộc nào hoặc có giá trị thông số không chính xác. Những yêu cầu này thường có một 400 Trạng thái phản hồi HTTP (Bad Request) hoặc 401 (Unauthorized) . Những lỗi đó bao gồm:

Lỗi Mã trạng thái HTTP Mô tả
admin_policy_enforced 400 Tài khoản Google không thể cấp quyền cho một hoặc nhiều phạm vi đã yêu cầu do chính sách của quản trị viên Google Workspace của họ. Xem phần trợ giúp dành cho Quản trị viên Google Workspace bài viết Kiểm soát bên thứ ba & 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 các phạm vi cho đến khi bạn cấp quyền truy cập rõ ràng cho OAuth mã ứng dụng khách.
invalid_client 401

Không tìm thấy ứng dụng OAuth. Ví dụ: lỗi này xảy ra nếu Giá trị tham số client_id không hợp lệ.

Loại ứng dụng OAuth không chính xác. Đảm bảo rằng loại ứng dụng cho mã ứng dụng khách được đặt thành TV và thiết bị đầu vào bị giới hạn.
invalid_grant 400 Giá trị thông số code không hợp lệ, đã được xác nhận quyền sở hữu hoặc không thể được đã phân tích cú pháp.
unsupported_grant_type 400 Giá trị tham số grant_type không hợp lệ.
org_internal 403 Mã ứng dụng 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 theo một cách cụ thể Tổ chức Google Cloud. Xác nhận kiểu người dùng cấu hình cho ứng dụng OAuth.

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ể 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 Tệp Drive).

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 drive.files điểm cuối (API Tệp Drive) 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 /drive/v2/files 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/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à 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/drive/v2/files

Hoặc, một cách khác là tuỳ chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Làm mới mã truy cập

Mã truy cập hết hạn theo đị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ó) 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 POST HTTPS yêu cầu máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token) bao gồm các thông số sau:

Trường
client_id Mã ứng dụng khách lấy được từ API Console.
client_secret Mật khẩu ứng dụng khách lấy được từ API Console.
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&
client_secret=your_client_secret&
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ã thông báo truy cập mới. Đoạn mã sau đây cho thấy một mẫu trả lời:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Xin lưu ý rằng có giới hạn về số lượng mã thông báo làm mới sẽ được phát hành; một giới hạn mỗi khách hàng/người dùng và một tổ hợp khách hàng/người dùng khác cho mỗi người dùng trên tất cả khách hàng. Bạn nên lưu mã làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng miễn là chúng vẫn hợp lệ. Nếu ứng dụng của bạn yêu cầu quá nhiều mã làm mới, thì mã này có thể gặp phải các 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 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á.

Để 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.

Phạm vi được phép

Quy trình OAuth 2.0 cho thiết bị chỉ được hỗ trợ đối với các phạm vi sau:

OpenID Connect, Đăng nhập bằng Google

  • email
  • openid
  • profile

API Drive

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

API YouTube

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly

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ó.