OAuth 2.0 cho Mobile & Ứng dụng trên 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 điểm cuối OAuth 2.0 của Google để uỷ quyền truy cập vào các API của Google.

OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với ứng dụng trong khi vẫn đảm bảo sự riêng tư cho 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 để xin người dùng cấp quyền lưu trữ tệp trong Google Drive.

Các ứng dụng đã cài đặt được phân phối đến các thiết bị riêng lẻ và được 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 các API của Google khi người dùng đang sử dụng ứng dụng hoặc khi ứng dụng đang chạy trong nền.

Quy trình uỷ quyền này tương tự như quy trình dùng cho ứ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 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.

Lựa chọn thay thế

Đối với ứng dụng dành cho thiết bị di động, bạn nên dùng tính năng Đăng nhập bằng Google cho Android hoặc iOS. Thư viện ứng dụng Đăng nhập bằng Google xử lý việc xác thực và uỷ quyền cho người dùng, đồng thời các thư viện này có thể dễ triển khai hơn so với giao thức cấp thấp hơn đượ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 nhập bị 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ế.

Thư viện và mẫu

Bạn nên sử dụng các thư viện và mẫu sau để giúp triển khai quy trình OAuth 2.0 được mô tả trong tài liệu này:

• Thư viện AppAuth cho Android
• Thư viện AppAuth cho iOS
• OAuth cho ứng dụng: Mẫu Windows

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

Bật API cho dự án của bạ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. 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 mà bạn muốn bật không xuất hiện 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 xác thực uỷ quyền

Mọi ứng dụng dùng OAuth 2.0 để truy cập vào API của Google đều phải có thông tin xác thực uỷ 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 đó, ứng dụng của bạn có thể sử dụng thông tin xác thực để 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. Các phần dưới đây mô tả các loại ứng dụng và phương thức chuyển hướng mà máy chủ uỷ quyền của Google hỗ trợ. Chọn loại ứng dụng đượ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 sao 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 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ố lượng 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 những phạm vi mà ứng dụng sẽ cần quyền truy cập.

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ể dùng để truy cập vào các API của Google.

Nhận mã truy cập OAuth 2.0

Các bước sau đây cho thấy cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để có được sự đồng ý của người dùng để thực hiện yêu cầu API thay mặt cho người dùng. Ứng dụng của bạn phải có được sự đồng ý đó thì mới có thể thực thi yêu cầu API của Google cần có sự cho phép của người dùng.

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

Google hỗ trợ giao thức Khoá bằng chứng để Trao đổi mã (PKCE) để giúp quy trình ứng dụng được cài đặt an toàn hơn. Mỗi yêu cầu uỷ quyền sẽ được tạo một trình xác minh mã riêng và giá trị chuyển đổi của yêu cầu này có tên là "code_Challenge" (thách thức mã) 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] / "-" / "." / "_" / "~", với độ 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ó đủ entropy để khiến việc đoán giá trị không thực tế.

Tạo thử thách mã

Hỗ trợ hai 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ự cho phép của người dùng, hãy gửi yêu cầu tới 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ý hoạt động tra cứu phiên đang hoạt động, xác thực người dùng và lấy sự đồng ý của người dùng. Điểm cuối chỉ có thể truy cập được qua SSL và từ chối các kết nối HTTP (không có 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ẻ dưới đây hiển thị URL uỷ quyền mẫu cho các tuỳ chọn URI chuyển hướng khác nhau.

Các URL 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ố response_type và client_id bắt buộc, cũng như tham số state không bắt buộc. Mỗi URL đều chứa các dấu ngắt dòng và khoảng trắng để bạn dễ đọc.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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 quyết định có cấp cho ứng dụng của bạn quyền truy cập đã yêu cầu hay không. Ở giai đoạn này, Google sẽ hiện một cửa sổ đồng ý cho biết tên ứng dụng của bạn và các dịch vụ API của Google 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, kèm theo thông tin tóm tắt về phạm vi quyền truy cập cần đượ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 đang chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu 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 sau.

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 vào ứng dụng của bạn, bạn có thể đổ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à thiết lập 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 ngắn hạ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 câu trả lời mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.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ã thông báo này để thay mặt một tài khoản người dùng cụ thể thực hiện lệnh gọi đến API của Google 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 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 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 thư viện ứng dụng để thiết lập lệnh gọi đến API Google (chẳng hạn như khi gọi API Tệp Drive).

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 API OAuth 2.0.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối drive.files (API Drive Files) 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 /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Dưới đây là một 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/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. 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/drive/v2/files

Hoặc lựa chọn khác là tuỳ 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 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 (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 đượ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). Yêu cầu này bao gồm 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ề đố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 ứ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 trong bộ nhớ dài hạn và tiếp tục sử dụng các mã này 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ũ 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ợ về 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 rất quan trọng trong những trường hợp người dùng huỷ đăng ký, xoá ứ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 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ã thông báo theo phương thức lập trình, ứng dụng sẽ gửi yêu cầu tới https://oauth2.googleapis.com/revoke và đưa mã thông báo vào dưới dạng 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 quy 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 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 nêu tại đây.