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

Tài liệu này giải thích cách các ứng dụng được cài đặt trên thiết bị như điện thoại, máy tính bảng và máy tính sử dụng điểm cuối OAuth 2.0 của Google để cho phép truy cập vào API của Google.

OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với ứng dụng trong khi vẫn giữ cho tên người dùng, mật khẩu và các thông tin khác ở chế độ riêng tư. Ví dụ: một ứng dụng có thể dùng OAuth 2.0 để được cấp quyền người dùng lưu trữ tệp trong Google Drive của họ.

Các ứng dụng đã cài đặt sẽ được phân phối đến từng thiết bị và người dùng giả định rằng những ứng dụng này không thể giữ bí mật. Chúng có thể truy cập vào các API của Google trong khi người dùng có mặt trên ứng dụng hoặc khi ứng dụng đang chạy trong nền.

Quy trình uỷ quyền này tương tự như quy trình được dùng cho ứng dụng máy chủ web. Điểm khác biệt chính là ứng dụng đã cài đặt đó phải mở trình duyệt hệ thống và cung cấp URI chuyển hướng cục bộ để xử lý phản hồi từ máy chủ uỷ quyền của Google.

Lựa chọn thay thế

Đối với ứng dụng dành cho thiết bị di động, bạn có thể thích sử dụng tính năng Đăng nhập bằng Google hơn Android hoặc iOS. Thông tin đăng nhập bằng Google thư viện ứng dụng xử lý việc xác thực và uỷ quyền của người dùng và chúng có thể đơn giản hơn triển khai khác so với giao thức cấp thấp hơn được mô tả ở đây.

Đối với các ứng dụng chạy trên thiết bị không hỗ trợ trình duyệt hệ thống hoặc có dữ liệu đầu vào hạn chế các chức năng như TV, máy chơi trò chơi, máy ảnh hoặc máy in, hãy xem OAuth 2.0 cho TV và Thiết bị hoặc Đăng nhập trên TV và các thiết bị đầu vào hạn chế.

Thư viện và mẫu

Bạn nên dùng các thư viện và mẫu sau đây để giúp bạn triển khai quy trình OAuth 2.0 được mô tả trong tài liệu này:

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

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

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

Cách bật API cho dự án:

  1. Open the API Library trong Google API Console.
  2. If prompted, select a project, or create a new one.
  3. API Library liệt kê tất cả các API có sẵn, được nhóm theo sản phẩm gia đình và độ nổi tiếng. Nếu API bạn muốn bật không hiển thị trong danh sách, hãy sử dụng tính năng tìm kiếm để tìm biểu tượng hoặc nhấp vào Xem tất cả trong nhóm sản phẩm chứa mục đó.
  4. Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Tạo thông tin xác thực cho phép

Mọi ứng dụng sử dụng OAuth 2.0 để truy cập API Google đều phải có thông tin xác thực uỷ quyền xác định ứng dụng tới máy chủ OAuth 2.0 của Google. Các bước sau đây sẽ giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, ứng dụng của bạn có thể sử dụng thông tin xác thực để truy cập API mà bạn đã bật cho dự án đó.

  1. Go to the Credentials page.
  2. Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
  3. Các phần dưới đây mô tả các loại ứng dụng và phương thức chuyển hướng mà Google máy chủ uỷ quyền hỗ trợ. Chọn loại ứng dụng được đề xuất cho , đặt tên cho ứng dụng OAuth và đặt các trường khác trong biểu mẫu là phù hợp.
Android
  1. Chọn loại ứng dụng Android.
  2. 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.
  3. 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 package của phần tử <manifest> trong tệp kê khai ứng dụng.
  4. 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ị SHA1 trong phần Certificate fingerprints củ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.
  5. (Không bắt buộc) Xác minh quyền sở hữu thiết bị Android của bạn .
  6. 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 OAuth. Tên này được hiển thị trên Credentials page để xác định khách hàng.
  3. 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.
  4. (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.

    1. Mở Ứng dụng App Store của Apple trên thiết bị iOS hoặc iPadOS.
    2. Tì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 đường liên kết.
    5. 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

  5. (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.

  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 OAuth. Tên này được hiển thị trên Credentials page để xác định khách hàng.
  3. 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.
  4. 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 Android

Sử 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:

  1. Hãy cập nhật mã của bạn để sử dụng SDK đăng nhập bằng Google.
  2. 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:

  1. Cập nhật mã của bạn để sử dụng SDK Android đăng nhập bằng Google:
    1. 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:/oauth2redirect là 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.
    2. Hãy lưu ý các tham số yêu cầu scopeclient_id bạn sẽ cần định cấu hình SDK đăng nhập bằng Google.
    3. 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_id mà bạn truy xuất từ bước trước.
    4. Làm theo Bật quyền truy cập vào API phía máy chủ . Quá trình này bao gồm các bước sau:
      1. 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.
      2. 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.
      3. 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.
  2. Tắt tính năng hỗ trợ cho lược đồ tuỳ chỉnh trong Google API Console:
    1. Chuyển đến Thông tin đăng nhập OAuth 2.0 và chọn ứng dụng Android của bạn.
    2. 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:
  1. 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.
  2. 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.
Giải pháp thay thế cho việc sử dụng giao thức URI tuỳ chỉnh trên ứng dụng Chrome

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 cho ứng dụng nghĩa 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.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
đơn thuần Thử thách mã có cùng giá trị với trình xác minh mã đã tạo ở trên.
code_challenge = code_verifier

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

Để nhận được sự cho phép của người dùng, hãy gửi yêu cầu tới máy chủ cấp phép của Google tại https://accounts.google.com/o/oauth2/v2/auth. Điểm cuối này xử lý hoạt động tra cứu phiên đang hoạt động, xác thực người dùng và lấy sự đồng ý của người dùng. Chỉ có thể truy cập vào điểm cuối qua SSL và từ chối kết nối HTTP (không có SSL).

Máy chủ uỷ quyền hỗ trợ các tham số chuỗi truy vấn sau cho các máy chủ đã cài đặt ứng dụng:

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. Đồ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 redirect_uri_mismatch.

Bảng bên dưới trình bày giá trị tham số redirect_uri thích hợp cho từng phương thức:

Giá trị redirect_uri
Lược đồ URI tuỳ chỉnh com.example.app:redirect_uri_path

hoặc

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app là ký hiệu DNS ngược của miền trong quyền kiểm soát của bạn. Giao thức tuỳ chỉnh phải chứa dấu chấm thì mới hợp lệ.
  • com.googleusercontent.apps.123 là ký hiệu DNS ngược của mã ứng dụng khách.
  • redirect_uri_path là thành phần đường dẫn không bắt buộc, chẳng hạn như /oauth2redirect. Xin 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 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 để biết địa chỉ IP vòng lặp có liên quan và bắt đầu một HTTP trình nghe trên một cổng ngẫu nhiên có sẵn. Thay thế port bằng giá trị thực tế số cổng mà ứng dụng của bạn nghe trên đó.

Lưu ý rằng có hỗ trợ tuỳ chọn chuyển hướng địa chỉ IP loopback trên thiết bị di động ứng dụng ĐÃ NGỪNG HOẠT ĐỘNG.

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 code cho các ứng dụng đã cài đặt.

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_verifier đã mã hoá sẽ được dùng làm phía máy chủ trong quá trình trao đổi mã uỷ quyền. Xem tạo mã thử thách ở trên để biết thêm thông tin.

code_challenge_method Recommended (Nên dùng)

Chỉ định phương thức dùng để mã hoá code_verifier sẽ được dùng trong quá trình trao đổi mã uỷ quyền. Bạn phải dùng thông số này cùng với Tham số code_challenge như 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ị duy nhất được hỗ trợ cho thông số này là S256 hoặc plain.

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 name=value trong Giá trị nhận dạng phân đoạn URL (#) của redirect_uri sau khi người dùng đồng ý hoặc từ chối các quyền yêu cầu truy 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 redirect_uri của bạn, nên sử dụng state có thể làm tăng sự bảo đảm 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ã hoá hàm băm của một cookie hoặc một giá trị khác nắm bắt trạng thái của ứng dụng, bạn có thể xác thực phản hồi để ngoài ra, hãy đảm bảo rằng yêu cầu và phản hồi được bắt nguồn từ cùng một trình duyệt, cung cấp biện pháp bảo vệ chống lại các cuộc tấn công như yêu cầu trên nhiều trang web giả mạo. Xem OpenID Connect tài liệu về 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 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 sub, tức là tương đương với mã nhận dạng trên Google của người 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_typeclient_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 trên khách hàng/người dùng và một tổ hợp khách hàng/người dùng khác cho mỗi người dùng trên tất cả khách hàng. Bạn nên lưu mã làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng miễn là chúng vẫn hợp lệ. Nếu ứng dụng của bạn yêu cầu quá nhiều mã làm mới, thì mã này có thể gặp phải các giới hạn này. Trong trường hợp đó, các mã làm mới cũ hơn sẽ ngừng hoạt động.

Thu hồi mã thông báo

Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào Account Settings (Cài đặt tài khoản). Xem Xoá phần truy cập trang web hoặc ứng dụng trong mục Trang web bên thứ ba & các ứng dụng có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.

Ứng dụng cũng có thể thu hồi quyền truy cập đã cấp cho ứng dụng theo cách lập trình. Việc thu hồi có lập trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá ứng dụng hoặc tài nguyên API mà một ứng dụng yêu cầu đã thay đổi đáng kể. Nói cách khác, Một phần của quy trình xoá có thể bao gồm yêu cầu API để đảm bảo các quyền trước đó được cấp cho ứng dụng sẽ bị xoá.

Để thu hồi mã thông báo theo cách lập trình, ứng dụng sẽ đưa ra yêu cầu https://oauth2.googleapis.com/revoke và bao gồm mã thông báo dưới dạng tham số:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Mã này có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo là một mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.

Nếu việc thu hồi được xử lý thành công thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, mã trạng thái HTTP 400 sẽ được trả về cùng với có mã lỗi.

Tài liệu đọc thêm

Phương pháp hay nhất hiện tại của IETF OAuth 2.0 cho Ứng dụng gốc thiết lập nhiều phương pháp hay nhất được nêu ở đây.

Triển khai tính năng Bảo vệ nhiều tài khoản

Bạn nên thực hiện thêm một bước để bảo vệ đang triển khai tính năng Nhiều tài khoản Bảo vệ bằng cách sử dụng Dịch vụ bảo vệ nhiều tài khoản của Google. Dịch vụ này cho phép bạn đăng ký nhận thông báo sự kiện bảo mật nhằm cung cấp thông tin cho ứng dụng của bạn về những thay đổi lớn đối với tài khoản người dùng. Sau đó, bạn có thể sử dụng thông tin này để thực hiện hành động tùy thuộc vào cách bạn quyết định phản hồi sự kiện.

Dưới đây là một số ví dụ về các loại sự kiện mà Dịch vụ bảo vệ nhiều tài khoản của Google gửi tới ứng dụng của bạn:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Xem Bảo vệ tài khoản người dùng bằng trang Bảo vệ nhiều tài khoản để biết thêm thông tin về cách triển khai tính năng Bảo vệ nhiều tài khoản và để biết danh sách đầy đủ các sự kiện hiện có.