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

Tính năng sao lưu

Tài liệu này giải thích cách triển khai lệnh ủy quyền OAuth 2.0 để truy cập vào các API của Google thông qua các ứng dụng chạy trên 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 vào trình duyệt hoặc có khả năng nhập hạn chế.

OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với một ứng dụng mà vẫn giữ 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 TV có thể sử dụng OAuth 2.0 để có quyền chọn một tệp được lưu trữ trên Google Drive.

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

Phương án thay thế

Nếu bạn đang viết ứng dụng cho một nền tảng như Android, iOS, macOS, Linux hoặc Windows (bao gồm cả Nền tảng phổ biến của Windows), có quyền truy cập vào trình duyệt và khả năng nhập dữ liệu đầy đủ, hãy sử dụng quy trình OAuth 2.0 dành cho thiết bị di động và máy tính. (Bạn nên sử dụng quy trình đó ngay cả khi ứng dụng là công cụ dòng lệnh 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 JWT để lấy thông tin cơ bản trong hồ sơ người dùng, hãy xem phần Đăng nhập trên TV và Thiết bị đầu vào hạn chế.

Điều kiện tiên quyết

Bật API cho dự án

Bất kỳ ứng dụng nào gọi API của Google đều phải 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 nhóm sản phẩm và mức độ phổ biến. Nếu API bạn muốn chọn không hiển thị 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 chứa API đó.
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 cấp phép

Bất kỳ ứng dụng nào dùng OAuth 2.0 để truy cập API của Google đều phải có thông tin xác thực ủy quyền giúp xác định ứng dụng đó với máy chủ OAuth 2.0 của Google. Các bước sau giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, các ứng dụng của bạn có thể dùng thông tin xác thực để truy cập vào những 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 khách OAuth.
3. Chọn loại ứng dụng TV và thiết bị đầu vào giới hạn.
4. Đặt tên cho ứng dụng khách OAuth 2.0 rồi nhấp vào 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 cần thiết, đồng thời cho phép người dùng kiểm soát số lượng quyền 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 đạt được sự đồng ý của người dùng.

Trước khi bắt đầu triển khai lệnh ủy 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.

Lưu ý: Ủy quyền gia tăng không được hỗ trợ cho các ứng dụng hoặc thiết bị đã cài đặt.

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

Nếu ứng dụng công khai của bạn sử dụng phạm vi cho phép truy cập vào một số dữ liệu người dùng nhất định, thì ứng dụng đó phải hoàn tất quy trình xác minh. Nếu thấy ứng dụng chưa được xác minh trên màn hình khi kiểm thử ứng dụng, bạn phải gửi một yêu cầu xác minh để xoá ứng dụng đó. Tìm hiểu thêm về ứng dụng chưa được xác minh và nhận câu trả lời cho các câu hỏi thường gặp về quy trình xác minh ứng dụng trong Trung tâm trợ giúp.

Lấy mã truy cập OAuth 2.0

Mặc dù ứng dụng chạy trên một thiết bị có chức năng nhập hạn chế, nhưng người dùng phải có quyền truy cập riêng vào một thiết bị có khả năng nhập phong phú hơn để hoàn tất quy trình uỷ quyền 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 đến máy chủ uỷ quyền của Google để xác định phạm vi mà ứng dụng yêu cầu cấp quyền truy cập.
2. Máy chủ phản hồi bằng một số thông tin được sử 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 sẽ hiển thị thông tin mà người dùng có thể nhập trên một thiết bị riêng biệt để uỷ quyền cho ứng dụng của bạn.
4. Ứng dụng của bạn bắt đầu thăm dò máy chủ uỷ quyền của Google để xác định xem người dùng có uỷ quyền cho ứng dụng của bạn hay không.
5. Người dùng chuyển sang một thiết bị có khả năng nhập liệu phong phú hơn, chạy trình duyệt web, chuyển đến URL hiển thị ở bước 3 và nhập mã cũng hiển thị ở bước 3. Sau đó, người dùng 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 phải ủy quyền cho các 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 sẽ không chứa mã thông báo.)

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

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

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

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

Các 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 Danh sách các phạm vi phân tách bằng dấu cách xác định các tài nguyên mà ứng dụng của bạn có thể thay mặt người dùng truy cập. Những giá trị này thông báo cho người dùng về màn hình xin phép mà Google hiển thị. Xem danh sách Phạm vi được phép đối với 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 các tài nguyên cần thiết, đồng thời cho phép người dùng kiểm soát số lượng quyền truy cập mà họ cấp vào ứng dụng của bạn. Do đó, có một mối tương quan 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.

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=

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

curl -d "client_id=client_id&scope=" \
     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 này hợp lệ, phản hồi của bạn sẽ là một đối tượng JSON chứa các thuộc tính sau:

Thuộc tính
device_code	Một giá trị duy nhất mà Google chỉ định để xác định thiết bị chạy ứng dụng đang yêu cầu uỷ quyền. Người dùng sẽ uỷ quyền cho thiết bị đó từ một thiết bị khác nhờ khả năng nhập dữ liệu phong phú hơn. 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 phép cho một ứ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ị chạy ứng dụng xác định một cách an toàn xem người dùng đã cấp quyền hoặc đã 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 hợp lệ. Trong thời gian đó, nếu người dùng không hoàn tất quy trình cấp phép 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, thì bạn có thể phải bắt đầu lại quy trình này từ bước 1.
interval	Khoảng thời gian tính bằng giây mà thiết bị của bạn sẽ chờ giữa các 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. Hãy xem bước 3 để biết thêm chi tiết.
user_code	Giá trị phân biệt chữ hoa chữ thường, xác định cho Google các phạm vi mà ứng dụng đang yêu cầu quyền truy cập. Giao diện người dùng sẽ hướng dẫn người dùng nhập giá trị này trên một thiết bị khác có chức năng nhập đầu vào phong phú hơn. Sau đó, Google sẽ sử dụng giá trị này để hiển thị đúng phạm vi 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	URL mà người dùng phải điều hướng đến trên một thiết bị riêng biệt để nhập user_code và cấp hoặc từ chối 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 yêu cầu mã thiết bị của bạn vượt quá hạn mức liên kết với mã ứng dụng khách của bạn, thì bạn sẽ nhận được phản hồi 403, trong đó có 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 thu được ở bước 2 cho người dùng. Cả hai giá trị đều có thể chứa bất kỳ ký tự nào in được từ bộ ký tự ASCII-US. Nội dung mà bạn hiển thị cho người dùng phải hướng dẫn người dùng chuyển đến verification_url trên một thiết bị riêng biệt và nhập user_code.

Thiết kế giao diện người dùng (UI) theo những quy tắc sau:

• user_code
  • user_code phải được hiển thị trong trường có thể xử lý 15 ký tự kích thước "W". Nói cách khác, nếu bạn có thể hiển thị mã WWWWWWWWWWWWWWW chính xác, giao diện người dùng của bạn sẽ hợp lệ và bạn nên sử dụng giá trị chuỗi đó khi kiểm thử cách 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à không được sửa đổi theo bất kỳ cách nào, chẳng hạn như thay đổi trường hợp hoặc chèn các ký tự định dạng khác.
• verification_url
  • Không gian hiển thị verification_url phải đủ rộng để xử lý một chuỗi URL dài 40 ký tự.
  • Bạn không nên sửa đổi verification_url dưới bất kỳ hình thức nào, ngoại trừ việc tuỳ ý xoá lược đồ để hiển thị. Nếu bạn dự đị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ả biến thể http và https.

Cảnh báo: Cả hai giá trị này đều có thể thay đổi và bạn không nên mã cứng một giá trị trong mã. Tương tự như vậy, bạn không nên sửa đổi các giá trị theo bất kỳ cách nào khác ngoài việc xoá lược đồ khỏi verification_url.

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 biệt để chuyển đến verification_url và cấp (hoặc từ chối) quyền truy cập, nên thiết bị gửi yêu cầu sẽ không tự động thông báo khi người dùng phản hồi yêu cầu truy cập đó. Do đó, thiết bị yêu cầu cần thăm dò máy chủ uỷ quyền của Google để xác định thời điểm người dùng phản hồi yêu cầu.

Thiết bị gửi yêu cầu sẽ tiếp tục gửi các 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 nhận được ở bước 2 đã hết hạn. interval được trả về ở bước 2 sẽ chỉ định khoảng thời gian (tính bằng giây) để chờ giữa các yêu cầu.

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

Các 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 được 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ụ sau đây cho thấy một 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 phản hồi yêu cầu cấp quyền truy cập

Lưu ý: Ứng dụng của bạn không cần phải làm gì ngoài giai đoạn này, ngoài việc thăm dò ý kiến máy chủ uỷ quyền như mô tả trong bước trước.

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

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

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 những phản hồi sau:

Đã cấp quyền truy cập

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 cho phép thiết bị của bạn truy cập các API của Google thay mặt người dùng. (Thuộc tính scope trong phản hồi xác định những API mà thiết bị có thể truy cập.)

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

Các trường
access_token	Mã thông báo mà ứng dụng của bạn gửi để cho phép một yêu cầu API của Google.
expires_in	Thời gian tồn tại của mã truy cập tính bằng giây.
refresh_token	Một 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 sẽ hợp lệ cho đến khi người dùng thu hồi quyền truy cập. 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 các chuỗi được 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ề. Hiện tại, 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ó giới hạn thời gian. Nếu cần quyền truy cập vào một API trong một khoảng thời gian dài, thì ứng dụng có thể sử dụng mã làm mới để lấy mã truy cập mới. Nếu ứng dụng cần loại quyền truy cập này, thì ứng dụng sẽ lưu trữ mã làm mới để sử dụng sau.

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ủ sẽ có mã trạng thái phản hồi HTTP 403 (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 uỷ quyền, thì máy chủ sẽ trả về một mã trạng thái phản hồi HTTP 428 (Precondition Required). Phản hồi chứa lỗi sau:

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

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ã trạng thái phản hồi HTTP 403 (Forbidden). Phản hồi chứa lỗi sau:

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

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ỳ tham số bắt buộc nào hoặc có giá trị tham số không chính xác. Các yêu cầu này thường có mã trạng thái phản hồi HTTP 400 (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ể uỷ quyền cho một hoặc nhiều phạm vi yêu cầu theo chính sách của quản trị viên Google Workspace. Xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát những ứng dụng nội bộ và của bên thứ ba truy cập vào dữ liệu trên 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 quyền truy cập rõ ràng được cấp cho mã ứng dụng khách OAuth của bạn.
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 giới hạn.
invalid_grant	400	Giá trị tham số code không hợp lệ, đã được xác nhận quyền sở hữu hoặc không thể 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 khách OAuth trong yêu cầu này là một phần của dự án hạn chế quyền truy cập vào Tài khoản Google trong một Tổ chức Google Cloud cụ thể. Xác nhận cấu hình loại người dùng cho ứng dụng OAuth của bạn.

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ã thông báo này để gọi API Google thay mặt cho một tài khoản người dùng nhất định nếu API đó đã cấp(các) phạm vi quyền truy cập mà ứng dụng cần. Để thực hiện việc này, hãy đưa mã truy cập vào một yêu cầu tới API bằng cách thêm giá trị tham số truy vấn access_token hoặc Authorization tiêu đề HTTP Bearer. Khi có thể, bạn nên chọn tiêu đề HTTP vì các chuỗi cụm từ tìm kiếm có xu hướng xuất hiện trong nhật ký máy chủ. Trong hầu hết trường hợp, bạn có thể sử dụng một 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 Drive Files).

Bạn có thể dùng thử tất 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

Lệnh gọi đến điểm cuối drive.files (API Drive Files) sử dụng tiêu đề 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 chính mình:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Sau đây là 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à một ví dụ về cách 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, tùy 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ã thông báo truy cập sẽ hết hạn và định kỳ trở thành thông tin xác thực không hợp lệ cho 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 (bao gồm cả khi người dùng không có mặt) nếu bạn đã yêu cầu quyền truy cập ngoại tuyến vào các phạm vi 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 yêu cầu HTTPS POST đến máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token) có chứa các tham số sau:

Các trường
client_id	Mã ứng dụng khách thu được từ API Console.
client_secret	Mật khẩu ứng dụng khách lấy từ API Console.
grant_type	Như đã xác định trong thông số kỹ thuật 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ừ hoạt động 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ề đối tượng JSON chứa mã truy cập mới. Đoạn mã sau đây cho thấy một phản hồi mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "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 cho mỗi tổ hợp khách hàng/người dùng và một giới hạn cho mỗi người dùng trên tất cả ứng dụng. Bạn nên lưu mã làm mới trong bộ nhớ dài hạn rồi tiếp tục sử dụng cho đến khi 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ì ứng dụng có thể gặp phải các giới hạn này. Trong trường hợp đó, mã làm mới cũ sẽ ngừng hoạt động.

Thu hồi mã thông báo

Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào phần Cài đặt tài khoản. Hãy xem tài liệu hỗ trợ Xoá trang web hoặc ứng dụng của các trang web và ứng dụng 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 lập trình. Thu hồi có lập trình có ý nghĩa quan trọng trong trường hợp người dùng hủy đăng ký, xóa một ứng dụng hoặ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 trong quy trình xóa có thể bao gồm một yêu cầu API để đảm bảo các quyền đã cấp cho ứng dụng trước đó đã bị xóa.

Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng sẽ yêu cầu https://oauth2.googleapis.com/revoke và đưa mã thông báo đó vào dưới dạng thông 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ã này 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 quá trình 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ột mã lỗi.

Lưu ý: Sau khi thu hồi được yêu cầu thu hồi thành công, có thể mất chút thời gian trước khi việc thu hồi đó có hiệu lực hoàn toàn.

Phạm vi được phép

Quy trình OAuth 2.0 cho thiết bị chỉ được hỗ trợ cho 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