OAuth 2.0 cho ứng dụng dành cho thiết bị di động và máy tính

Tài liệu này giải thích cách các ứng dụng được cài đặt trên các thiết bị như điện thoại, máy tính bảng và máy tính sử dụng các điểm cuối OAuth 2.0 của Google để cho phép truy cập vào YouTube Analytics API hoặc YouTube Reporting API.

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 có thể sử dụng OAuth 2.0 để được cấp quyền truy xuất dữ liệu YouTube Analytics của một kênh.

Các ứng dụng đã cài đặt được phân phối cho từng thiết bị và giả định rằng những ứng dụng này không thể giữ bí mật. Chúng có thể truy cập vào các 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.

Quy trình uỷ quyền này tương tự như quy trình được dùng cho các ứng dụng máy chủ web. Điểm khác biệt chính là các ứng dụng đã cài đặt phải mở trình duyệt hệ thống và cung cấp một URI chuyển hướng cục bộ để xử lý các phản hồi từ máy chủ uỷ quyền của Google.

Thư viện và mẫu

Đối với ứng dụng di động, bạn nên dùng phiên bản mới nhất của thư viện gốc Dịch vụ nhận dạng của Google cho Android và thư viện gốc Đăng nhập bằng Google cho iOS. Các thư viện này xử lý việc uỷ quyền cho người dùng và dễ triển khai hơn so với giao thức cấp thấp được mô tả ở đây.

Đối với các ứng dụng chạy trên những thiết bị không hỗ trợ trình duyệt hệ thống hoặc có khả năng đầu vào hạn chế, chẳng hạn như TV, máy chơi trò chơi, máy ảnh hoặc máy in, hãy xem OAuth 2.0 cho TV và thiết bị hoặc Đă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 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 Analytics API cũng như API Báo cáo của YouTube. Nhiều ứng dụng truy xuất dữ liệu trong YouTube Analytics cũng tương tác với 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. Các phần sau đây mô tả các loại ứng dụng mà máy chủ uỷ quyền của Google hỗ trợ. Chọn loại ứng dụng khách được đề xuất cho ứng dụng của bạn, đặt tên cho ứng dụng khách OAuth và đặt các trường khác trong biểu mẫu cho phù hợp.

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 Analytics API sử dụng các phạm vi sau:

YouTube Reporting API sử dụng các phạm vi sau:

Tài liệu Phạm vi API OAuth 2.0 chứa danh sách đầy đủ các phạm vi mà bạn có thể sử dụng để truy cập vào các API của Google.

Lấy mã truy cập OAuth 2.0

Các bước sau đây cho biết cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để nhận được sự đồng ý của người dùng nhằm thực hiện một yêu cầu API thay cho người dùng. Ứng dụng của bạn phải có sự đồng ý đó thì mới có thể thực thi yêu cầu Google API cần có sự uỷ quyền của người dùng.

Bước 1: Tạo trình xác minh mã và thử thách

Google hỗ trợ giao thức Khoá bằng chứng để trao đổi mã (PKCE) nhằm giúp quy trình cài đặt ứng dụng trở nên an toàn hơn. Một trình xác minh mã riêng biệt được tạo cho mọi yêu cầu uỷ quyền và giá trị đã chuyển đổi của trình xác minh này (gọi là "code_challenge") sẽ được gửi đến máy chủ uỷ quyền để lấy mã uỷ quyền.

Tạo trình xác minh mã

code_verifier là một chuỗi ngẫu nhiên mật mã có entropy cao, sử dụng các ký tự không dành riêng [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", có độ dài tối thiểu là 43 ký tự và độ dài tối đa là 128 ký tự.

Trình xác minh mã phải có đủ độ ngẫu nhiên để khiến việc đoán giá trị trở nên bất khả thi.

Tạo thử thách về mã

Chúng tôi hỗ trợ 2 phương thức tạo thử thách mã.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Bước 2: Gửi yêu cầu đến máy chủ OAuth 2.0 của Google

Để nhận được sự uỷ quyền của người dùng, hãy gửi yêu cầu đến máy chủ uỷ quyền của Google tại https://accounts.google.com/o/oauth2/v2/auth. Điểm cuối này xử lý việc tra cứu phiên hoạt động, xác thực người dùng và lấy sự đồng ý của người dùng. Chỉ có thể truy cập vào điểm cuối qua SSL và điểm cuối này từ chối các kết nối HTTP (không phải SSL).

Máy chủ uỷ quyền hỗ trợ các tham số chuỗi truy vấn sau đây cho các ứng dụng đã cài đặt:

URL uỷ quyền mẫu

Các thẻ bên dưới cho thấy các URL uỷ quyền mẫu cho các lựa chọn URI chuyển hướng khác nhau.

Các URL này giống hệt nhau, ngoại trừ giá trị của tham số redirect_uri. Các URL này cũng chứa các tham số bắt buộc response_type và client_id, cũng như tham số không bắt buộc state. Mỗi URL chứa dấu ngắt dòng và dấu cách để dễ đọc.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Bước 3: Google nhắc người dùng đồng ý

Trong bước này, người dùng sẽ quyết định có cấp cho ứng dụng của bạn quyền truy cập được yêu cầu hay không. Ở giai đoạn này, Google sẽ hiển thị một cửa sổ đồng ý cho biết tên của ứng dụng và các dịch vụ Google API mà ứng dụng đang yêu cầu quyền truy cập bằng thông tin xác thực uỷ quyền của người dùng, cũng như bản tóm tắt về các phạm vi truy cập sẽ được cấp. Sau đó, người dùng có thể đồng ý cấp quyền truy cập vào một hoặc nhiều phạm vi mà ứng dụng của bạn yêu cầu hoặc từ chối yêu cầu.

Ứng dụng của bạn không cần làm gì ở giai đoạn này vì ứng dụng sẽ đợi phản hồi từ máy chủ OAuth 2.0 của Google cho biết có quyền truy cập nào được cấp hay không. Phản hồi đó được giải thích trong bước tiếp theo.

Bước 4: Xử lý phản hồi của máy chủ OAuth 2.0

Cách ứng dụng của bạn nhận được phản hồi uỷ quyền phụ thuộc vào lược đồ URI chuyển hướng mà ứng dụng đó sử dụng. Bất kể lược đồ nào, phản hồi sẽ chứa mã uỷ quyền (code) hoặc lỗi (error). Ví dụ: error=access_denied cho biết người dùng đã từ chối yêu cầu.

Nếu người dùng cấp quyền truy cập cho ứng dụng của bạn, bạn có thể trao đổi mã uỷ quyền để lấy mã truy cập và mã làm mới như mô tả trong bước tiếp theo.

Bước 5: Trao đổi mã uỷ quyền để lấy mã làm mới và mã truy cập

Để đổi mã uỷ quyền lấy mã truy cập, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt 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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google phản hồi yêu cầu này bằng cách trả về một đối tượng JSON chứa mã truy cập có thời hạn ngắn và mã làm mới.

Phản hồi 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,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Bước 6: Kiểm tra xem người dùng đã cấp quyền truy cập vào những phạm vi nào

Khi yêu cầu nhiều quyền (phạm vi), người dùng có thể không cấp cho ứng dụng của bạn quyền truy cập vào tất cả các quyền đó. Ứng dụng của bạn phải xác minh những phạm vi nào đã được cấp và xử lý một cách linh hoạt những trường hợp một số quyền bị từ chối, thường là bằng cách tắt các tính năng dựa vào những phạm vi bị từ chối đó.

Tuy nhiên, vẫn có một số trường hợp ngoại lệ. Các ứng dụng Google Workspace Enterprise có quyền uỷ quyền trên toàn miền hoặc các ứng dụng được đánh dấu là Đáng tin cậy sẽ bỏ qua màn hình đồng ý cấp quyền chi tiết. Đối với những ứng dụng này, người dùng sẽ không thấy màn hình đồng ý cấp quyền chi tiết. Thay vào đó, ứng dụng của bạn sẽ nhận được tất cả các phạm vi được yêu cầu hoặc không nhận được phạm vi nào.

Để biết thêm thông tin chi tiết, hãy xem bài viết Cách xử lý các quyền ở cấp độ chi tiết.

Để kiểm tra xem người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào một phạm vi cụ thể hay chưa, hãy kiểm tra trường scope trong phản hồi mã truy cập. Phạm vi truy cập được cấp bởi access_token dưới dạng danh sách các chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.

Ví dụ: phản hồi mã truy cập mẫu sau đây cho biết rằng người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào quyền chỉ đọc đối với hoạt động trên Drive và sự kiện trên Lịch:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

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ể sử 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 Phân tích YouTube).

Xin lưu ý rằng YouTube Analytics API không hỗ trợ quy trình tài khoản dịch vụ. YouTube Reporting 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 reports.query (YouTube Analytics API) bằng cách sử dụng tiêu đề HTTP Authorization: Bearer có thể trô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/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views 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/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

Hoặc, bạn có thể chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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 https://www.googleapis.com/auth/calendar.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ương thức chuyển hướng ứng dụng

Bảo vệ ứng dụng của bạn

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.

Tài liệu đọc thêm

Phương pháp hay nhất hiện tại của IETF OAuth 2.0 cho ứng dụng gốc thiết lập nhiều phương pháp hay nhất được ghi lại ở đây.