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 để cấp 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 một ứng dụng, đồng thời 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 để xin phép người dùng lưu trữ tệp trong Google Drive của họ.
Ứng dụng đã cài đặt sẽ được phân phối đến các thiết bị riêng lẻ và giả định rằng những ứng dụng này không thể giữ bí mật. Họ có thể truy cập API Google trong khi người dùng sử dụng ứng dụng hoặc khi ứng dụng đang chạy trong nền.
Luồng ủy quyền này tương tự như quy trình 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 URI chuyển hướng cục bộ để xử lý phản hồi từ máy chủ ủy 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 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 sẽ xử lý việc xác thực và ủy quyền người dùng. Việc triển khai có thể đơn giản hơn so với giao thức cấp thấp hơn như mô tả ở đây.
Đối với những ứng dụng chạy trên các thiết bị không hỗ trợ trình duyệt hệ thống hoặc có chức năng nhập dữ liệu 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à amp; thiết bị hoặc đăng nhập trên TV và các thiết bị đầu vào giới hạn.
Thư viện và mẫu
Bạn nên sử dụng các thư viện và mẫu sau để 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 cho iOS
- OAuth dành cho ứng dụng: Windows mẫu
Đ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 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 Danh sách tất 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 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 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 đăng nhập ủy quyền
Bất kỳ ứng dụng nào sử dụng OAuth 2.0 để truy cập API của Google đều phải có thông tin đăng nhập ủy quyền để nhận dạng ứng dụng đó bằng máy chủ OAuth 2.0 của Google. Sau đây là các bước 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 xác thực để truy cập các 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à máy chủ ủy quyền của Google hỗ trợ. Chọn loại ứng dụng nên dùng 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 cho phù hợp.
Lược đồ URI tùy chỉnh (Android, iOS, UWP)
Bạn nên sử dụng lược đồ URI tùy 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 để nhận dạng khách hàng.
- Nhập tên gói của ứng dụng Android. 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 vân tay số cho chứng chỉ ký SHA-1 của bản 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 khóa và khóa ký của riêng mình, hãy 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. Xem bài viết Xác thực ứng dụng của bạn trong tài liệu về 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 để nhận dạng khách hàng.
- Nhập giá trị nhận dạng gói cho ứng dụng của bạn. 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ị thường xuất hiện trong ngăn Tóm tắt hoặc ngăn Ký hiệu & khả năng của trình chỉnh sửa dự án Xcode. Mã gói cũng hiển thị trong phần Thông tin chung của trang Thông tin ứng dụng của ứ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 trong App Store của Apple. Mã cửa hàng là một chuỗi số đi kèm 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.
- 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 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. Hãy xem bài viết 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.
- 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 để nhận dạng khách hàng.
- Nhập mã Microsoft Store gồm 12 ký tự của ứ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 tùy chỉnh không được dài hơn 39 ký tự.
Địa chỉ IP Loop (MacOS, Linux, Windows trên máy tính)
Để nhận được mã uỷ quyền bằng URL này, ứng dụng của bạn phải đang theo dõi trên 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 mà bạn hỗ trợ, thì đây là cơ chế đề xuất để nhận mã ủy quyền.
Khi nhận được phản hồi ủy quyền, ứng dụng của bạn sẽ phản hồi bằng cách hiển thị HTML 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 | Ứng dụng dành cho máy tính để bàn macOS, Linux và Windows (chứ không phải Universal Windows Platform) |
| Giá trị trên 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 đã 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 ủ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 sẽ cần 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ể 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 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 để nhận được sự đồng ý của người dùng để thực hiện yêu cầu API thay mặt 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 yêu cầu sự cho phép của người dùng.
Bước 1: Tạo trình xác minh mã và xác thực
Google hỗ trợ giao thức Khóa bằng chứng cho Quy trình trao đổi mã (PKCE) để giúp quy trình ứng dụng được cài đặt trở nên 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 mã này được gọi là "code_challenge" và được gửi đến máy chủ ủy quyền để lấy mã ủy quyền.
Tạo trình xác minh mã
code_verifier là một chuỗi mã hóa ngẫu nhiên có tốc độ cao sử dụng các ký tự chưa đặt trước [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" với độ dài tối thiểu là 43 ký tự
và tối đa là 2 ký tự 1.
Trình xác minh mã phải có đủ entropy để không đoán được giá trị.
Tạo thử thách mã
Có hai phương pháp tạo thử thách bằng mã được hỗ trợ.
| Phương pháp tạo mã xác thực | |
|---|---|
| S256 (nên dùng) | Thách thức mã là hàm băm được mã hóa SHA256 (không có khoảng đệm) của trình xác minh mã
Base64URL.
|
| plain | Thử thách mã giống với giá trị của trình xác minh mã đã tạo ở trên.
|
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 một yêu cầu đến máy chủ ủy quyền của Google ở
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. Bạn 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 phải SSL).
Máy chủ ủy quyền hỗ trợ các tham số chuỗi truy vấn sau cho các ứng dụng đã cài đặt:
| Các thông số | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Bắt buộc
ID ứ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 Credentials page API Console. |
||||||
redirect_uri |
Bắt buộc
Xác định cách máy chủ ủy quyền của Google gửi phản hồi tới ứng dụng của bạn. Có một số tùy chọn chuyển hướng có sẵn cho ứng dụng đã cài đặt và bạn sẽ thiết lập thông tin đăng nhập ủy quyền có phương pháp 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 ủy quyền của ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong API Consolecủa Credentials page. Nếu giá trị này không khớp với URI được phép, thì bạn sẽ gặp lỗi Bảng bên dưới trình bày giá trị thông số
|
||||||
response_type |
Bắt buộc
Xác định điểm cuối của Google OAuth 2.0 có trả về mã ủy quyền hay không. Đặt giá trị thông số thành |
||||||
scope |
Bắt buộc
Danh sách các phạm vi được 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ể truy cập thay mặt cho người dùng. Những giá trị này cho biết màn hình đồng ý 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 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ó mối quan hệ nghịch đảo giữa số lượng phạm vi đã yêu cầu và khả năng có được sự đồng ý của người dùng. |
||||||
code_challenge |
Nên
Chỉ định |
||||||
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 dùng để duy trì trạng thái giữa yêu cầu ủy quyền của bạn và phản hồi của máy chủ ủy 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 nhiều mục đích, chẳng hạn như chuyển hướng người dùng đến
tài nguyên chính xác trong ứng dụng của bạn, gửi nonces và giảm thiểu hành vi giả mạo yêu cầu trên nhiều trang web. Vì |
||||||
login_hint |
Tùy chọn
Nếu biết ứng 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 hóa 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 địa chỉ email hoặc giá trị nhận dạng |
||||||
URL ủy quyền mẫu
Các thẻ bên dưới thể hiện URL ủy quyền mẫu cho các tùy chọn URI chuyển hướng khác nhau.
Các URL giống nhau ngoại trừ giá trị của thông 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 các 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 ý
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 thị một cửa sổ yêu cầu đồng ý, trong đó hiển thị tên ứng dụng 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 ủy quyền của người dùng và bản tóm tắt các phạm vi quyền 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 theo yêu cầu của bạn hoặc từ chối yêu cầu.
Ứng dụng của bạn không cần làm gì trong giai đoạn này vì đang chờ phản hồi của máy chủ OAuth 2.0 của Google cho biết liệu có cấp quyền truy cập nào không. Phản hồi đó sẽ được giải thích trong bước sau.
Lỗi
Các yêu cầu đến điểm cuối ủy quyền OAuth 2.0 của Google có thể hiển thị các thông báo lỗi mà người dùng thấy được thay vì các quy trình xác thực và ủy quyền dự kiến. Bên dưới là các mã lỗi phổ biến và cách giải quyết được đề xuất.
admin_policy_enforced
Tài khoản Google không thể ủy quyền một hoặc nhiều phạm vi được yêu cầu do các chính sách của quản trị viên Google Workspace của họ. Hãy xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát những nội dung & của bên thứ ba; 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 phạm vi nhạy cảm và bị hạn chế cho đến khi quyền truy cập được cấp rõ ràng vào mã ứng dụng OAuth của bạn.
disallowed_useragent
Điểm cuối ủy quyền được hiển thị bên trong tác nhân người dùng đã nhúng theo Chính sách OAuth 2.0 của Google.
Android
Nhà phát triển Android có thể nhận được thông báo lỗi này khi mở yêu cầu ủy 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ác nhà phát triển web có thể gặp lỗi này khi ứng dụng Android mở một đường liên kết 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 ủy quyền OAuth 2.0 của Google trên trang web của bạn. Nhà phát triển nên cho phép mở đườ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 (bao gồm 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 Các thẻ tùy chỉnh Android cũng là một tùy chọn được hỗ trợ.
iOS
Các nhà phát triển iOS và macOS có thể gặp lỗi này khi mở các yêu cầu ủy quyền trong
WKWebView.
Thay vào đó, nhà phát triển nên sử dụng các thư viện dành cho iOS như Đăng nhập bằng Google dành cho iOS hoặc AppAuth for iOS của OpenID Foundation.
Các 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 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 ủy quyền OAuth 2.0 của Google trên 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, bao gồm 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 OAuth trong yêu cầu 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ề tùy 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 đồng ý OAuth.
redirect_uri_mismatch
redirect_uri được chuyển trong yêu cầu ủy quyền không khớp với URI chuyển hướng được ủy quyền cho mã ứng dụng OAuth. Xem lại các URI chuyển hướng được ủy quyền trong
Google API Console Credentials page.
redirect_uri đã chuyển có thể không hợp lệ đối với loại ứng dụng.
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 ủy quyền sẽ 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ột mã ủy quyền (code) hoặc một 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ể đổi mã ủy quyền để biết mã truy cập và mã làm mới như được mô tả trong bước tiếp theo.
Bước 5: Trao đổi mã ủy quyền để làm mới và truy cập mã thông báo
Để trao đổi mã ủy 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:
| Trường | |
|---|---|
client_id |
Mã ứng dụng 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ã ủy quyền 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ư đã xác định trong quy cách OAuth 2.0, bạn phải đặt giá trị của trường này là authorization_code. |
redirect_uri |
Một trong các URI chuyển hướng được liệt kê cho dự án của bạn trong
API Console
Credentials page cho
client_id đã cho. |
Đoạn mã sau đây hiển thị 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:
| Trường | |
|---|---|
access_token |
Mã thông báo mà ứng dụng của bạn gửi để ủy quyền một yêu cầu API của Google. |
expires_in |
Thời gian còn lạ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ị này là một Mã thông báo web JSON (JWT) chứa thông tin nhận dạng đã ký kỹ thuật số về người dùng. |
refresh_token |
Mã thông báo mà bạn có thể sử dụng để lấy mã truy cập mới. Mã làm mới sẽ có hiệu lực 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ả lại cho ứng dụng đã cài đặt. |
scope |
Phạm vi truy cập do 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 và phân biệt chữ hoa chữ thường. |
token_type |
Loại mã thông báo được trả về. Lúc 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 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ã đó để gọi điện đến API Google
thay mặt cho một
tài khoản người dùng nhất định nếu(các) phạm vi quyền truy cập mà API yêu cầu đã cấp. Để làm điều này, hãy đưa mã truy cập vào yêu cầu API bằng cách thêm thông số truy vấn access_token hoặc tiêu đề Authorization tiêu đề HTTP Bearer. Khi có thể, bạn nên dùng tiêu đề HTTP vì các chuỗi truy vấn 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 thư viện ứng dụng để thiết lập lệnh gọi đến API 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 này tại OAuth 2.0 Playground.
Ví dụ về HTTP GET
Lệnh gọi đến điểm cuối
drive.files (API Drive Drive) bằng cách 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 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 đã xác thực bằng cách sử dụng thông 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 tra các lệnh này bằng ứng dụng dòng lệnh curl. Sau đây là ví dụ về cách sử dụng tùy 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ã thông báo 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 đăng nhập 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 về quyền (bao gồm cả khi người dùng không hiện diện) 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ã đó.
Để làm mới mã truy cập, ứng dụng của bạn sẽ gửi một yêu cầu POST HTTPS đến máy chủ ủy quyền của Google (https://oauth2.googleapis.com/token) trong đó có các thông số sau:
| Trường | |
|---|---|
client_id |
Mã ứng dụng được lấy 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 đăng ký dưới dạng ứng dụng
Android, iOS hoặc Chrome.)
|
grant_type |
Như đã xác định trong quy cách OAuth 2.0, bạn phải đặt giá trị của trường này là refresh_token. |
refresh_token |
Mã làm mới sẽ trả về từ sàn giao dịch mã ủy quyền. |
Đoạn mã sau đây hiển thị 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 cấp cho ứng dụng, thì máy chủ mã thông báo sẽ trả về một đố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 sẽ 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 khác cho mỗi người dùng trên tất cả khách hàng. Bạn nên lưu các 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ã thông báo đó, miễn là các mã này 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, ứng dụng có thể gặp phải các giới hạn này. Trong trường hợp đó, các mã thông báo 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 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 Xóa quyền truy cập vào trang web hoặc ứng dụng của trang web bên thứ ba và amp; các ứng dụng có quyền truy cập vào tài khoản của bạn tài liệu hỗ trợ để biết thêm thông tin.
Ứng dụng cũng có thể thu hồi quyền truy cập được cấp theo phương thức lập trình. Tính năng thu hồi có lập trình đóng vai trò quan trọng trong các trường hợp người dùng hủy đăng ký, xoá một ứng dụng hoặc cá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, quy trình xoá có thể chứa một yêu cầu API để đảm bảo những quyền trước đây đã cấp cho ứng dụng này 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ẽ yêu cầu
https://oauth2.googleapis.com/revoke và đưa mã thông báo làm 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ã mới, 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 đ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
Các phương pháp hay nhất hiện tại về 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.