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 tính năng uỷ quyền OAuth 2.0 để truy cập vào API Dữ liệu YouTube qua các ứng dụng chạy trên những 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 bị 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 trong khi vẫn bảo mật tên người dùng, mật khẩu và các thông tin khác của họ. Ví dụ: một ứng dụng TV có thể sử dụng OAuth 2.0 để được phép chọn một tệp được lưu trữ trên Google Drive.

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

Lựa chọ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ả Universal Windows Platform), có quyền truy cập vào trình duyệt và khả năng nhập đầy đủ, hãy sử dụng quy trình OAuth 2.0 cho ứng dụng dành cho thiết bị di động và máy tính. (Bạn nên sử dụng luồng này ngay cả khi ứng dụng của bạn là một 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 mã nhận dạng JWT để lấy thông tin cơ bản về hồ sơ người dùng, hãy xem phần Đă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

Bất kỳ ứng dụng nào gọi API của Google đề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. 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 uỷ quyền

Mọi ứng dụng dùng OAuth 2.0 để truy cập vào API Google đều phải có thông tin xác thực uỷ quyền giúp nhận dạng ứng dụng đó vớ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 đăng nhập để truy cập vào các 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 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, đồng thời cho phép người dùng kiểm soát 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ố phạm vi được yêu cầu và khả năng có được sự đồng ý của người dùng.

Trước khi bắt đầu triển khai tính năng 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/youtubeQuản lý tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.channel-memberships.creatorXem 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-sslXem, 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.readonlyXem tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.uploadQuản lý video trên YouTube của bạn
https://www.googleapis.com/auth/youtubepartnerXem 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-auditXem 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

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.

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ó khả năng đầu vào 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ó tính năng đầu vào 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 một yêu cầu đến máy chủ uỷ quyền của Google. Máy chủ này sẽ 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ủ phản hồi bằng một số thông tin 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 cho thấy thông tin mà người dùng có thể nhập trên một thiết bị khác để cấp 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 đã uỷ quyền cho ứng dụng của bạn hay chưa.
  5. Người dùng chuyển sang một thiết bị có tính năng nhập dữ liệu phong phú hơn, chạy một trình duyệt web, chuyển đến URL hiển thị ở bước 3 và nhập mã 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 mã thông báo mà ứng dụng của bạn cần để thay mặt người dùng uỷ quyền cho các yêu cầu. (Nếu người dùng từ chối truy cập vào ứng dụng, thì 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:

Người dùng đăng nhập trên một thiết bị riêng biệt 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. Do các chức năng và môi trường thời gian chạy mà thiết bị có thể có, các ví dụ 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ễ chuyển sang nhiều ngôn ngữ và 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

Ở bước này, thiết bị của bạn sẽ gửi một 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). Máy chủ này sẽ xác định ứng dụng của bạn cũng như các 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á bằng cách sử dụng giá trị siêu dữ liệu device_authorization_endpoint. Hãy bao gồm các tham số yêu cầu HTTP sau đây:

Thông số
client_id Bắt buộc

Mã ứng dụng khách của ứng dụng. Bạn có thể tìm thấy giá trị này trong API Console Credentials page.

scope Bắt buộc

Một danh sách phạm vi được phân tách bằng dấu cách giúp xác định những 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 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 các tài nguyên mà ứng dụng cần, đồng thời cho phép người dùng kiểm soát lượng quyền truy cập mà họ cấp cho ứng dụng của bạn. 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:

Kính ngắm
https://www.googleapis.com/auth/youtubeQuản lý tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.channel-memberships.creatorXem 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-sslXem, 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.readonlyXem tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.uploadQuản lý video trên YouTube của bạn
https://www.googleapis.com/auth/youtubepartnerXem 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-auditXem 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 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 vào các API của Google.

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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly

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

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
     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à một đối tượng JSON chứa các thuộc tính sau:

Thuộc tính
device_code Giá trị mà Google gán 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ẽ cấp phép cho thiết bị đó từ một thiết bị khác có khả năng đầu vào 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 quyền 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 truy cập hay từ chối quyền truy cập.

expires_in Khoảng thời gian (tính bằng giây) mà device_codeuser_code hợp lệ. Trong thời gian đó, nếu người dùng không hoàn tất quy trình uỷ quyền 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ể 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ị của bạn sẽ chờ giữa các yêu cầu thăm dò. Ví dụ: nếu giá trị là 5, thì cứ 5 giây một lần, thiết bị của bạn sẽ gửi một yêu cầu thăm dò đến máy chủ uỷ quyền của Google. Hãy xem bước 3 để biết thêm thông tin.
user_code Một giá trị phân biệt chữ hoa chữ thường giúp Google xác định 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ị riêng có khả năng nhập phong phú hơn. Sau đó, Google sẽ dùng giá trị này để hiển thị đúng nhóm 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 Một URL mà người dùng phải truy cập trên một thiết bị riêng biệt để nhập user_code cũng như 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 câu trả lờ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 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ị cho người dùng verification_urluser_code thu được ở bước 2. Cả hai giá trị đều có thể chứa bất kỳ ký tự nào có thể in được từ bộ ký tự US-ASCII. Nội dung mà bạn hiển thị cho người dùng phải hướng dẫn họ chuyển đến verification_url trên một thiết bị riêng biệt và nhập user_code.

Hãy lưu ý đến các quy tắc sau đây khi thiết kế giao diện người dùng (UI) của bạn:

  • user_code
    • user_code phải được hiển thị trong một trường có thể xử lý 15 ký tự có kích thước "W". Nói cách khác, nếu có thể hiển thị mã WWWWWWWWWWWWWWW chính xác, thì giao diện người dùng của bạn sẽ hợp lệ. Bạn cũng 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 nên sửa đổi theo bất kỳ cách nào, chẳng hạn 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ý 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 xoá giao thức hiển thị (không bắt buộc). 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 rằng ứng dụng của bạn có thể xử lý cả biến thể httphttps.

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ị yêu cầu sẽ không tự động nhận được 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ị 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_codeuser_code nhận được trong bước 2 đã hết hạn. interval được trả về trong bước 2 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 cần thăm dò ý kiến là https://oauth2.googleapis.com/token. Yêu cầu thăm dò ý kiến chứa các thông số sau:

Thông số
client_id Mã ứng dụng khách của ứng dụng. 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 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 phản hồ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ọ chuyển đến 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à đăng nhập vào Google (nếu chưa đăng nhập), người dùng sẽ thấy màn hình đồng ý như màn hình minh hoạ dưới đây:

Ví dụ về màn hình đồng ý 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ò

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

Đã 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ột mã truy cập và một mã làm mới. Mã thông báo này cho phép thiết bị của bạn thay mặt người dùng truy cập vào các API của Google. (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 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 để uỷ quyền cho một 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 các chuỗi được phân tách bằng dấu cách và 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 câu trả lờ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 gian tồn tại giới hạn. Nếu cần quyền truy cập vào một API trong một thời gian dài, ứng dụng của bạn có thể sử dụng mã làm mới để lấy mã truy cập mới. Nếu cần loại quyền truy cập này, ứng dụng của bạn nên lưu trữ mã làm mới để sử dụng sau này.

Quyền 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 này có lỗi sau:

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

Đang chờ uỷ quyền

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

{
  "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ỳ tham số 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ã 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 Nội dung 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 theo yêu cầu theo 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 những ứng dụng nội bộ và ứng dụng 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 các phạm vi cho đến khi mã ứng dụng khách OAuth của bạn được cấp quyền truy cập một cách rõ ràng.
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. Nhớ đặt loại ứng dụng cho mã ứng dụng khách thành TV và thiết bị đầu vào bị hạn chế.

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ị thông số grant_type không hợp lệ.
org_internal 403 Mã ứng dụng khách OAuth trong yêu cầu là một phần của dự án giới hạn quyền truy cập vào các Tài khoản Google trong một tổ chức cụ thể trên Google Cloud. Xác nhận cấu hình loại người dùng 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ã thông báo này để thực hiện lệnh gọi đến một API Google thay mặt cho một tài khoản người dùng cụ thể 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 đưa mã truy cập vào một yêu cầu gửi tới API bằng cách cung cấp tham số truy vấn access_token hoặc giá trị tiêu đề HTTP Authorization Bearer. Khi có thể, bạn nên sử dụng tiêu đề HTTP vì các chuỗi truy vấn thường hiển thị trong nhật ký máy chủ. Trong hầu hết các trường hợp, bạn có thể sử dụng thư viện ứng dụng để thiết lập lệnh gọi đến các API của Google (ví dụ: khi gọi YouTube Data API).

Xin lưu ý rằng YouTube Data API chỉ hỗ trợ tài khoản dịch vụ dành cho những chủ sở hữu nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube, chẳng hạn như hãng thu âm và hãng phim.

Bạn có thể dùng thử tất cả các API của Google và xem phạm vi của các API đó tại Playground 2.0 của OAuth.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối youtube.channels (API Dữ liệu YouTube) sử dụng tiêu đề HTTP Authorization: Bearer có thể có dạng như sau. Lưu ý rằng bạn cần chỉ định mã truy cập của riêng mình:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Dưới đây là lệnh gọi tới cùng một API cho người dùng đã xác thực bằng cách sử dụng tham số chuỗi truy vấn access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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. Dưới đây là 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/channels?part=snippet&mine=true

Hoặc cách khác là lựa chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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

Mã thông báo truy cập sẽ hết hạn theo định kỳ và trở thành thông tin xác thực không hợp lệ cho một yêu cầu API liên quan. Bạn có thể làm mới mã truy cập mà không cần nhắc người dùng cấp quyền (kể cả khi người dùng không có mặt) nếu bạn đã yêu cầu quyền truy cập ngoại tuyến vào các phạm vi được liên kết với mã thông báo.

Để làm mới mã truy cập, ứng dụng của bạn sẽ gửi yêu cầu POST HTTPS đến 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 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 của 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ã 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ó một 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 ứng dụng/người dùng và một giới hạn khác cho mỗi người dùng trên tất cả các ứng dụng. Bạn nên lưu mã thông báo làm mới vào bộ nhớ dài hạn và tiếp tục sử dụng các mã này cho đến khi các mã này vẫn hợp lệ. Nếu 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 đó, những 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 ứ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ợ về Xoá quyền truy cập vào trang web hoặc ứng dụng trong phần 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 lập trình. Việc thu hồi có lập trình đóng vai trò quan trọng trong những trường hợp người dùng huỷ đăng ký, xoá ứ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 của quy trình xoá có thể bao gồm cả yêu cầu API để đảm bảo các quyền đã cấp trước đó cho ứng dụng sẽ bị xoá.

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

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