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 những 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 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 bảo mật tên người dùng, mật khẩu và các thông tin khác của họ. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để xin người dùng cấp quyền lưu trữ tệp trong Google Drive.

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

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

Lựa chọn thay thế

Đối với ứng dụng di động, bạn nên dùng tính năng Đăng nhập bằng Google cho Android hoặc iOS. Thư viện ứng dụng Đăng nhập bằng Google xử lý việc xác thực và uỷ quyền của người dùng. Các thư viện này có thể đơn giản hơn để triển khai 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 những thiết bị không hỗ trợ trình duyệt hệ thống hoặc có khả năng đầu vào 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à thiết bị hoặc Đăng nhập trên TV và Thiết bị đầu vào hạn chế.

Thư viện và mẫu

Bạn nên sử dụng các thư viện và mẫu sau để giúp 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

Bất kỳ ứng dụng nào gọi API của Google đề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 nhóm sản phẩm và mức độ phổ biến. Nếu API bạn muốn bật không xuất hiện trong danh sách, hãy 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 đó.
  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 uỷ quyền

Mọi ứng dụng dùng OAuth 2.0 để truy cập vào API Google đều phải có thông tin xác thực uỷ quyền giúp nhận dạng ứng dụng đó vớ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 đăng nhập để truy cập vào 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 > Mã ứng dụng khách OAuth.
  3. Phần dưới đây mô tả các loại ứng dụng và phương thức chuyển hướng mà máy chủ uỷ quyền của Google hỗ trợ. Chọn loại ứng dụng được đề xuất cho ứng dụng của bạn, đặt tên cho ứng dụng OAuth và thiết lập các trường khác trong biểu mẫu sao cho 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 sẽ xuất hiện trên Credentials page của dự án để xác định ứng dụng khách.
  3. Nhập tên gói ứ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 quy 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 vân tay số SHA-1 từ trang ký ứng dụng trên Play Console.
    • Nếu bạn quản lý kho khoá và khoá ký của riêng mình, hãy sử dụng tiện ích keytool đi kèm với Java để in thông tin chứng chỉ ở định dạng có thể đọc được. Sao chép giá trị SHA1 trong phần Certificate fingerprints của đầu ra keytool. Hãy xem phần 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.
  5. (Không bắt buộc) Xác minh quyền sở hữu ứng dụng 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 sẽ xuất hiện trên Credentials page của dự án để xác định ứng dụng khách.
  3. 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 khoá CFBundleIdentifier trong tệp tài nguyên danh sách thuộc tính thông tin của ứng dụng (info.plist). Giá trị này thường xuất hiện nhất trong ngăn Chung hoặc ngăn Ký và chức năng của trình chỉnh sửa dự án Xcode. Mã nhận dạng gói cũng xuất hiện 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 của bạn.
    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 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. Hãy xem phần 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 sẽ xuất hiện trên Credentials page của dự án để xác định ứng dụng khách.
  3. Nhập mã cửa hàng gồm 12 ký tự của ứng dụng trên Microsoft Store. 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.
  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 tùy chỉnh là một dạng của đường liên kết sâu sử dụng lược đồ được xác định tùy chỉnh để mở ứng dụng của bạn.

Thay thế cho việc sử dụng lược đồ URI tuỳ chỉnh trên Android

Sử dụng SDK Đăng nhập bằng Google cho Android. SDK này cung cấp phản hồi OAuth 2.0 trực tiếp cho ứng dụng của bạn, giúp bạn không cần URI chuyển hướng.

Cách chuyển sang SDK Đăng nhập bằng Google cho Android

Nếu đang sử dụng một lược đồ tuỳ chỉnh để tích hợp OAuth trên Android, thì bạn cần hoàn thành các thao tác dưới đây để chuyển hoàn toàn sang sử dụng SDK Đăng nhập bằng Google cho Android được đề xuất:

  1. 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 để 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 nơi bạn đang gửi yêu cầu đến máy chủ OAuth 2.0 của Google; nếu sử 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ụ trên. Hãy 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ị lược đồ URI tuỳ chỉnh.
    2. Hãy lưu ý các tham số yêu cầu scopeclient_id mà bạn cần để định cấu hình SDK Đăng nhập bằng Google.
    3. Làm theo hướng dẫn 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 bước Lấy mã ứng dụng khách OAuth 2.0 của máy chủ phụ trợ vì sử dụng lại client_id mà bạn đã truy xuất từ bước trước.
    4. Làm theo hướng dẫn Bật quyền truy cập 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 quyền.
      2. Gửi mã xác thực đến phần phụ trợ của ứng dụng để đổi mã đó lấy mã truy cập và làm mới.
      3. Sử dụng mã truy cập đã truy xuất để thực hiện lệnh gọi đến các API của Google thay mặt người dùng.
  2. Tắt tính năng hỗ trợ cho lược đồ tuỳ chỉnh trong Google API Console:
    1. Chuyển đến danh sách Thông tin đăng nhập OAuth 2.0 rồi chọn ứng dụng Android của bạn.
    2. Chuyển đến phần Advanced Settings (Cài đặt nâng cao), bỏ đánh dấu hộp đánh dấu Enable Custom URI Scheme (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ợ lược đồ URI tuỳ chỉnh.
Bật lược đồ URI tuỳ chỉnh
Nếu phương án thay thế đề xuất không phù hợp với bạn, bạn có thể bật lượ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 rồi chọn ứng dụng Android của bạn.
  2. Chuyển đến phần Advanced Settings (Cài đặt nâng cao), đánh dấu vào hộp đánh dấu Enable Custom URI Scheme (Bật lược đồ URI tuỳ chỉnh) rồi nhấp vào Save (Lưu) để bật tính năng hỗ trợ lược đồ URI tuỳ chỉnh.
Cách thay thế cho việc sử dụng lược đồ URI tuỳ chỉnh trên ứng dụng Chrome

Sử dụng API Chrome Identity để gửi phản hồi OAuth 2.0 trực tiếp cho ứng dụng của bạn mà 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ơ mạo danh ứng dụng.

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 (nếu có) và ứng dụng của bạn đã được đăng ký trên Google Play Console. Bạn phải đáp ứng các yêu cầu sau đây để xác minh thành công:

  • Bạn phải có một ứng dụng đã đăng ký trong Google Play Console có cùng tên gói và dấu vân tay chứng chỉ ký SHA-1 với ứng dụng OAuth của Android mà bạn đang hoàn tất quy trình xác minh.
  • Bạn phải có quyền Quản trị viên đối với ứng dụng trong Google Play Console. Tìm hiểu thêm về việc 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 trên ứ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 quy trình xác minh thành công, một thông báo sẽ hiển thị để xác nhận rằng quy trình xác minh đã thành công. Nếu không, thông báo lỗi sẽ xuất hiện.

Để khắc phục việc xác minh không thành công, vui lòng thử những cách sau:

  • Đảm bảo ứng dụng bạn đang xác minh là ứng dụng đã đăng ký trong Google Play Console.
  • Đảm bảo bạn có quyền Quản trị viên đố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 trê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ó mã mặt hàng giố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.
  • Bạn phải là nhà xuất bản cho mặt hàng trên Cửa hàng Chrome trực tuyến. Tìm hiểu thêm về việc 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 của 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 sau khi cấp quyền truy cập vào tài khoản của bạn.

Nếu quy trình xác minh thành công, một thông báo sẽ hiển thị để xác nhận rằng quy trình xác minh đã thành công. Nếu không, thông báo lỗi sẽ xuất hiện.

Để khắc phục việc xác minh không thành công, vui lòng thử những cách sau:

  • Đảm bảo rằng 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ó mã mặt hàng giố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ề việc 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, hãy xác minh rằng danh sách thành viên của 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 của nhà xuất bản.

Địa chỉ IP Loopback (macOS, Linux, máy tính chạy Windows)

Để 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ể thực hiện được trên nhiều nền tảng, nhưng không phải tất cả. Tuy nhiên, nếu nền tảng của bạn hỗ trợ mã uỷ quyền đó, thì đây là cơ chế bạn nên dùng để lấy mã uỷ quyền.

Khi ứng dụng của bạn nhận được phản hồi uỷ quyền, để có thể sử dụng tốt nhất, ứng dụng của bạn nên 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.

Mức sử dụng được đề xuất Các ứng dụng dành cho máy tính để bàn macOS, Linux và Windows (nhưng không phải Universal Windows Platform)
Giá trị biểu mẫu Đặt loại ứng dụng thành Ứng dụng 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, đồng thời cho phép người dùng kiểm soát 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ố phạm vi được 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 tính năng 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 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 để có được sự đồng ý của người dùng nhằm 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 phải được 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ợ giao thức Khoá bằng chứng để trao đổi mã (PKCE) để giúp quy trình cài đặt ứng dụng an toàn hơn. Một trình xác minh mã duy nhất sẽ được tạo cho mọi yêu cầu uỷ quyền. Sau đó, giá trị đã chuyển đổi của yêu cầu này (đượ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 bằng mật mã có độ entropy cao sử dụng các ký tự không được đặt trước [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", có độ dài tối thiểu là 43 ký tự và độ dài tối đa là 128 ký tự.

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

Tạo thử thách lập trình

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

Phương thức 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 trình xác minh mã.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
đơn giản Yêu cầu 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

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

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

Thông số
client_id Bắt buộc

Mã ứng dụng khách của ứng dụng. 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ố lựa chọn chuyển hướng dành cho các ứng dụng đã cài đặt và bạn cần thiết lập thông tin đăng nhập uỷ quyền theo phương thức chuyển hướng cụ thể.

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

Bảng dưới đây hiển thị 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 một miền thuộc quyền kiểm soát của bạn. Lược đồ tuỳ chỉnh phải chứa một dấu chấm thì mới có hiệu lực.
  • com.googleusercontent.apps.123 là ký hiệu DNS ngược của mã ứng dụng khách.
  • redirect_uri_path là một 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 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 để biết địa chỉ IP lặp lại có liên quan và khởi động 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 theo dõi.

Xin lưu ý rằng tính năng hỗ trợ tuỳ chọn chuyển hướng địa chỉ IP lặp lại trên ứng dụng dành cho thiết bị di động ĐÃ NGỪNG HOẠT ĐỘNG.

response_type Bắt buộc

Xác định xem điểm cuối của 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

Một danh sách phạm vi được phân tách bằng dấu cách giúp xác định những tài nguyên mà ứng dụng của bạn có thể thay mặt người dùng truy cập. Những giá trị này thông báo cho 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 các tài nguyên mà ứng dụng cần, đồng thời cho phép người dùng kiểm soát 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ố 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ẽ dùng làm thử thách phía máy chủ trong quá trình trao đổi mã uỷ quyền. Hãy xem phần thử thách tạo mã ở 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. Tham số này phải được 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 có chứa 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 mọi giá trị chuỗi 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ủ sẽ trả về giá trị chính xác mà bạn gửi dưới dạng 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 yêu cầu truy cập của ứng dụng.

Bạn có thể sử dụng tham số này cho nhiều mục đích, chẳng hạn như hướng người dùng đến đúng tài nguyên trong ứng dụng, gửi số chỉ dùng một lần và giảm thiểu hành vi giả mạo yêu cầu trên nhiều trang web. Vì có thể đoán được redirect_uri, nên việc sử dụng giá trị state có thể giúp bạn tăng mức độ đảm bảo 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 tạo một chuỗi ngẫu nhiên hoặc mã hoá hàm băm của cookie hoặc một giá trị khác ghi lại trạng thái của ứng dụng, thì 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, giúp chống lại các cuộc tấn công như giả mạo yêu cầu trên nhiều trang web. Hãy xem tài liệu về 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, thì ứ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 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 chọn phiên đăng nhập nhiều tài khoản thích hợp.

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

URL uỷ quyền mẫu

Các thẻ dưới đây 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 giống hệt nhau, ngoại trừ giá trị của tham số redirect_uri. Các URL này cũng chứa các tham số response_typeclient_id bắt buộc cũng như tham số state (không bắt buộc). Mỗi URL đều chứa dấu ngắt dòng và dấu cách để 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 quyết định có cấp cho ứng dụng của bạn quyền truy cập mà họ yêu cầu hay không. Ở giai đoạn này, Google sẽ hiện một cửa sổ đồng ý cho thấy 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 cấp quyền truy cập bằng thông tin xác thực cấp quyền của người dùng và bản tóm tắt về 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 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ì ứng dụng đang chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu có quyền truy cập nào đã được cấp hay không. Câu trả lời đó được giải thích trong bước sau.

Lỗi

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

admin_policy_enforced

Tài khoản Google không thể cấp quyền cho một hoặc nhiều phạm vi theo yêu cầu theo 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 những ứng dụng nội bộ và ứng dụng bên thứ ba nào truy cập vào dữ liệu 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 phạm vi nhạy cảm và bị hạn chế cho đến khi mã ứng dụng khách OAuth của bạn được cấp quyền truy cập rõ ràng.

disallowed_useragent

Điểm cuối uỷ quyền hiển thị bên trong một tác nhân người dùng nhúng không được Chính sách OAuth 2.0 của Google cho phép.

Android

Nhà phát triển Android có thể gặp phải thông báo lỗi này khi mở yêu cầu uỷ quyền trong android.webkit.WebView. Thay vào đó, nhà phát triển nên chuyển sang sử dụng các thư viện Android như Đăng nhập bằng Google cho Android hoặc AppAuth cho Android của OpenSL Foundation.

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 web chung trong một tác nhân người dùng được nhúng và một 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ý đườ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 Thẻ tuỳ chỉnh của Android cũng là một tuỳ chọn được hỗ trợ.

iOS

Nhà phát triển iOS và macOS có thể gặp phải lỗi này khi mở yêu cầu uỷ quyền trong WKWebView. Thay vào đó, nhà phát triển nên sử dụng các thư viện dành cho iOS, chẳng hạn như tính năng Đăng nhập bằng Google dành cho iOS hoặc AppAuth cho iOS của ID mở Foundation.

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 web chung trong một tác nhân người dùng được nhúng và một 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ý đườ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 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 các Tài khoản Google trong một tổ chức cụ thể trên Google Cloud. Để biết thêm thông tin về lựa 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 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 và thử thách mã, thì tham số code_callenge không hợp lệ hoặc bị thiếu. Hãy đảm bảo rằng bạn đã thiết lập chính xác tham số code_challenge.

Khi làm mới mã truy cập, mã thông báo đó có thể đã hết hạn hoặc không hợp lệ. Xác thực lại người dùng và yêu cầu sự đồng ý của người dùng để lấy mã thông báo mới. Nếu bạn tiếp tục thấy lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã được định cấu hình đúng cách và bạn đang sử dụng đúng mã thông báo và thông số trong yêu cầu của mình. Nếu không, tài khoản người dùng có thể đã bị xoá hoặc vô hiệu hoá.

redirect_uri_mismatch

redirect_uri được truyền trong yêu cầu uỷ quyền không khớp với URI chuyển hướng được uỷ quyền cho mã ứng dụng khách OAuth. Xem lại các URI chuyển hướng được uỷ quyền trong Google API Console Credentials page.

redirect_uri được truyền có thể không hợp lệ đối với loại ứng dụng.

Tham số redirect_uri có thể đề cập đến quy trình OAuth ngoài băng tần (OOB) đã ngừng hoạt động và không còn được hỗ trợ. Hãy tham khảo hướng dẫn di chuyển để cập nhật quy trình 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 sử dụng phương thức uỷ quyền mà Google không hỗ trợ. Xác minh rằng bạn đã tích hợp OAuth bằng phương thức tích hợp được đề xuất
  • Lược đồ tuỳ chỉnh đượ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, thì tức là bạn đang dùng một lược đồ URI tuỳ chỉnh không được hỗ trợ trên các ứng dụng Chrome và đã bị tắt theo mặc định trên Android. Tìm hiểu thêm về các phương án thay thế lược đồ URI tuỳ chỉnh

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 uỷ quyền phụ thuộc vào lược đồ URI chuyển hướng mà ứng dụng sử dụng. Bất kể sử dụng lược đồ nào, phản hồi đều sẽ chứa mã uỷ quyền (code) hoặc lỗi (error). Ví dụ: error=access_denied cho biết 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ã uỷ quyền lấy 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à mã thông báo truy cập

Để đổi mã uỷ quyền lấy mã truy cập, hãy gọi đ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 từ API Console Credentials page.
client_secret Mật khẩu ứng dụng khách lấy từ API Console Credentials page.
code Mã uỷ quyền được trả về từ yêu cầu ban đầu.
code_verifier Trình xác minh mã mà bạn đã tạo ở Bước 1.
grant_type Như xác định trong thông số kỹ thuật của OAuth 2.0, 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 của 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=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 để uỷ quyền cho một 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ị này là một Mã thông báo web JSON (JWT) chứa thông tin nhận dạng đã có chữ 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. Lưu ý rằng mã làm mới luôn được trả về cho ứng dụng đã cài đặt.
scope Phạm vi truy cập mà access_token cấp được biểu thị dưới dạng danh sách các chuỗi được phân tách bằng dấu cách và phân biệt chữ hoa chữ thường.
token_type Loại mã thông báo được trả về. Hiện tại, giá trị của trường này luôn được đặt thành Bearer.

Đoạn mã sau đây cho thấy một câu trả lời mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Gọi API của Google

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

Bạn có thể dùng thử tất cả các API của Google và xem phạm vi của các API đó tại Playground 2.0 của OAuth.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối drive.files (API Tệp trên Drive) bằng tiêu đề HTTP Authorization: Bearer có thể có dạng như sau. 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 tới cùng một API cho người dùng đã xác thực bằng cách sử dụng tham số chuỗi truy vấn access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Ví dụ về curl

Bạn có thể kiểm thử các lệnh này bằng ứng dụng dòng lệnh curl. Dưới đây là 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 cách khác là lựa chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Làm mới mã truy cập

Mã thông báo truy cập sẽ hết hạn theo đị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ã 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ã truy cập, ứng dụng của bạn sẽ gửi yêu cầu POST HTTPS đến 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 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 các yêu cầu từ các ứng dụng đã đăng ký dưới dạng ứng dụng Android, iOS hoặc Chrome.)
grant_type Như xác định trong thông số kỹ thuật của 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ã truy cập mới. Đoạn mã sau đây cho thấy một phản hồi mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Xin lưu ý rằng có một 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 ứng dụ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 ứng dụng. Bạn nên lưu mã thông báo làm mới vào bộ nhớ dài hạn và tiếp tục sử dụng các mã này cho đến khi các mã này vẫn hợp lệ. Nếu yêu cầu quá nhiều mã làm mới, thì ứng dụng có thể gặp phải các giới hạn này. Trong trường hợp đó, những 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 ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào phần Cài đặt tài khoản. Hãy xem tài liệu hỗ trợ về Xoá quyền truy cập vào trang web hoặc ứng dụng trong phần Các trang web và ứng dụng của bên thứ ba có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.

Ứng dụng cũng có thể thu hồi quyền truy cập đã cấp cho ứng dụng theo phương thức lập trình. Việc thu hồi có lập trình đóng vai trò quan trọng trong những 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 cả yêu cầu API để đảm bảo các quyền đã cấp trước đó cho ứng dụng sẽ bị xoá.

Để thu hồi một mã thông báo theo phương thức lập trình, ứng dụng sẽ gửi yêu cầu đến https://oauth2.googleapis.com/revoke và đưa mã thông báo đó vào dưới dạng một 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 này có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo này là mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.

Nếu yêu cầu 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, hệ thống sẽ trả về mã trạng thái HTTP 400 cùng với mã lỗi.

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

Phương pháp hay nhất hiện tại của IETF xác định nhiều phương pháp hay nhất được nêu ở đây.