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 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 để cho phép truy cập vào 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 giữ cho tên người dùng, mật khẩu và các thông tin khác ở chế độ riêng tư. Ví dụ: một ứng dụng có thể dùng OAuth 2.0 để được cấp quyền người dùng lưu trữ tệp trong Google Drive của họ.

Các ứng dụng đã cài đặt sẽ được phân phối đến từng thiết bị và người dùng 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 có mặt trên ứ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 được dùng cho ứng dụng máy chủ web. Điểm khác biệt chính là ứ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ý 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 có thể thích sử dụng tính năng Đăng nhập bằng Google hơn Android hoặc iOS. Thông tin đăng nhập bằng Google thư viện ứng dụng xử lý việc xác thực và uỷ quyền của người dùng và chúng có thể đơn giản hơn triển khai khác 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 thiết bị không hỗ trợ trình duyệt hệ thống hoặc có dữ liệu đầu vào hạn chế các chức năng 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à các thiết bị đầu vào hạn chế.

Thư viện và mẫu

Bạn nên dùng các thư viện và mẫu sau đây để giúp bạn 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 dành cho iOS
• OAuth cho ứng dụng: Windows Đoạn nhạc

Đ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 Google API đề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 sản phẩm gia đình và độ nổi tiếng. Nếu API bạn muốn bật không hiển thị trong danh sách, hãy sử dụng tính năng tìm kiếm để tìm biểu tượng hoặc nhấp vào Xem tất cả trong nhóm sản phẩm chứa mục đó.
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 cho phép

Mọi ứng dụng sử dụng OAuth 2.0 để truy cập API Google đều phải có thông tin xác thực uỷ quyền xác định ứng dụng tớ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 xác thực để truy cập 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 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à Google máy chủ uỷ quyền hỗ trợ. Chọn loại ứng dụng được đề xuất cho , đặt tên cho ứng dụng OAuth và đặt các trường khác trong biểu mẫu là 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 các tài nguyên mà ứng dụng cần trong khi cho phép người dùng kiểm soát lượng truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể là mối quan hệ nghịch đảo giữa số phạm vi được yêu cầu và khả năng lấy sự đồng ý của người dùng.

Trước khi bắt đầu triển khai việc 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.

Tài liệu về Phạm vi API của OAuth 2.0 chứa thông tin đầy đủ danh sách phạm vi mà bạn có thể dùng để truy cập 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 để lấy 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ó trước khi có thể thực thi yêu cầu API của Google cần người dùng cho phép.

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

Google hỗ trợ Khoá bằng chứng để trao đổi mã (PKCE) để tăng cường bảo mật cho luồng ứng dụng đã cài đặt. Một trình xác minh mã duy nhất được tạo cho mỗi yêu cầu uỷ quyền và giá trị đã biến đổi của nó (được 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 bằng cách sử dụng dữ liệu không được đặt trước ký tự [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", có độ dài tối thiểu là 43 ký tự và có độ dài tối đa là 128 ký tự.

Trình xác minh mã phải có đủ entropy để việc đoán giá trị là không thực tế.

Tạo thử thách lập trình

Có 2 phương thức tạo thử thách lập trình được hỗ trợ.

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

code_challenge = code_verifier

Bước 2: Gửi yêu cầu tới 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ủ cấp phép 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. Chỉ có thể truy cập vào điểm cuối qua SSL và từ chối 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 cho các máy chủ đã cài đặt ứng dụng:

URL uỷ quyền mẫu

Các thẻ bên dưới 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 này giống hệt nhau, ngoại trừ giá trị của tham số redirect_uri. Các URL cũng chứa các tham số response_type và client_id bắt buộc làm tham số state không bắt buộc. Mỗi URL chứa dấu ngắt dòng và dấu cách cho 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 ý

Ở bước này, người dùng sẽ quyết định xem có cấp cho ứng dụng của bạn quyền truy cập mà bạn yêu cầu hay không. Lúc này giai đoạn này, Google sẽ cho thấy một cửa sổ đồng ý cho thấy tên ứng dụng của bạn và Google API các dịch vụ mà nhà cung cấp đó đang yêu cầu cấp quyền truy cập bằng thông tin xác thực ủy quyền của người dùng và phần tóm tắt các phạm vi truy cập đã được cấp. Chiến lược phát hành đĩa đơn 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ì đang chờ phản hồi từ Máy chủ OAuth 2.0 của Google cho biết liệu có bất kỳ quyền truy cập nào được cấp hay không. Câu trả lời đó được giải thích bằng bước sau đây.

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 cho phép phụ thuộc vào lược đồ URI chuyển hướng mà nó sử dụng. Bất kể lược đồ là gì, 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 rằng 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ể trao đổi mã ủy quyền cho 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àm mới và truy cập mã thông báo

Để đổi mã uỷ quyền lấy mã truy cập, hãy gọi hàm đ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 có chứa quyền truy cập trong thời gian ngắn và mã làm mới.

Phản hồi có 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/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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ã này để thực hiện lệnh gọi đến Google thay mặt cho một tài khoản người dùng 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 thêm mã truy cập trong yêu cầu gửi đến API bằng cách bao gồm truy vấn access_token hoặc một giá trị Bearer của tiêu đề HTTP Authorization. Nếu có thể, nên ưu tiên sử dụng tiêu đề HTTP vì chuỗi truy vấn thường hiển thị trong nhật ký máy chủ. Trong hầu hết 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 API Tệp Drive).

Bạn có thể dùng thử tất cả API của Google và xem phạm vi của chúng ở Nền tảng OAuth 2.0.

Ví dụ về HTTP GET

Lệnh gọi đến drive.files điểm cuối (API Tệp Drive) bằng 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à lệnh gọi đến cùng một API cho người dùng đã được xác thực bằng access_token tham số chuỗi truy vấn:

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. Sau đây là một 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, một cách 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ã truy cập hết hạn theo định kỳ và trở thành thông tin đăng nhập 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ó) 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 POST HTTPS yêu cầu máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token) bao gồm các thông 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 mẫu trả lời:

{
  "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 trên khách hàng/người dùng và một tổ hợp khách hàng/người dùng khác cho mỗi người dùng trên tất cả khách hà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 miễn là 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ì mã này có thể gặp phải các 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 Account Settings (Cài đặt tài khoản). Xem Xoá phần truy cập trang web hoặc ứng dụng trong mục Trang web bên thứ ba & các ứng dụng 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 cách lập trình. Việc thu hồi có lập trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá ứng dụng hoặc tài nguyên API mà một ứ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 trước đó được cấp cho ứng dụng sẽ bị xoá.

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

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 nêu ở đây.