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:
- 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 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 đó.
- 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 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 đó.
- Go to the Credentials page.
- Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
- 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.
Android
- Chọn loại ứng dụng Android.
- Nhập tên cho ứng dụng OAuth. Tên này được hiển thị trên Credentials page để 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. - Nhập dấu vân tay chứng chỉ ký SHA-1 của quá trình 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 SHA-1 vân tay số 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 phần mềm 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 Đầu ra của keytool. Xem Xác thực ứng dụng của bạn trong Để biết thêm thông tin, hãy tham khảo tài liệu về các API của Google dành cho Android.
- (Không bắt buộc) Xác minh quyền sở hữu thiết bị Android của bạn .
- 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 được hiển thị trên Credentials page để xác định khách hàng.
- Nhập mã nhận dạng gói cho ứng dụng của bạn. Mã gói là giá trị của CFBundleIdentifier vào 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ị thường được hiển thị nhất trong ngăn Chung hoặc Ký & Ngăn chức năng của Trình chỉnh sửa dự án Xcode. Mã gói cũng được hiển thị trong phần Thông tin chung của trang Thông tin ứng dụng cho ứng dụng trên Trang web App Store Connect 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 xuất bản trong 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 App Store của Apple trên thiết bị iOS hoặc iPadOS.
- Tì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 Mã 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
- Chọn loại ứng dụng Universal Windows Platform.
- Nhập tên cho ứng dụng OAuth. Tên này được hiển thị trên Credentials page để xác định khách hàng.
- Nhập mã cửa hàng gồm 12 ký tự của ứng dụng trên Microsoft. Bạn có thể tìm thấy giá trị này trong Trung tâm đối tác của Microsoft trên Danh tính ứng dụng trong phần Quản lý ứng dụng.
- Nhấp vào Tạo.
Đối với các ứng dụng UWP, lược đồ URI tuỳ chỉnh không được dài hơn 39 ký tự.
Lược đồ URI tuỳ chỉnh (Android, iOS, UWP)
Lược đồ URI tuỳ chỉnh là một dạng đường liên kết sâu sử dụng lược đồ được xác định tuỳ chỉnh để mở ứng dụng của bạn.
Phương án thay thế cho việc sử dụng giao thức URI tuỳ chỉnh trên AndroidSử dụng SDK Android Đăng nhập bằng Google giúp cung cấp phản hồi OAuth 2.0 trực tiếp cho ứng dụng của bạn, nhờ đó không cần URI chuyển hướng.
Cách di chuyển sang SDK Đăng nhập bằng Google dành cho Android
Nếu đang dùng một lược đồ tuỳ chỉnh để tích hợp OAuth trên Android, bạn cần hoàn tất những hành động dưới đây để chuyển hoàn toàn sang sử dụng tính năng Đăng nhập bằng Google được đề xuất cho SDK Android:
- Hãy cập nhật mã của bạn để sử dụng SDK đăng nhập bằng Google.
- Tắt tính năng hỗ trợ cho lược đồ tuỳ chỉnh trong Google API Console.
Hãy làm theo các bước dưới đây để di chuyển sang SDK Android đăng nhập bằng Google:
-
Cập nhật mã của bạn để sử dụng SDK Android đăng nhập bằng Google:
-
Kiểm tra mã của bạn để xác định vị trí hiện tại của bạn
gửi yêu cầu đến máy chủ OAuth 2.0 của Google; nếu dùng lược đồ tuỳ chỉnh, yêu cầu của bạn sẽ có dạng như sau:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirectlà URI chuyển hướng lược đồ tuỳ chỉnh trong ví dụ bên trên. Xem Định nghĩa tham sốredirect_uriđể biết thêm thông tin chi tiết về định dạng của giá trị giao thức URI tuỳ chỉnh. -
Hãy lưu ý các tham số yêu cầu
scopevàclient_idbạn sẽ cần định cấu hình SDK đăng nhập bằng Google. -
Làm theo
Bắt đầu tích hợp tính năng Đăng nhập bằng Google vào ứng dụng Android
để thiết lập SDK. Bạn có thể bỏ qua
Nhận mã ứng dụng khách OAuth 2.0 của máy chủ phụ trợ theo cách bạn sử dụng lại
client_idmà bạn truy xuất từ bước trước. -
Làm theo
Bật quyền truy cập vào API phía máy chủ
hướng dẫn. Quá trình này bao gồm các bước sau:
-
Sử dụng phương thức
getServerAuthCodeđể truy xuất mã xác thực cho các phạm vi mà bạn đang yêu cầu cấp quyền. - Gửi mã xác thực đến máy chủ phụ trợ của ứng dụng để đổi mã đó lấy quyền truy cập & làm mới mã thông báo.
- Sử dụng mã truy cập đã truy xuất để thay mặt người dùng thực hiện lệnh gọi đến các API của Google.
-
Sử dụng phương thức
-
Kiểm tra mã của bạn để xác định vị trí hiện tại của bạn
gửi yêu cầu đến máy chủ OAuth 2.0 của Google; nếu dùng lược đồ tuỳ chỉnh, yêu cầu của bạn sẽ có dạng như sau:
-
Tắt tính năng hỗ trợ cho lược đồ tuỳ chỉnh trong Google API Console:
- Chuyển đến Thông tin đăng nhập OAuth 2.0 và chọn ứng dụng Android của bạn.
- Chuyển đến phần Cài đặt nâng cao, bỏ chọn Bật Lược đồ URI tuỳ chỉnh rồi nhấp vào Save (Lưu) để tắt tính năng hỗ trợ giao thức URI tuỳ chỉnh.
Bật lược đồ URI tuỳ chỉnh
Nếu phương án thay thế được đề xuất không phù hợp với bạn, thì bạn có thể bật giao thức URI tuỳ chỉnh cho Ứng dụng Android bằng cách làm theo hướng dẫn bên dưới:- Chuyển đến Danh sách thông tin đăng nhập OAuth 2.0 và hãy chọn ứng dụng khách Android của bạn.
- Chuyển đến phần Cài đặt nâng cao, chọn Hộp đánh dấu Bật Lược đồ URI tuỳ chỉnh rồi nhấp vào Lưu để bật hỗ trợ giao thức URI tuỳ chỉnh.
Sử dụng API Nhận dạng Chrome giúp cung cấp phản hồi OAuth 2.0 trực tiếp cho ứng dụng của bạn, nhờ đó không cần URI chuyển hướng.
Xác minh quyền sở hữu ứng dụng (Android, Chrome)
Bạn có thể xác minh quyền sở hữu ứng dụng của mình để giảm nguy cơ ứng dụng bị mạo danh.
Android
Để hoàn tất quy trình xác minh, bạn có thể sử dụng Tài khoản nhà phát triển trên Google Play và ứng dụng của bạn được đăng ký trên Google Play Console. Nội dung sau đây phải đáp ứng các yêu cầu để xác minh thành công:
- Bạn phải đăng ký một ứng dụng trong Google Play Console có cùng tên gói và dấu vân tay chứng chỉ ký SHA-1 dưới dạng ứng dụng OAuth của Android hoàn tất quy trình xác minh.
- Bạn phải có quyền Quản trị đối với ứng dụng trong Google Play Console. Tìm hiểu thêm về cách quản lý quyền truy cập trong Google Play Console.
Trong phần Xác minh quyền sở hữu ứng dụng của ứng dụng Android, hãy nhấp vào Nút Xác minh quyền sở hữu để hoàn tất quy trình xác minh.
Nếu xác minh thành công, một thông báo sẽ xuất hiện để xác nhận rằng bạn đã thành công của quy trình xác minh. Nếu không, lời nhắc báo lỗi sẽ xuất hiện.
Để khắc phục trường hợp xác minh không thành công, vui lòng thử các cách sau:
- Đảm bảo ứng dụng bạn đang xác minh là một ứng dụng đã đăng ký trong Google Play Console.
- Đảm bảo bạn có quyền Quản trị đối với ứng dụng trong Google Play Console.
Chrome
Để hoàn tất quy trình xác minh, bạn cần sử dụng tài khoản Nhà phát triển Cửa hàng Chrome trực tuyến của mình. Để xác minh thành công, bạn phải đáp ứng các yêu cầu sau đây:
- Bạn phải có một mặt hàng đã đăng ký trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến có cùng mã mục với ứng dụng OAuth của Tiện ích Chrome mà bạn đang hoàn tất xác minh.
- Bạn phải là nhà xuất bản cho mặt hàng trong Cửa hàng Chrome trực tuyến. Tìm hiểu thêm về cách quản lý quyền truy cập trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến.
Trong phần Xác minh quyền sở hữu ứng dụng của ứng dụng Tiện ích Chrome, hãy nhấp vào nút Xác minh quyền sở hữu để hoàn tất quy trình xác minh.
Lưu ý: Vui lòng đợi vài phút rồi mới hoàn tất quy trình xác minh. cấp quyền truy cập vào tài khoản của bạn.
Nếu xác minh thành công, một thông báo sẽ xuất hiện để xác nhận rằng bạn đã thành công của quy trình xác minh. Nếu không, lời nhắc báo lỗi sẽ xuất hiện.
Để khắc phục trường hợp xác minh không thành công, vui lòng thử các cách sau:
- Đảm bảo có một mặt hàng đã đăng ký trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến có cùng mã mặt hàng với ứng dụng OAuth của Tiện ích Chrome mà bạn đang hoàn tất quy trình xác minh.
- Đảm bảo bạn là nhà xuất bản của ứng dụng, tức là bạn phải là nhà xuất bản cá nhân của ứng dụng hoặc thành viên của nhà xuất bản nhóm của ứng dụng. Tìm hiểu thêm về cách quản lý quyền truy cập trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến.
- Nếu bạn vừa cập nhật danh sách nhà xuất bản nhóm của mình, hãy xác minh rằng tư cách thành viên nhà xuất bản nhóm được đồng bộ hoá trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến. Tìm hiểu thêm về cách đồng bộ hoá danh sách thành viên nhà xuất bản.
Địa chỉ IP Loopback (macOS, Linux, máy tính chạy Windows)
Để nhận được mã ủy quyền bằng URL này, ứng dụng của bạn phải nghe trên máy chủ web cục bộ. Điều đó có thể xảy ra trên nhiều, nhưng không phải tất cả, nền tảng. Tuy nhiên, nếu nền tảng của bạn hỗ trợ nó, đây là cơ chế được khuyến nghị để lấy mã uỷ quyền.
Khi ứng dụng của bạn nhận được phản hồi cho phép, để có khả năng hữu dụng nhất, ứng dụng của bạn nên phản hồi bằng hiển thị trang HTML hướng dẫn người dùng đóng trình duyệt và quay lại ứng dụng của bạn.
| Cách sử dụng đề xuất | Ứng dụng 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 Desktop app (Ứ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 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ợ.
| Phương pháp tạo thử thách mã | |
|---|---|
| S256 (nên dùng) | Thử thách mã là hàm băm SHA256 được mã hoá Base64URL (không có khoảng đệm) của mã
trình xác minh.
|
| đơn thuần | Thử thách mã có cùng giá trị với trình xác minh mã đã tạo ở trên.
|
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:
| 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. |
||||||
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. Đồng thời, bạn sẽ thiết lập uỷ quyền thông tin xác thực bằng một phương thức chuyển hướng cụ thể của chúng tôi. 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 phép cho OAuth 2.0
mà bạn đã định cấu hình trong
API Console
Credentials page. Nếu giá trị này không khớp với
URI được uỷ quyền, bạn sẽ gặp lỗi Bảng bên dưới trình bà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
Đáp phân tách bằng dấu cách danh sách phạm vi xác định tài nguyên mà ứng dụng của bạn có thể truy cập trên thay mặt cho người dùng. Các giá trị này cho biết màn hình xin phép mà Google hiển thị cho người dùng. 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 vẫn cho phép người dùng kiểm soát lượng quyền truy cập mà họ cấp cho . Do đó, có mối quan hệ nghịch đảo giữa số phạm vi được yêu cầu và khả năng có được sự đồng ý của người dùng. |
||||||
code_challenge |
Recommended (Nên dùng)
Chỉ định một |
||||||
code_challenge_method |
Recommended (Nên dùng)
Chỉ định phương thức dùng để mã hoá |
||||||
state |
Recommended (Nên dùng)
Chỉ định bất kỳ giá trị chuỗi nào mà ứng dụng của bạn 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 thông số này cho một số mục đích, chẳng hạn như hướng người dùng đến
tài nguyên chính xác trong ứng dụng, gửi số chỉ dùng một lần và giảm thiểu yêu cầu trên nhiều trang web
giả mạo. Vì có thể đoán được |
||||||
login_hint |
Không bắt buộc
Nếu biết người dùng nào đang cố gắng xác thực, ứ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 trong biểu mẫu đăng nhập hoặc bằng cách chọn phiên đăng nhập nhiều tài khoản thích hợp. Đặt giá trị thông số thành một địa chỉ email hoặc giá trị nhận 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.
Lược đồ URI tuỳ chỉnh
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
Địa chỉ IP Loopback
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.
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. Các mã lỗi phổ biến và nội dung đề xuất được liệt kê dưới đây.
admin_policy_enforced
Tài khoản Google không thể cho phép một hoặc nhiều phạm vi đã yêu cầu do các chính sách của quản trị viên Google Workspace của họ. Xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát bên thứ ba và các ứng dụng nội bộ truy cập vào dữ liệu trong 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 tất cả các phạm vi hoặc các dữ liệu nhạy cảm và phạm vi bị hạn chế cho đến khi bạn cấp quyền truy cập rõ ràng cho mã ứng dụng khách OAuth.
disallowed_useragent
Điểm cuối uỷ quyền được hiển thị trong một tác nhân người dùng được nhúng bởi Chính sách của OAuth 2.0.
Android
Nhà phát triển Android có thể gặp phải 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ư
Tính năng Đăng nhập bằng Google dành cho Android hoặc tài khoản OpenID Foundation
AppAuth cho Android.
Các nhà phát triển web có thể gặp phải lỗi này khi ứng dụng Android mở một đường liên kết trang web chung trong một tác nhân người dùng được nhúng và người dùng 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ý liên kết mặc định của hệ điều hành của Google, bao gồm cả Đường liên kết trong ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Chiến lược phát hành đĩa đơn Thẻ tuỳ chỉnh trong Android thư viện 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ở các 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ư
Tính năng Đăng nhập bằng Google cho iOS hoặc tài khoản OpenID Foundation
AppAuth cho iOS.
Các nhà phát triển web có thể gặp phải lỗi này khi một ứng dụng iOS hoặc macOS mở một đường liên kết trang web chung trong
tác nhân người dùng được nhúng và người dùng 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ý liên kết mặc định của
hệ điều hành của Google, bao gồm cả
Đường liên kết phổ quát
hoặc ứng dụng trình duyệt mặc định. Chiến lược phát hành đĩa đơn
SFSafariViewController
thư viện cũng là một tuỳ chọn được hỗ trợ.
org_internal
Mã ứng dụng OAuth trong yêu cầu là một phần của một dự án giới hạn quyền truy cập vào Tài khoản Google trong một cụ thể Tổ chức Google Cloud. Để biết thêm thông tin về tuỳ chọn cấu hình này, hãy xem 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ì tham số code_callenge không hợp lệ hoặc bị thiếu. Đảm bảo rằng
Tham số code_challenge đã được đặt đúng cách.
Khi làm mới mã truy cập, mã đó có thể đã hết hạn hoặc đã không còn hiệu lực. Xác thực người dùng một lần nữa và yêu cầu người dùng đồng ý để lấy mã thông báo mới. Nếu bạn đang tiếp tục để xem lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã được định cấu hình chính xác và bạn bằng cách sử dụng đúng mã thông báo và tham số trong yêu cầu của bạn. Nếu không, tài khoản người dùng có thể phải đã bị xóa hoặc vô hiệu hóa.
redirect_uri_mismatch
redirect_uri đã chuyển trong yêu cầu uỷ quyền không khớp với với
chuyển hướng URI cho mã ứng dụng khách OAuth. Xem lại các URI chuyển hướng được uỷ quyền 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 này.
Tham số redirect_uri có thể tham chiếu đến luồng OAuth ngoài băng tần (OOB) đã
không được dùng nữa và không còn được hỗ trợ nữa. Tham khảo
hướng dẫn di chuyển để cập nhật
tích hợp.
invalid_request
Đã xảy ra lỗi với yêu cầu của bạn. Điều này có thể là do một số lý do:
- Yêu cầu không được định dạng đúng
- Yêu cầu thiếu thông số bắt buộc
- Yêu cầu này sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. Xác minh OAuth của bạn sử dụng phương pháp tích hợp được đề xuất
- Giao thức tuỳ chỉnh đang được sử dụng cho URI chuyển hướng : Nếu bạn thấy thông báo lỗi Lược đồ URI tuỳ chỉnh không được hỗ trợ trên các ứng dụng Chrome hoặc Lược đồ URI tuỳ chỉnh chưa được bật cho ứng dụng Android của bạn, điều đó có nghĩa là bạn đang dùng URI tuỳ chỉnh không được hỗ trợ trên ứng dụng Chrome và bị tắt theo mặc định trên Android. Tìm hiểu thêm về giao thức URI tuỳ chỉnh lựa chọn thay thế
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:
| Trường | |
|---|---|
client_id |
Mã ứng dụng khách lấy được từ API Console Credentials page. |
client_secret |
Mật khẩu ứng dụng khách lấy được 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 định nghĩa trong OAuth 2.0
chỉ số, thì giá trị của trường này phải được đặt thành authorization_code. |
redirect_uri |
Một trong những URI chuyển hướng được liệt kê cho dự án của bạn trong
API Console
Credentials page cho các giá trị cụ thể
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 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:
| Trường | |
|---|---|
access_token |
Mã thông báo mà ứng dụng của bạn gửi để cho phép yêu cầu API của Google. |
expires_in |
Thời gian hoạt động còn lại của mã truy cập tính bằng giây. |
id_token |
Lưu ý: Tài sản này chỉ được trả về nếu yêu cầu của bạn có phạm vi danh tính,
chẳng hạn như openid, profile hoặc email. Giá trị là
Mã thông báo web JSON (JWT) chứa thông tin nhận dạng đã ký số về
người dùng. |
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 có hiệu lực cho đến khi người dùng thu hồi quyền truy cập. Xin 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
chuỗi 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ề. 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 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:
| 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 được từ API Console.
(client_secret không áp dụng cho các yêu cầu từ những khách hàng đã đăng ký bằng
ứng dụng Android, iOS hoặc Chrome.)
|
grant_type |
Như
được xác định trong
Quy cách 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ừ quá trình 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ề 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 mỗi 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à ứ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.