Tài liệu này giải thích cách triển khai ủy quyền OAuth 2.0 để truy cập API dữ liệu YouTube thông qua các ứng dụng chạy trên thiết bị như TV, bảng điều khiển 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 dữ liệu có giới hạn.
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 bảo mật tên người dùng, mật khẩu và các thông tin khác. Ví dụ: ứng dụng TV có thể sử dụng OAuth 2.0 để có quyền chọn tệp được lưu trữ trên Google Drive.
Vì 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 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 đang ở ứ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 một ứng dụng cho 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 liệu đầy đủ, hãy sử dụng quy trình OAuth 2.0 dành cho ứng dụng trên thiết bị di động và máy tính. (Bạn nên sử dụng luồng đó ngay cả khi ứng dụng của bạn 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 vào các tài khoản Google của người dùng và sử dụng mã nhận dạng 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à các thiết bị đầu vào có giới hạn.
Đ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 của Google đều cần bật những 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.
- Sử dụng trang Thư viện để tìm và bật API dữ liệu YouTube. Tìm mọi API khác mà ứng dụng của bạn cũng sẽ sử dụng và bật các API đó.
Tạo thông tin xác thực ủy quyền
Bất kỳ ứng dụng nào sử dụng OAuth 2.0 để truy cập API Google đều phải có thông tin đăng nhập ủy quyền để 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 đă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 thông tin xác thực > Mã ứng dụng khách OAuth.
- Chọn loại ứng dụng TV và thiết bị đầu vào giới hạn.
- Đặ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 tài nguyên cần thiết trong khi cũng 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ó 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 lấy được sự đồng ý của người dùng.
Trước khi bắt đầu triển khai việc cấp quyền OAuth 2.0, bạn nên xác định các phạm vi mà ứng dụng của mình sẽ cần quyền truy cập.
API dữ liệu YouTube v3 sử dụng các phạm vi sau:
| Kính ngắm | |
|---|---|
| https://www.googleapis.com/auth/youtube | Quản lý tài khoản YouTube của bạn |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | Xem 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-ssl | Xem, 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.readonly | Xem tài khoản YouTube của bạn |
| https://www.googleapis.com/auth/youtube.upload | Quản lý video trên YouTube của bạn |
| https://www.googleapis.com/auth/youtubepartner | Xem 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-audit | Xem 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 dành 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ế, 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 cấp quyền này. Quy trình có các bước sau:
- Ứ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 của bạn sẽ yêu cầu quyền truy cập.
- 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.
- 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 để ủy quyền cho ứng dụng của bạn.
- Ứ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.
- 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 một trình duyệt web, chuyển đến URL hiển thị ở bước 3 và nhập một mã cũng được 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.
- Nội dung 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ần để ủy quyền thay mặt người dùng yêu cầu. (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 bên dưới minh họa quá trình này:
Phần sau đây giải thích chi tiết các bước này. Dựa trên khả năng và môi trường thời gian chạy mà các 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ễ dàng chuyển 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 POST qua HTTP đến 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 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 về 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 tham số yêu cầu HTTP sau:
| 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 API Console Credentials page. |
||||||||||||||||
scope |
Bắt buộc
Danh sách phạm vi được phân tách bằng dấu cách xác định 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 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ối quan hệ nghịch đảo giữa số lượng phạm vi được yêu cầu và khả năng lấy được sự đồng ý của người dùng. API dữ liệu YouTube v3 sử dụng các phạm vi sau:
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 API 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ụ nà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%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ủ ủy 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ị do Google chỉ định duy nhất để xác định thiết bị chạy ứng dụng yêu cầu cấp quyền. Người dùng sẽ uỷ quyền cho thiết bị đó bằng một thiết bị khác có khả năng nhập 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 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 việc người dùng đã cấp quyền hay từ chối. |
expires_in |
Khoảng thời gian tính bằng giây mà device_code và user_code hợp lệ. Nếu trong thời gian đó, người dùng không hoàn tất quy trình ủy quyền và thiết bị của bạn cũng không thăm dò ý kiến để lấy thông tin về quyết định của người dùng, thì bạn có thể phải khởi động 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ẽ đợi 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 một 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 thông tin chi tiết. |
user_code |
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ị khác có khả năng nhập phong phú hơn. Sau đó, Google sẽ sử dụng giá trị để hiển thị đúng tập hợp các 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 chuyển đến trên một thiết bị riêng để 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 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
}
Đã vượt quá định mức phản hồi
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, 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 trong bước 2 cho người dùng. 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 người dùng chuyển đến verification_url trên một thiết bị khác và 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_codeuser_codephải được hiển thị trong trường có thể xử lý ký tự kích thước 15 'W'. Nói cách khác, nếu có thể hiển thị chính xác mãWWWWWWWWWWWWWWW, 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áchuser_codehiển thị trong giao diện người dùng.user_codecó 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 kiểu chữ hoặc chèn các ký tự định dạng khác.
verification_url- Khoảng trống hiển thị
verification_urlphả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_urltheo bất kỳ cách nào, ngoại trừ việc tuỳ chọn xoá giao thức hiển thị. Nếu bạn có kế hoạch 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ảhttpvàhttps.
- Khoảng trống hiển thị
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, nên thiết bị 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 phải 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 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 chỉ định khoảng thời gian (tính bằng giây) để chờ nhận 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
chứa các thông số sau:
| Thông 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ủ ủy 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ụ nà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 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ị ở bước 3:
Sau khi nhập user_code và nếu chưa đăng nhập và đăng nhập vào Google, thì người dùng sẽ thấy màn hình xin phép như màn hình bên dưới:
Bước 6: Xử lý phản hồi đối với yêu cầu bỏ phiếu
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 những 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. Mã thông báo cho phép thiết bị 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 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 để ủy quyền yêu cầu API của Google. |
expires_in |
Thời gian tồn tại của mã thông báo 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 sẽ hợp lệ cho đến khi người dùng thu hồi quyền truy cập. Lưu ý rằng mã thông báo làm mới luôn được trả về cho thiết bị. |
scope |
Phạm vi truy cập do 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ề. 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 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ã thông báo truy cập có thời gian giới hạn. 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ủ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 quyền truy cập này, ứ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 có 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 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
có 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ò ý kiến 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 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). Các 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ể ủy quyền cho một hoặc nhiều phạm vi được yêu cầu do các 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 các ứng dụng nội bộ và ứng dụng bên thứ ba sẽ 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 quyền truy cập rõ ràng vào 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ố Loại ứng dụng khách OAuth không chính xác. Đảm bảo rằng loại ứng dụng cho mã ứng dụng được đặt thành TV và thiết bị đầu vào có giới hạn. |
invalid_grant |
400 |
Giá trị thông số code là 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 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 cụ thể của Google Cloud. Xác nhận cấu hình loại người dùng cho ứng dụng OAuth. |
Gọi API Google
Sau khi ứng dụng của bạn lấy đượ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 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 quyền 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 tới API bằng cách đưa vào một tham số truy vấn access_token hoặc một giá trị Bearer tiêu đề HTTP Authorization. Khi có thể, bạn nên ưu tiên tiêu đề HTTP hơn 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 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 API Google (ví dụ: khi gọi cho API dữ liệu YouTube).
Xin lưu ý rằng API dữ liệu YouTube 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ả API của Google và xem phạm vi của chúng tại OAuth 2.0 Playground.
Ví dụ về HTTP GET
Lệnh gọi đến điểm cuối
youtube.channels (API dữ liệu YouTube) bằ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
Dưới đâ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/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ụ 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/youtube/v3/channels?part=snippet&mine=true
Hoặc, có thể là, tùy 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ã thông báo 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ệ đối với 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 hiện diện) 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 một 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:
| Các 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 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ừ lần trao đổi mã ủy 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, thì 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 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"
}
Lưu ý rằng sẽ 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 ứ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ả ứng dụng. Bạn nên lưu các mã làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng miễn là các mã này 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, ứng dụng có thể bị giới hạn. Trong trường hợp này, mã thông báo 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 ứ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. Vui lòng xem tài liệu hỗ trợ Xóa trang web hoặc ứng dụng của 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. 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 của quy trình xóa có thể bao gồm một yêu cầu API để đảm bảo những quyền trước đây đã cấp cho ứng dụng bị xóa.
Để thu hồi 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à bao gồm mã thông bá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}
Đâ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, 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ã lỗi.
Các phạm vi được phép
Quy trình OAuth 2.0 cho thiết bị chỉ được hỗ trợ trong các phạm vi sau:
OpenID Connect, Đăng nhập bằng Google
emailopenidprofile
API Drive
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
API YouTube
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly