OAuth 2.0 dành cho ứng dụng dành cho thiết bị di động và máy tính để bàn

Tài liệu này giải thích cách các ứng dụng được cài đặt trên các thiết bị như điện thoại, máy tính bảng và máy tính sử dụng điểm cuối OAuth 2.0 của Google để 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 trong khi vẫn giữ bí mật tên người dùng, mật khẩu và thông tin khác của họ. 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ọ.

Các ứng dụng đã cài đặt được phân phối tới các thiết bị riêng lẻ và người ta cho rằng các ứng dụng này không thể giữ bí mật. Họ có thể truy cập các API của Google trong khi người dùng có mặt tại ứ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 được sử dụng cho các ứng dụng máy chủ web . Sự 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.

Giải pháp thay thế

Đối với các ứng dụng dành cho thiết bị di động, bạn có thể thích sử dụng Đăng nhập bằng Google cho Android hoặc iOS . Thư viện ứng dụng khách Đăng nhập của Google xử lý xác thực và ủy quyền người dùng và chúng có thể dễ triển khai hơn so với giao thức cấp thấp hơn được mô tả tại đâ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ó khả năng đầu vào hạn chế, chẳng hạn như TV, bảng điều khiển trò chơi, máy ảnh hoặc máy in, hãy xem OAuth 2.0 dành 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

Chúng tôi đề xuất 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:

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

Bật API cho dự án của bạn

Bất kỳ ứng dụng nào gọi API Google đều cần bật các API đó trong API Console.

Để kích hoạt một API cho dự án của bạ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 họ 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ìm kiếm để tìm nó hoặc nhấp vào Xem tất cả trong họ sản phẩm mà nó thuộc về.
  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 ủy quyền

Bất kỳ ứng dụng nào sử dụng OAuth 2.0 để truy cập Google API đều phải có thông tin xác thực ủy quyền 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 đăng nhập cho dự án của bạn. Các ứng dụng của bạn sau đó có thể sử dụng thông tin đăng nhập để truy cập các API mà bạn đã bật cho dự án đó.

  1. Go to the Credentials page.
  2. Nhấp vào Tạo thông tin xác thực> ID ứng dụng khách OAuth .
  3. Các phần bên dưới mô tả các loại ứng dụng khách và các phương pháp chuyển hướng mà máy chủ ủy quyền của Google hỗ trợ. Chọn loại ứng dụng được khuyến nghị cho ứng dụng của bạn, đặt tên cho ứng dụng OAuth của bạn và đặt các trường khác trong biểu mẫu sao cho phù hợp.

Lược đồ URI tùy chỉnh (Android, iOS, UWP)

Lược đồ URI tùy chỉnh được khuyến nghị cho các ứng dụng Android, ứng dụng iOS và ứng dụng Nền tảng Windows chung (UWP).

Android
  1. Chọn loại ứng dụng Android .
  2. Nhập tên cho ứng dụng khách OAuth. Tên này được hiển thị trên Credentials page của dự án của bạn để xác định khách hàng.
  3. Nhập tên gói của ứng dụng Android của bạn. Giá trị này được xác định trong thuộc tính package của phần tử <manifest> trong tệp kê khai ứng dụng của bạn.
  4. Nhập tệp tham chiếu 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 tệp tham chiếu 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 sử dụng tiện ích keytool đi kèm với Java để in thông tin chứng chỉ ở định dạng con người có thể đọc được. Sao chép giá trị SHA1 trong phần Dấu Certificate fingerprints của đầu ra công cụ bàn phím. Xem Xác thực khách hàng của bạn trong tài liệu Google API dành cho Android để biết thêm thông tin.
  5. Nhấp vào Tạo .
iOS
  1. Chọn loại ứng dụng iOS .
  2. Nhập tên cho ứng dụng khách OAuth. Tên này được hiển thị trên Credentials page của dự án của bạn để xác định khách hàng.
  3. Nhập số nhận dạng gói cho ứng dụng của bạn. ID 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ị được hiển thị phổ biến nhất trong ngăn Chung hoặc ngăn Ký tên & Khả năng của trình soạn thảo dự án Xcode. ID 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 App Store Connect của Apple .
  4. (Không bắt buộc)

    Nhập ID cửa hàng ứng dụng của ứng dụng của bạn nếu ứng dụng được xuất bản trong Cửa hàng ứng dụng của Apple. ID cửa hàng là một chuỗi số được bao gồm trong mọi URL của Apple App Store.

    1. Mở ứng dụng Apple App Store trên thiết bị iOS hoặc iPadOS của bạn.
    2. Tìm kiếm ứng dụng của bạn.
    3. Chọn nút Chia sẻ (biểu tượng hình vuông và mũi tên lên).
    4. Chọn Sao chép liên kết .
    5. Dán liên kết vào một trình soạn thảo văn bản. ID App Store là phần cuối cùng của URL.

      Ví dụ: https://apps.apple.com/app/google/id 284815942

  5. (Không bắt buộc)

    Nhập ID nhóm của bạn. Xem Định vị ID nhóm của bạn trong tài liệu Tài khoản nhà phát triển Apple để biết thêm thông tin.

  6. Nhấp vào Tạo .
UWP
  1. Chọn loại ứng dụng Universal Windows Platform .
  2. Nhập tên cho ứng dụng khách OAuth. Tên này được hiển thị trên Credentials page của dự án của bạn để xác định khách hàng.
  3. Nhập ID Microsoft Store gồm 12 ký tự cho ứng dụng của bạn. 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 Nhận dạng ứng dụng trong phần Quản lý ứng dụng.
  4. Nhấp vào Tạo .

Đối với các ứng dụng UWP, lược đồ URI tùy chỉnh không được dài hơn 39 ký tự.

Địa chỉ IP vòng lặp (macOS, Linux, máy tính để bàn Windows)

Để nhận mã ủy quyền bằng URL này, ứng dụng của bạn phải đang lắng 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ợ thì đây là cơ chế được khuyến nghị để lấy mã ủy quyền.

Khi ứng dụng của bạn nhận được phản hồi ủy quyền, để có khả năng sử dụng tốt nhất, ứng dụng sẽ phản hồi bằng cách 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 được đề xuất Ứng dụng macOS, Linux và Windows dành cho máy tính để bàn (nhưng không phải Nền tảng Windows chung)
Giá trị biểu mẫu Đặt loại ứng dụng thành ứng dụng Máy tính để bàn .

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à nó cần đồng thời 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ể 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 nhận được sự đồng ý của người dùng.

Trước khi bắt đầu triển khai ủy quyền OAuth 2.0, chúng tôi khuyên 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 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 các API của Google.

Nhận mã thông báo 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 để có được sự đồng ý của người dùng để thay mặt người dùng thực hiện yêu cầu API. Ứng dụng của bạn phải có sự đồng ý đó trước khi có thể thực thi một yêu cầu API 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à thử thách

Google hỗ trợ giao thức Khóa Chứng minh cho Code Exchange (PKCE) để làm cho luồng ứng dụng đã 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 đế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 ngẫu nhiên mật mã entropy cao sử dụng các ký tự chưa được lưu trữ [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", với độ dài tối thiểu là 43 ký tự và độ dài tối đa là 128 ký tự.

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

Tạo thử thách mã

Hai phương pháp tạo thử thách mã được hỗ trợ.

Phương pháp tạo thử thách mã
S256 (khuyến nghị) Thử thách mã là hàm băm SHA256 được mã hóa Base64URL (không có phần đệm) của trình xác minh mã.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
đơn giản Thử thách mã có cùng giá trị với trình xác minh mã được tạo ở trên.
code_challenge = code_verifier

Bước 2: Gửi yêu cầu đến máy chủ OAuth 2.0 của Google

Để nhận ủy quyền của người dùng, hãy gửi yêu cầu tới máy chủ ủy quyền của Google tại https://accounts.google.com/o/oauth2/v2/auth . Điểm cuối này xử lý tra cứu phiên hoạt động, xác thực người dùng và nhận được sự đồng ý của người dùng. Điểm cuối chỉ có thể truy cập qua SSL và nó từ chối các 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:

Thông số
client_id Yêu cầu

ID khách hàng cho ứng dụng của bạn. Bạn có thể tìm thấy giá trị này trong API ConsoleCredentials page.

redirect_uri Yêu cầu

Xác định cách máy chủ ủy quyền của Google gửi phản hồi đến ứng dụng của bạn. Có một số tùy chọn chuyển hướng có sẵn cho các ứng dụng đã cài đặt và bạn sẽ phải thiết lập thông tin xác thực ủy quyền của mình với một phương pháp chuyển hướng cụ thể.

Giá trị phải khớp chính xác với một trong các URI chuyển hướng được ủy quyền cho ứng dụng khách OAuth 2.0 mà bạn đã định cấu hình trong API ConsoleCredentials pagecủa ứng dụng khách. Nếu giá trị này không khớp với URI được ủy quyền, bạn sẽ gặp lỗi redirect_uri_mismatch .

Bảng bên dưới hiển thị giá trị tham số redirect_uri thích hợp cho mỗi phương thức:

giá trị redirect_uri
Lược đồ URI tùy chỉnh com.example.app : redirect_uri_path

hoặc là

com.googleusercontent.apps.123 : redirect_uri_path
  • com.example.app là ký hiệu DNS ngược của miền do bạn kiểm soát. Lược đồ tùy chỉnh phải chứa một khoảng thời gian để có hiệu lực.
  • com.googleusercontent.apps.123 là ký hiệu DNS ngược của ID ứng dụng khách.
  • redirect_uri_path là một thành phần đường dẫn tùy chọn, chẳng hạn như /oauth2redirect . Lưu ý rằng đường dẫn phải bắt đầu bằng một dấu gạch chéo, khác với các URL HTTP thông thường.
Địa chỉ IP lặp lại http://127.0.0.1: port hoặc http://[::1]: port

Truy vấn nền tảng của bạn địa chỉ IP lặp lại có liên quan và bắt đầu trình nghe HTTP trên một cổng ngẫu nhiên có sẵn. Thay thế port bằng số cổng thực tế mà ứng dụng của bạn sử dụng.

Sao chép / dán thủ công urn:ietf:wg:oauth:2.0:oob
Trích xuất có lập trình urn:ietf:wg:oauth:2.0:oob:auto
response_type Yêu cầu

Xác định xem điểm cuối Google OAuth 2.0 có trả lại mã ủy quyền hay không.

Đặt giá trị tham số thành code cho các ứng dụng đã cài đặt.

scope Yêu cầu

Một 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. Các giá trị này thông báo cho 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 mà nó cần đồng thời 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ó mối quan hệ nghịch đảo 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 Khuyến khích

Chỉ định một code_verifier được mã hóa sẽ được sử dụng như một thử thách phía máy chủ trong quá trình trao đổi mã ủy quyền. Xem phần tạo thử thách mã ở trên để biết thêm thông tin.

code_challenge_method Khuyến khích

Chỉ định phương thức nào được sử dụng để mã hóa code_verifier sẽ được sử dụng trong quá trình trao đổi mã ủy quyền. Tham số này phải được sử dụng với tham số code_challenge được mô tả ở trên. Giá trị của code_challenge_method mặc định là plain nếu không có trong yêu cầu bao gồm code_challenge . Các giá trị được hỗ trợ duy nhất cho tham số này là S256 hoặc plain .

state Khuyến khích

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 ủ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 cặp name=value trong mã định danh phân đoạn URL ( # ) của redirect_uri sau khi người dùng đồng ý hoặc từ chối yêu cầu truy cập ứng dụng của bạn.

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 tài nguyên chính xác trong ứng dụng của bạn, gửi các lỗi khác và giảm thiểu giả mạo yêu cầu trên nhiều trang web. Vì redirect_uri của bạn có thể được đoán, việc sử dụng giá trị state có thể làm tăng sự đảm bảo của bạn rằng kết nối đến là kết quả của một yêu cầu xác thực. Nếu bạn tạo một chuỗi ngẫu nhiên hoặc mã hóa băm của cookie hoặc một giá trị khác nắm bắt trạng thái của khách hàng, bạn có thể xác thực phản hồi để đảm bảo thêm rằng yêu cầu và phản hồi bắt nguồn từ cùng một trình duyệt, cung cấp khả năng bảo vệ chống lại các cuộc tấn công chẳng hạn như trang web chéo yêu cầu giả mạo. Xem tài liệu OpenID Connect để biết ví dụ về cách tạo và xác nhận mã thông báo state .

login_hint Không bắt buộc

Nếu ứng dụng của bạn biết người dùng nào đang cố xác thực, ứng dụng có thể sử dụng tham 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 trước trường email trong biểu mẫu đăng nhập hoặc bằng cách chọn phiên nhiều đăng nhập thích hợp.

Đặt giá trị tham số thành địa chỉ email hoặc số nhận dạng sub , giá trị này tương đương với ID Google của người dùng.

URL ủy quyền mẫu

Các tab bên dưới hiển thị các 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 tham số redirect_uri . Các URL cũng chứa các tham số response_typeclient_id bắt buộc cũng như tham số state tùy chọn. Mỗi URL chứa các ngắt dòng và khoảng trắng để có thể đọc được.

Lược đồ URI tùy 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 lặp lại

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

Sao chép dán

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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&
 client_id=client_id

Trích xuất có lập trì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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
 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 được yêu cầu hay không. Ở giai đoạn này, Google hiển thị cửa sổ đồng ý hiển thị tên ứng dụng của bạn và các dịch vụ API của Google mà Google đang yêu cầu quyền truy cập bằng thông tin xác thực ủy quyền của người dùng và bản tóm tắt các phạm vi truy cập đượ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 do ứ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 thực hiện bất kỳ điều gì ở giai đoạn này vì nó 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. Phản ứng đó được giải thích trong bước sau.

Lỗi

Các yêu cầu tới điểm cuối ủy quyền OAuth 2.0 của Google có thể hiển thị thông báo lỗi do người dùng đối mặt thay vì các quy trình xác thực và ủy quyền như mong đợi. Các mã lỗi phổ biến và các giải pháp được đề xuất được liệt kê bên dưới.

admin_policy_enforced

Tài khoản Google không thể cấp phép 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ọ. Xem bài viết trợ giúp Quản trị không gian làm việc của Google Kiểm soát ứng dụng bên thứ ba và ứng dụng nội bộ nào truy cập vào dữ liệu Không gian làm việc của Google để 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 cho ID ứng dụng khách 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 được nhúng không được Chính sách OAuth 2.0 của Google cho phép.

Android

Các 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 ủy quyền trongandroid.webkit.WebView . Thay vào đó, các nhà phát triển nên sử dụng các thư viện Android như Google Sign-In cho Android hoặc AppAuth của OpenID Foundation 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ở liên kết web chung trong tác nhân người dùng được nhúng và người dùng điều hướng đến điểm cuối ủy quyền OAuth 2.0 của Google từ trang web của bạn. Các nhà phát triển nên cho phép các liên kết chung mở trong trình xử lý liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Liên kết ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Thư viện Tab tùy chỉnh của 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ở yêu cầu cấp quyền trongWKWebView . Thay vào đó, các nhà phát triển nên sử dụng các thư viện iOS như Google Sign-In cho iOS hoặc AppAuth của OpenID Foundation cho iOS .

Các nhà phát triển web có thể gặp phải lỗi này khi ứng dụng iOS hoặc macOS mở liên kết web chung trong tác nhân người dùng được nhúng và người dùng điều hướng đến điểm cuối ủy quyền OAuth 2.0 của Google từ trang web của bạn. Các nhà phát triển nên cho phép các liên kết chung mở trong trình xử lý liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Liên kết chung hoặc ứng dụng trình duyệt mặc định. Thư việnSFSafariViewController cũng là một tùy chọn được hỗ trợ.

org_internal

ID ứng dụng khách OAuth trong yêu cầu là một phần của dự án giới hạn 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 chấp thuận OAuth của bạn.

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 ID ứng dụng khách OAuth. Xem lại các URI chuyển hướng được ủy quyền trong Google API Console Credentials page.

redirect_uri được thông qua có thể không hợp lệ đối với loại khách hàng.

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 ủy quyền 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ộ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ể trao đổi mã ủy quyền để lấy mã thông báo 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 lấy mã thông báo truy cập, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt các thông số sau:

Lĩnh vực
client_id ID khách hàng thu được từ API ConsoleCredentials page.
client_secret Bí mật khách hàng thu được từ API ConsoleCredentials page.
code Mã ủy quyền được trả về từ yêu cầu ban đầu.
code_verifier Trình xác minh mã bạn đã tạo ở Bước 1 .
grant_type Như đã định nghĩa trong thông số kỹ thuật OAuth 2.0 , giá trị của trường này phải authorization_code đặt thành Authority_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 ConsoleCredentials page cho client_id đã cho.

Đ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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
grant_type=authorization_code

Google đáp ứng yêu cầu này bằng cách trả về một đối tượng JSON có chứa mã thông báo truy cập tồn tại trong thời gian ngắn và mã thông báo làm mới.

Phản hồi chứa các trường sau:

Lĩnh vực
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òn lại của mã thông báo truy cập tính bằng giây.
id_token Lưu ý: Thuộc tính này chỉ được trả lại nếu yêu cầu của bạn bao gồm phạm vi nhận dạng, 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 được ký điện tử về người dùng.
refresh_token Mã thông báo mà bạn có thể sử dụng để lấy mã thông báo truy cập mới. Làm mới mã thông báo có giá trị 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 các ứng dụng đã cài đặt.
scope Các phạm vi truy cập được cấp bởi access_token được biểu thị dưới dạng danh sách các chuỗi phân biệt 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ả lại. 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 các API của Google

Sau khi ứng dụng của bạn nhận được mã thông báo truy cập, bạn có thể sử dụng mã này để thực hiện các cuộc gọi tới 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 truy cập mà API yêu cầu đã được cấp. Để thực hiện việc này, hãy bao gồm mã thông báo truy cập trong một yêu cầu tới API bằng cách bao gồm tham số truy vấn access_token hoặc giá trị Bearer hiệu tiêu đề HTTP Authorization . Khi có thể, tiêu đề HTTP được ưu tiên hơn, vì các chuỗi truy vấn có xu hướng hiển thị trong nhật ký máy chủ. Trong hầu hết các trường hợp, bạn có thể sử dụng thư viện ứng dụng khách để thiết lập lệnh gọi của mình tới API Google (ví dụ: khi gọi API tệp Drive ).

Bạn có thể thử tất cả các API của Google và xem phạm vi của chúng tại Sân chơi OAuth 2.0 .

Ví dụ về HTTP GET

Một lệnh gọi đến điểm cuối drive.files (API Tệp ​​Drive) bằng cách sử dụng tiêu đề HTTP Authorization: Bearer có thể trông giống như sau. Lưu ý rằng bạn cần chỉ định mã thông báo truy cập của riêng mình:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Đâ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ụ curl

Bạn có thể kiểm tra các lệnh này bằng ứng dụng dòng lệnh curl . Dưới đây là một ví dụ 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, cách khá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 hết hạn định kỳ và trở thành thông tin xác thực không hợp lệ cho một yêu cầu API liên quan. Bạn có thể làm mới mã thông báo 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ó mặt) nếu bạn yêu cầu quyền truy cập ngoại tuyến vào các phạm vi được liên kết với mã thông báo.

Để làm mới mã thông báo truy cập, ứng dụng của bạn sẽ gửi một yêu cầu HTTPS POST tới máy chủ ủy quyền của Google ( https://oauth2.googleapis.com/token ) bao gồm các thông số sau:

Lĩnh vực
client_id ID khách hàng thu được từ API Console.
client_secret Bí mật khách hàng thu được từ API Console. ( client_secret không áp dụng cho các yêu cầu từ các ứng dụng khách được đăng ký là ứng dụng Android, iOS hoặc Chrome.)
grant_type Như đã định nghĩa trong đặc 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ả lại từ trao đổi mã ủy 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 có chứa mã thông báo 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"
}

Lưu ý rằng có giới hạn về số lượng mã làm mới sẽ được phát hành; một giới hạn cho mỗi kế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ả các khách hàng. Bạn nên lưu mã thông báo làm mới trong bộ nhớ lâu dài và tiếp tục sử dụng chúng miễn là chúng vẫn còn hiệu lực. Nếu ứng dụng của bạn yêu cầu quá nhiều mã làm mới, nó có thể gặp phải những 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 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 Cài đặt tài khoản . Xem phần Xóa trang web hoặc quyền truy cập ứng dụng của Trang web và ứng dụng của bên thứ ba có quyền truy cập vào tài liệu hỗ trợ 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 cấp theo chương trình. Việc thu hồi có lập trình rất quan trọng trong trường hợp người dùng hủy đăng ký, xóa ứ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 quá trình xóa có thể bao gồm yêu cầu API để đảm bảo các quyền đã cấp trước đó cho ứng dụng bị xóa.

Để thu hồi mã thông báo theo chương trình, ứng dụng của bạn đưa ra yêu cầu tới 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ã thông báo có thể là mã thông báo truy cập hoặc mã thông báo làm mới. Nếu mã thông báo là mã thông báo truy cập và nó có mã thông báo 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 là 200 . Đối với các điều kiện lỗi, mã trạng thái HTTP 400 được trả về cùng với mã lỗi.

Đọc thêm

Thực tiễn tốt nhất hiện tại của IETF OAuth 2.0 dành cho ứng dụng gốc thiết lập nhiều phương pháp hay nhất được ghi lại ở đây.