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 một ứng dụng mà 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 quyền của người dùng khi lưu trữ tệp trong Google Drive của họ.
Các ứng dụng đã cài đặt được phân phối cho các thiết bị riêng lẻ và giả định rằng các ứng dụng này 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 sử dụng ứ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 sử 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 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.
Phương án thay thế
Đối với ứng dụng dành cho thiết bị di động, bạn nên sử dụng tính năng Đăng nhập bằng Google cho Android hoặc iOS. Các thư viện ứng dụng Đăng nhập bằng Google xử lý việc xác thực và cấp phép cho người dùng. Những 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 như 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ó chức năng nhập 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 đây để giúp triển khai quy trình OAuth 2.0 như 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
Bất kỳ ứng dụng nào gọi API của Google đều phải bật các 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.
- 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 bạn muốn chọn không hiển thị 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 đó.
- Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Tạo thông tin cấp phép
Bất kỳ ứng dụng nào dùng OAuth 2.0 để truy cập API của Google đều phải có thông tin xác thực ủy 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 đó, các ứng dụng của bạn có thể dùng thông tin xác thực để truy cập vào những 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.
- 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 OAuth và đặt các trường khác trong biểu mẫu này cho phù hợp.
Lược đồ URI tùy chỉnh (Android, iOS, UWP)
Bạn nên sử dụng lược đồ URI tuỳ chỉnh cho các ứng dụng Android, ứng dụng iOS và ứng dụng Universal Windows Platform (UWP).
Android
- Chọn loại ứng dụng Android.
- Nhập tên cho ứng dụng OAuth. Tên này sẽ hiển thị trên Credentials page của dự án để giúp xác định khách hàng.
- Nhập tên gói cho ứng dụng Android của bạn. Giá trị này được xác định trong
thuộc tính
packagecủa phần tử<manifest>trong tệp kê khai ứng dụng của bạn. - Nhập tệp tham chiếu chứng chỉ ký SHA-1 của phân phối ứng dụng.
- Nếu ứng dụng của bạn sử dụng tính năng ký ứng dụng của Google Play, hãy sao chép vân tay SHA-1 từ trang ký ứng dụng của Play Console.
- Nếu bạn quản lý kho khoá và khoá ký của riêng mình, hãy sử dụng tiện ích keytool đi kèm với Java để in thông tin chứng chỉ ở định dạng mà con người có thể đọc được. Sao chép giá trị
SHA1trong phầnCertificate fingerprintscủa kết quả keytool. Hãy xem phần Xác thực ứng dụng trong tài liệu API của Google dành cho Android để biết thêm thông tin.
- Nhấp vào Tạo.
iOS
- Chọn loại ứng dụng iOS.
- Nhập tên cho ứng dụng OAuth. Tên này sẽ hiển thị trên Credentials page của dự án để giúp xác định khách hàng.
- Nhập mã nhận dạng gói cho ứng dụng. Mã gói là giá trị của khóa CFBundleIdentifier trong tệp tài nguyên danh sách thuộc tính thông tin của ứng dụng (info.plist). Giá trị này thường xuất hiện nhất trong ngăn Chung hoặc ngăn Ký và Khả năng của trình chỉnh sửa dự án Xcode. Mã nhận dạng gói cũng được hiển thị trong phần Thông tin chung của trang Thông tin ứng dụng đối với ứng dụng trên trang web Kết nối cửa hàng ứng dụng của Apple.
- (Không bắt buộc)
Nhập mã App Store của ứng dụng nếu ứng dụng đó đã được phát hành trên App Store của Apple. Mã cửa hàng là một chuỗi số có trong mọi URL của Apple App Store.
- Mở ứng dụng Apple App Store trên thiết bị iOS hoặc iPadOS của bạn.
- Tìm kiếm ứng dụng của bạn.
- Chọn nút Chia sẻ (biểu tượng hình vuông và mũi tên lên).
- Chọn Sao chép đường liên kết.
- Dán đường liên kết đó vào một trình chỉnh sửa văn bản. Mã App Store là phần cuối cùng của URL.
Ví dụ:
https://apps.apple.com/app/google/id284815942
- (Không bắt buộc)
Nhập ID nhóm của bạn. Xem Tìm Mã nhóm của bạn trong tài liệu về Tài khoản nhà phát triển của Apple để biết thêm thông tin.
- Nhấp vào Tạo.
UWP (băng tần siêu rộng)
- Chọn loại ứng dụng Universal Windows Platform (Nền tảng Windows thống nhất).
- Nhập tên cho ứng dụng OAuth. Tên này sẽ hiển thị trên Credentials page của dự án để giúp xác định khách hàng.
- Nhập Mã Microsoft Store gồm 12 ký tự trong ứng dụng. Bạn có thể tìm thấy giá trị này trong Trung tâm đối tác của Microsoft trên trang Danh tính ứng dụng trong phần Quản lý ứng dụng.
- Nhấp vào Tạo.
Đối với ứng dụng UWP, lược đồ URI tuỳ chỉnh không được dài hơn 39 ký tự.
Địa chỉ IP Loopback (macOS, Linux, máy tính Windows)
Để nhận mã uỷ quyền bằng URL này, ứng dụng của bạn phải theo dõi máy chủ web cục bộ. Điều này có thể xảy ra trên nhiều nền tảng (nhưng không phải tất cả). Tuy nhiên, nếu nền tảng của bạn hỗ trợ mã này, thì đây là cơ chế đề xuất để lấy mã uỷ quyền.
Khi ứng dụng của bạn nhận được phản hồi uỷ quyền, để có thể sử dụng một cách hiệu quả nhất, ứng dụng sẽ phản hồi bằng cách hiện một trang HTML hướng dẫn người dùng đóng trình duyệt và quay lại ứng dụng.
| Cách sử dụng đề xuất | Các ứng dụng dành cho macOS, Linux và Windows dành cho máy tính (nhưng không phải Universal Windows Platform) |
| Giá trị biểu mẫu | Đặt loại ứng dụng thành Ứng dụng dành cho máy tính. |
Sao chép/dán thủ công
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 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 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 đạt được sự đồng ý của người dùng.
Trước khi bắt đầu triển khai lệnh ủy 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 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 API của Google.
Lấy 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 thay mặt người dùng thực hiện API. Ứng dụng của bạn phải có được sự đồng ý đó trước khi có thể thực thi một yêu cầu API của Google có yêu cầu người dùng phải uỷ quyền.
Bước 1: Tạo trình xác minh mã và thử thách
Google hỗ trợ giao thức Khóa bằng chứng để Trao đổi mã (PKCE) để giúp luồng ứng dụng được cài đặt an toàn hơn. Trình xác minh mã duy nhất được tạo cho mỗi yêu cầu ủy quyền và giá trị chuyển đổi của nó, được gọi là "code_Challenge", được gửi tới 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 mã hoá ngẫu nhiên có hiệu suất cao sử dụng các ký tự không đặt trước [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ó đủ entropy để không thể đoán được giá trị.
Tạo thử thách mã
Hỗ trợ hai phương thức tạo thử thách mã.
| Phương thức tạo thử thách mã nguồn | |
|---|---|
| S256 (khuyên dùng) | Thách thức về mã là hàm băm SHA256 được mã hoá Base64URL (không có khoảng đệm) của trình xác minh mã.
|
| văn bản thuần tuý | Thử thách mã giống với giá trị của trình xác minh mã được tạo ở trên.
|
Bước 2: Gửi yêu cầu đến máy chủ OAuth 2.0 của Google
Để xin người dùng uỷ quyền, 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ý quá trình 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. Người dùng chỉ có thể truy cập đ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 có SSL).
Máy chủ uỷ quyền hỗ trợ các tham số chuỗi truy vấn sau đây đối với các ứng dụng được cài đặt:
| Các tham 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. |
||||||
redirect_uri |
Bắt buộc
Xác định cách máy chủ uỷ quyền của Google gửi phản hồi đến ứng dụng của bạn. Có một số tuỳ chọn chuyển hướng có sẵn cho các ứng dụng đã cài đặt và bạn sẽ thiết lập thông tin đăng nhập ủy quyền cho phương thức chuyển hướng cụ thể. Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0, mà bạn đã định cấu hình trong API Consolecủa Credentials pagecho ứng dụng. Nếu giá trị này không khớp với một URI được ủy quyền, bạn sẽ gặp lỗi Bảng dưới đây cho thấy giá trị tham số
|
||||||
response_type |
Bắt buộc
Xác định xem điểm cuối Google OAuth 2.0 có trả về mã uỷ quyền hay không. Đặt giá trị tham số thành |
||||||
scope |
Bắt buộc
Danh sách các phạm vi phân tách bằng dấu cách xác định các 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ị. 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 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ột mối tương quan nghịch 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. |
||||||
code_challenge |
Nên
Chỉ định một |
||||||
code_challenge_method |
Nên
Chỉ định phương thức dùng để mã hóa một |
||||||
state |
Nên
Chỉ định mọi giá trị chuỗi mà ứng dụng sử dụng để duy trì trạng thái giữa yêu cầu uỷ quyền và phản hồi của máy chủ uỷ quyền.
Máy chủ trả về giá trị chính xác mà bạn gửi dưới dạng một cặp Bạn có thể sử dụng tham số này cho một số mục đích, chẳng hạn như hướng người dùng đến đúng tài nguyên trong ứng dụng, gửi số chỉ dùng một lần và giảm thiểu yêu cầu giả mạo trên nhiều trang web. Vì |
||||||
login_hint |
Optional (Không bắt buộc)
Nếu biết người dùng nào đang cố gắng xác thực, thì ứng dụng của bạn có thể sử dụng thông số này để cung cấp gợi ý cho Máy chủ xác thực của Google. Máy chủ sử dụng gợi ý để đơn giản hoá quy trình đăng nhập bằng cách điền sẵn trường email vào biểu mẫu đăng nhập, hoặc chọn phiên đăng nhập nhiều tài khoản thích hợp. Đặt giá trị tham số thành địa chỉ email hoặc giá trị nhận dạng |
||||||
URL uỷ quyền mẫu
Thẻ dưới đây trình bày các URL uỷ quyền mẫu cho nhiều lựa chọn URI chuyển hướng.
Các URL giống nhau ngoại trừ giá trị của tham số redirect_uri. Những URL này cũng chứa các tham số response_type và client_id bắt buộc cũng như các 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 để dễ đọc.
Lược đồ URI tùy chỉnh
https://accounts.google.com/o/oauth2/v2/auth? scope=& 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
Địa chỉ IP Loopback
https://accounts.google.com/o/oauth2/v2/auth? scope=& 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 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 thị một cửa sổ yêu cầu sự đồng ý để cho biết tên của ứng dụng và các dịch vụ API của Google mà Google đang yêu cầu cấp quyền truy cập bằng thông tin đăng nhập của người dùng cùng với thông tin tóm tắt về phạm vi truy cập cần 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ì hệ thống sẽ chờ phản hồi từ máy chủ OAuth 2.0 của Google để cho bạn biết bạn có được cấp quyền truy cập nào hay không. Phản hồi đó sẽ được giải thích trong bước sau.
Lỗi
Các yêu cầu gửi đến điểm cuối uỷ quyền OAuth 2.0 của Google có thể hiển thị thông báo lỗi mà người dùng nhìn thấy thay vì các quy trình xác thực và uỷ quyền dự kiến. Dưới đây là danh sách mã lỗi và các giải pháp đề xuất.
admin_policy_enforced
Tài khoản Google không thể uỷ quyền cho một hoặc nhiều phạm vi yêu cầu theo chính sách của quản trị viên Google Workspace. Xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát những ứng dụng nội bộ và ứng dụng bên trong có quyền truy cập vào dữ liệu trên 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 mọi phạm vi hoặc phạm vi nhạy cảm và bị hạn chế cho đến khi bạn được cấp quyền truy cập rõ ràng vào mã ứng dụng khách OAuth.
disallowed_useragent
Điểm cuối ủy quyền được hiển thị bên trong tác nhân người dùng được nhúng theo Chính sách OAuth 2.0 của Google.
Android
Nhà phát triển Android có thể gặp thông báo lỗi này khi mở các yêu cầu uỷ quyền trong
android.webkit.WebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện Android như Đăng nhập bằng Google cho Android hoặc AppAuth cho Android của WHOIS Foundation.
Nhà phát triển web có thể gặp lỗi này khi một ứng dụng Android mở một đường liên kết web chung trong tác nhân người dùng được nhúng và người dùng sẽ chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển nên cho phép mở các đường liên kết chung trong trình xử lý đường liên kết mặc định của hệ điều hành, trong đó có cả trình xử lý Đường liên kết trong ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Thư viện Thẻ tuỳ chỉnh Android cũng là một tuỳ chọn được hỗ trợ.
iOS
Nhà phát triển iOS và macOS có thể gặp lỗi này khi mở yêu cầu uỷ quyền trong
WKWebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện iOS như Đăng nhập bằng Google cho iOS hoặc AppAuth cho iOS của Orkut Foundation.
Nhà phát triển web có thể gặp lỗi này khi ứng dụng iOS hoặc macOS mở một đường liên kết web chung trong tác nhân người dùng được nhúng và người dùng sẽ chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển nên cho phép các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, trong đó có cả trình xử lý Đường liên kết phổ quát hoặc ứng dụng trình duyệt mặc định. Thư viện SFSafariViewController cũng là một tuỳ chọn được hỗ trợ.
org_internal
Mã ứng dụng khách 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 Google Cloud cụ thể. Để biết thêm thông tin về tuỳ chọn cấu hình này, hãy xem phần Loại người dùng trong bài viết trợ giúp về Thiết lập màn hình xin phép bằng OAuth.
invalid_grant
Nếu bạn đang sử dụng
trình xác minh mã và
thử thách, thì thông số code_callenge không hợp lệ hoặc bị thiếu. Đảm bảo rằng bạn đã đặt chính xác tham số code_challenge.
Khi làm mới mã truy cập, mã thông báo này có thể đã hết hạn hoặc đã hết hiệu lực. Xác thực lại người dùng và yêu cầu người dùng đồng ý để nhận mã thông báo mới. Nếu bạn vẫn tiếp tục gặp lỗi này, hãy đảm bảo rằng bạn đã định cấu hình đúng cách cho ứng dụng và bạn đang sử dụng đúng mã thông số cũng như thông số trong yêu cầu. Nếu không, tài khoản người dùng có thể đã bị xoá hoặc vô hiệu hoá.
redirect_uri_mismatch
redirect_uri được chuyển trong yêu cầu uỷ quyền không khớp với URI chuyển hướng được uỷ quyền cho mã ứng dụng khách OAuth. Hãy xem xét các URI chuyển hướng được phép trong Google API Console Credentials page.
redirect_uri đã truyền có thể không hợp lệ đối với loại ứng dụng.
Tham số redirect_uri có thể tham chiếu đến luồng ngoài băng tần (OOB) của OAuth đã không còn được dùng nữa và không còn được hỗ trợ. Hãy tham khảo
hướng dẫn di chuyển để cập nhật
công cụ tích hợp của bạn.
Bước 4: Xử lý phản hồi của máy chủ OAuth 2.0
Cách thức mà ứ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 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, bạn có thể trao đổi mã uỷ quyền cho một mã truy cập và một 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
Để trao đổi mã uỷ quyền cho mã truy cập, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt các thông số sau:
| Các trường | |
|---|---|
client_id |
Mã ứng dụng khách thu được từ API Console Credentials page. |
client_secret |
Mật khẩu ứng dụng khách lấy từ API Console Credentials page. |
code |
Mã uỷ quyền được trả về từ yêu cầu ban đầu. |
code_verifier |
Trình xác minh mã mà bạn đã tạo ở Bước 1. |
grant_type |
Như được 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 authorization_code. |
redirect_uri |
Một trong các URI chuyển hướng liệt kê cho dự án của bạn trong API Console
Credentials page của client_id. |
Đ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ột mã làm mới.
Phản hồi 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 để cho phép một yêu cầu API của Google. |
expires_in |
Thời gian tồn tại của mã truy cập tính bằng giây. |
id_token |
Lưu ý: Thuộc tính này chỉ được trả về nếu yêu cầu của bạn có phạm vi nhận dạng, chẳng hạn như openid, profile hoặc email. Giá trị là một Mã thông báo web JSON (JWT) chứa thông tin nhận dạng có chữ ký số của người dùng. |
refresh_token |
Một 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ã làm mới luôn được trả về cho các ứng dụng đã cài đặt. |
scope |
Phạm vi truy cập mà 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, phân biệt chữ hoa chữ thường. |
token_type |
Loại mã thông báo được trả về. Hiện tại, giá trị của trường này luôn được đặt thành Bearer. |
Đ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ã thông báo này để gọi API Google thay mặt cho một tài khoản người dùng nhất định nếu API đó đã cấp(các) phạm vi quyền truy cập mà ứng dụng cần. Để 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 thêm giá trị tham số truy vấn access_token hoặc Authorization tiêu đề HTTP Bearer. Khi có thể, bạn nên chọn tiêu đề HTTP vì các chuỗi cụm từ tìm kiếm có xu hướng xuất hiện trong nhật ký máy chủ. Trong hầu hết trường hợp, bạn có thể sử dụng một 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 Drive Files).
Bạn có thể dùng thử tất 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
drive.files (API Drive Files) 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 chính mình:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Sau đâ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/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ụ 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/drive/v2/files
Hoặc, tùy 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 và định kỳ trở thành thông tin xác thực không hợp lệ cho 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 (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 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 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:
| Các trường | |
|---|---|
client_id |
Mã ứng dụng khách thu được từ API Console. |
client_secret |
Mật khẩu ứng dụng khách lấy từ API Console.
(client_secret không áp dụng cho những yêu cầu của khách hàng đã đăng ký làm ứng dụng Android, iOS hoặc Chrome.)
|
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ừ hoạt động trao đổi mã uỷ 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, 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 khách hàng/người dùng và một giới hạn cho mỗi người dùng trên tất cả ứng dụng. Bạn nên lưu mã làm mới trong bộ nhớ dài hạn rồi tiếp tục sử dụng 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ũ 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 tài liệu hỗ trợ Xoá trang web hoặc ứng dụng của các trang web và ứng dụng 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 trong quy trình xóa có thể bao gồm một yêu cầu API để đảm bảo các quyền đã cấp cho ứng dụng trước đó đã bị xóa.
Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng sẽ yêu cầu https://oauth2.googleapis.com/revoke và đưa mã thông báo đó và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}
Mã nà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, thì 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ột mã lỗi.
Tài liệu đọc thêm
Phương pháp hay nhất hiện tại của IETF là OAuth 2.0 cho ứng dụng gốc giúp thiết lập nhiều phương pháp hay nhất trong tài liệu này.