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 uỷ quyền OAuth 2.0 để truy cập vào YouTube Data API 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 những 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 liệu 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 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 truyền hình có thể sử dụng OAuth 2.0 để được cấp 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 từng thiết bị, nên giả định rằng các ứng dụng không thể giữ bí mật. Các ứng dụng này có thể truy cập vào API của Google trong khi người dùng đang ở trong ứng dụng hoặc khi ứng dụng đang chạy ở chế độ nền.

Giải pháp 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ả Nền tảng Windows đa năng), có quyền truy cập vào trình duyệt và khả năng nhập liệu đầy đủ, hãy sử dụng quy trình OAuth 2.0 cho ứng dụng di động và ứng dụng dành cho máy tính. (Bạn nên sử dụng quy trình đó 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 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ị có chế độ đầu vào hạn chế.

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

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ả những API đó.

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

1. Go to the Credentials page.
2. Nhấp vào Tạo ứng dụng.
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 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 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.

YouTube Data API phiên bản 3 sử dụng các phạm vi sau:

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 liệu 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 liệu 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 để 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 đượ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 để 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 đã 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ó nhiều khả năng nhập liệu 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ã 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 sẽ chứa các mã thông báo mà ứng dụng của bạn cần để uỷ quyền các yêu cầu thay cho người dùng. (Nếu người dùng từ chối cấp quyền truy cập cho ứng dụng của bạn, thì phản hồi sẽ không chứa mã thông báo.)

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

Các phần sau đây sẽ giải thích chi tiết những bước này. Vì các thiết bị có thể có nhiều chức năng và môi trường thời gian chạy, nên các ví dụ trong tài liệu này sử dụng tiện ích dòng lệnh curl. Bạn có thể dễ dàng chuyển các ví dụ này 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

Trong bước này, thiết bị của bạn sẽ gửi một yêu cầu HTTP POST đến 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ư các phạm vi truy cập mà ứng dụng muốn truy cập thay cho 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. Thêm các tham số yêu cầu HTTP sau đây:

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ụ này 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:

Đ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 được liên kết với mã ứng dụng khách, 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ốc độ 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ự in nào trong 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 người dùng chuyển đến verification_url trên một thiết bị riêng và nhập user_code.

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

• user_code
  • user_code phải xuất hiện 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 bạn có thể hiển thị mã WWWWWWWWWWWWWWW một cách chính xác, thì giao diện người dùng của bạn là 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à bạn không được sửa đổi theo bất kỳ cách nào, chẳng hạn như thay đổi cách viết hoa và viết thường hoặc chèn các ký tự định dạng khác.
• verification_url
  • Không gian mà 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 theo bất kỳ cách nào, ngoại trừ việc xoá lược đồ để hiển thị (không bắt buộc). Nếu bạn dự định xoá 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.

Bước 4: Gửi yêu cầu đến 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, 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. Vì lý 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 phải tiếp tục gửi các yêu cầu thăm dò 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 thu đượ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) cần chờ giữa các yêu cầu.

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

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ụ nà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 cho thấy 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:

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ột màn hình đồng ý như màn hình bên dưới:

Bước 6: Xử lý các phản hồi cho 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ò 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ã truy cập và mã làm mới. Các mã thông báo này cho phép thiết bị của bạn truy cập vào các API của Google thay cho người dùng. (Thuộc tính scope trong phản hồi sẽ 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:

Đ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 gian tồn tại giới hạn. Nếu cần truy cập vào một API trong 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.

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 chứa 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ã trạng thái phản hồi HTTP 428 (Precondition Required). Phản hồi này 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 này 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 bị 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:

Gọi các 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 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ể 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 Dữ liệu của YouTube).

Xin lưu ý rằng YouTube Data API chỉ hỗ trợ tài khoản dịch vụ 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 OAuth 2.0 Playground.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối youtube.channels (YouTube Data API) bằng cách 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 riêng mình:

GET /youtube/v3/channels?part=snippet&mine=true 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/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. 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/youtube/v3/channels?part=snippet&mine=true

Hoặc, bạn có thể 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ã truy cập sẽ hết hạn đị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 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ó 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 một 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:

Đ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 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ã làm mới sẽ được cấp; 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ã làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng mã này miễn là mã còn hiệu lực. 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 những 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 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á.

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

Phạm vi được phép

Luồng OAuth 2.0 cho thiết bị chỉ được hỗ trợ cho các phạm vi sau:

Quyền truy cập theo thời gian

Quyền truy cập dựa trên thời gian cho phép người dùng cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu của họ trong một khoảng thời gian giới hạn để hoàn tất một hành động. Quyền truy cập dựa trên thời gian có trong một số sản phẩm của Google trong quy trình đồng ý, cho phép người dùng cấp quyền truy cập trong một khoảng thời gian giới hạn. Ví dụ: Data Portability API cho phép chuyển dữ liệu một lần.

Khi người dùng cấp cho ứng dụng của bạn quyền truy cập dựa trên thời gian, mã làm mới sẽ hết hạn sau khoảng thời gian được chỉ định. Xin lưu ý rằng mã làm mới có thể bị vô hiệu hoá sớm hơn trong những trường hợp cụ thể; hãy xem những trường hợp này để biết thông tin chi tiết. Trường refresh_token_expires_in được trả về trong phản hồi trao đổi mã uỷ quyền cho biết thời gian còn lại cho đến khi mã làm mới hết hạn trong những trường hợp như vậy.