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

. Bạn mới có 2

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 để uỷ 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 ứng dụng trong khi vẫn đảm bảo sự riêng tư cho tên người dùng, mật khẩu và các thông tin khác. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để xin 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à được 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 các API của Google khi người dùng đang sử dụng ứ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 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 dành cho thiết bị 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 cho người dùng, đồng thời các thư viện này có thể dễ triển khai hơn 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 nhập 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 của bạ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 mà bạn muốn bật không xuất hiện trong danh sách, hãy sử dụng chức 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 xác thực uỷ quyền

Mọi ứng dụng dùng OAuth 2.0 để truy cập vào API của Google đều phải có thông tin xác thực uỷ quyền giúp 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 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 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. Các phần dưới đây mô tả các loại ứng dụng và phương thức chuyển hướng mà máy chủ 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 khách OAuth và đặt 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 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 của ứng dụng Android. 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 mà con người có thể đọc được. Sao chép giá trị SHA1 trong phần Certificate fingerprints của đầu ra keytool. Xem phần Xác thực ứng dụng của bạn trong tài liệu về API 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.
  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 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 trong ngăn Chung hoặc ngăn Ký và khả 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 trên App Store của Apple. Mã cửa hàng là một chuỗi dạng 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 (Nền tảng Windows chung).
  2. Nhập tên cho ứng dụng OAuth. Tên này 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 trên Microsoft gồm 12 ký tự của ứng dụng. Bạn có thể tìm thấy giá trị này trong Trung tâm đối tác của Microsoft trên trang Danh tính ứng dụng trong phần Quản lý ứng dụng.
  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 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 mà không cần URI chuyển hướng.

Cách di 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, 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 tính năng Đăng nhập bằng Google được đề xuất cho SDK Android:

  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ợ 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 sử dụng tính năng Đă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 bạn sử dụng lược đồ tuỳ chỉnh, yêu cầu 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ì bạn có thể 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 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 mã truy cập và làm mới.
      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ợ lược đồ tuỳ chỉnh trong Google API Console:
    1. Chuyển đến danh sách Thông tin xác thực OAuth 2.0 rồi chọn ứng dụng Android của bạn.
    2. Chuyển đến phần Cài đặt nâng cao, bỏ đánh dấu hộp đánh dấu Bật lược đồ URI tuỳ chỉnh rồi nhấp vào 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ế được đề 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 dưới đây:
  1. Chuyển đến danh sách Thông tin xác thực OAuth 2.0 rồi chọn ứng dụng Android của bạn.
  2. Chuyển đến phần Cài đặt nâng cao, đánh dấu vào hộp đánh dấu Bật lược đồ URI tuỳ chỉnh rồi nhấp vào Lưu để bật tính năng hỗ trợ lược đồ URI tuỳ chỉnh.
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. API này cung cấp 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 thì việc xác minh thành công:

  • Trong Google Play Console, bạn phải đăng ký một ứng dụng có cùng tên gói và vân tay số của 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ề tính năng 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 quy trình xác minh thành công, bạn sẽ thấy một thông báo để xác nhận quy trình xác minh thành công. Nếu không, một thông 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 rằng ứng dụng mà 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. Việc xác minh thành công phải đáp ứng các yêu cầu sau:

  • Bạn phải có một mục đã đă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ục 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 của mặt hàng trên Cửa hàng Chrome trực tuyến. Tìm hiểu thêm về 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 trước khi 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, bạn sẽ thấy một thông báo để xác nhận quy trình xác minh thành công. Nếu không, một thông 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ục đã đă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ục 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 của mình, 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 Windows)

Để nhận được mã uỷ quyền bằng URL này, ứng dụng của bạn phải theo dõi trên máy chủ web cục bộ. Điều này có thể xảy ra trên nhiều nền tảng, nhưng không phải tất cả. Tuy nhiên, nếu nền tảng của bạn có hỗ trợ mã này, thì đây là cơ chế 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, để đảm bảo khả năng hữu dụng tối đa, ứ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ách sử dụng đề 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 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 những 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ố lượng 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 những phạm vi mà ứng dụng 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ể dùng để truy cập vào các API của Google.

Nhận 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 để 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ó được sự đồng ý đó thì mới có thể thực thi yêu cầu API của Google cần có 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 mã

Google hỗ trợ giao thức Khoá bằng chứng để Trao đổi mã (PKCE) để giúp quy trình ứng dụng được cài đặt an toàn hơn. Mỗi yêu cầu uỷ quyền sẽ được tạo một trình xác minh mã riêng và giá trị chuyển đổi của yêu cầu này có tên là "code_Challenge" (thách thức mã) 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 sử dụng các ký tự không dành riêng [A-Z] / [a-z] / [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 để khiến việc đoán giá trị không thực tế.

Tạo thử thách mã

Hỗ trợ hai phương thức tạo thử thách mã.

Phương pháp tạo thử thách mã
S256 (nên dùng) Yêu cầu đối với 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ã đã 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 được sự cho phép của người dùng, hãy gửi yêu cầu tới 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à lấy sự đồng ý của người dùng. Điểm cuối chỉ có thể truy cập được qua SSL và từ chối các 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 đâ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 Credentials page API Console.

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ó nhiều tuỳ chọn chuyển hướng dành cho các ứng dụng đã cài đặt và bạn nên thiết lập thông tin xác thực uỷ quyền theo một 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 cho thấ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 thuộc quyền kiểm soát của bạn. Lượ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à một thành phần đường dẫn không bắt buộc, chẳng hạn như /oauth2redirect. Hãy lưu ý rằng đường dẫn phải bắt đầu bằng một dấu gạch chéo. Điều này khác với các URL HTTP thông thường.
Địa chỉ IP Loopback 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à bắt đầu trình nghe HTTP trên một cổng có sẵn ngẫu nhiên. Thay thế port bằng số cổng thực tế mà ứng dụng của bạn nghe.

Xin lưu ý rằng chế độ hỗ trợ cho tuỳ chọn chuyển hướng địa chỉ IP lặp lại trên ứng dụng di độ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

Danh sách các 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 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 những 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ố 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 Recommended (Nên dùng)

Chỉ định một code_verifier mã hoá sẽ dùng làm yêu cầu xác thực 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 sử dụng trong quá trình trao đổi mã uỷ quyền. Tham số này phải được sử dụng cù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 chứa code_challenge. 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 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ề đúng giá trị 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 thông số này cho một số mục đích, chẳng hạn như chuyển hướng người dùng đến đúng tài nguyên trong ứng dụng, gửi nonces và giảm thiểu hành vi giả mạo yêu cầu trên nhiều trang web. Vì redirect_uri có thể đoán được, nên việc sử dụng giá trị state có thể giúp bạn đảm bảo hơn rằng kết nối đến là kết quả của 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 một cookie hay một giá trị khác ghi lại trạng thái của ứng dụ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, giúp bảo vệ 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 Optional (Không bắt buộc)

Nếu biết người dùng nào đang cố gắng xác thực, thì ứng dụng của bạn 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ẽ 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 lầ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ươ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 các dấu ngắt dòng và khoảng trắng để bạn 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 ý

Trong bước này, người dùng quyết định có cấp cho ứng dụng của bạn quyền truy cập đã yêu cầu hay không. Ở giai đoạn này, Google sẽ hiện một cửa sổ đồng ý cho biết tên ứng dụng của bạn và các dịch vụ API của Google mà ứng dụng đang yêu cầu quyền truy cập bằng thông tin xác thực uỷ quyền của người dùng, kèm theo thông tin tóm tắt về phạm vi quyền truy cập cần đượ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. Phản hồ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 luồng xác thực và uỷ quyền như dự kiến. Bạn có thể xem mã lỗi phổ biến và cách giải quyết được đề xuất dưới đây.

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 được yêu cầu do chính sách của quản trị viên Google Workspace của tài khoản đó. 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 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 phạm vi nhạy cảm và bị hạn chế cho đến khi được cấp rõ ràng quyền truy cập cho mã ứng dụng khách OAuth của bạn.

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 được nhúng theo Chính sách về OAuth 2.0 của Google không cho phép.

Android

Nhà phát triển Android có thể nhìn thấy thông báo lỗi này khi mở yêu cầu uỷ quyền trong android.webkit.WebView. Thay vào đó, các nhà phát triển nên sử dụng các thư viện Android như Đăng nhập bằng Google cho Android hoặc AppAuth cho Android của OpenID 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, sau đó 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. Bạn cũng có thể sử dụng thư viện Thẻ tuỳ chỉnh của Android.

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 như Đăng nhập bằng Google cho iOS hoặc AppAuth cho iOS của OpenID Foundation.

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ở một đường liên kết web chung trong một tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối 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 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ề tuỳ 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à xác thực mã, thì tham số code_callenge sẽ không hợp lệ hoặc bị thiếu. Hãy đảm bảo rằng bạn đã đặt tham số code_challenge đúng cách.

Khi làm mới mã truy cập, mã thông báo đó có thể đã hết hạn hoặc không còn hợp lệ. 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 vẫn gặp 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 cũng như 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 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.

Tham số redirect_uri có thể tham chiếu đến luồng OAuth ngoài băng tần (OOB) vốn không còn được dùng nữa và không còn được hỗ trợ. Hãy tham khảo hướng dẫn di chuyển để cập nhật quá trình tích hợp của bạn.

invalid_request

Đã xảy ra lỗi với yêu cầu bạn đưa ra. Điều này có thể là do một số lý do:

  • Yêu cầu có định dạng không đúng
  • Yêu cầu thiếu thông số bắt buộc
  • Yêu cầu sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. Xác minh rằng hoạt động tích hợp OAuth của bạn có sử dụng phương thức tích hợp đề 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ì có nghĩa là bạn đang sử dụng lược đồ 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ề các phương án thay thế cho 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ể lược đồ nào, 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 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ấy mã làm mới và mã 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à thiết lập các tham số sau:

Các 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 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:

Các trường
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ã truy cập tính bằng giây.
id_token Lưu ý: Hệ thống chỉ trả về thuộc tính này nếu yêu cầu của bạn bao gồm một 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ố của 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 sẽ có hiệu lực cho đến khi người dùng thu hồi quyền truy cập. Lưu ý rằng mã thông báo 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 do access_token cấp được biểu thị dưới dạng danh sách các chuỗi được phân tách bằng dấu cách và phân biệt chữ hoa chữ thường.
token_type Loại mã thông báo được trả về. 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 các 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 để thay mặt một tài khoản người dùng cụ thể thực hiện lệnh gọi đến API của Google 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 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 xuất hiện 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 API Google (chẳng hạn như khi gọi API Tệp 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 API OAuth 2.0.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối drive.files (API Drive Files) bằng tiêu đề HTTP Authorization: Bearer có thể có dạng như sau. Xin lưu ý rằng bạn cần chỉ định mã truy cập của riêng mình:

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

Dưới đây là một 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 lựa chọn 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ã 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 (bao gồm 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 một yêu cầu HTTPS POST đến máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token). Yêu cầu này bao gồm các tham số sau:

Các 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 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 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ề đố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ó 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 trong bộ nhớ dài hạn và tiếp tục sử dụng các mã này cho đến khi 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ì ứng dụng có thể gặp phải các giới hạn này. Trong trường hợp đó, 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 phần Cài đặt tài khoản. Hãy xem phần Xoá quyền truy cập của trang web hoặc ứng dụng trong tài liệu hỗ trợ về 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 rất quan trọng trong những trường hợp người dùng huỷ đăng ký, xoá ứng dụng hoặc cá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ã thông báo theo phương thức lập trình, ứng dụng sẽ gửi yêu cầu tới https://oauth2.googleapis.com/revoke và đưa mã thông báo và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 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 quy trình thu hồi được xử lý thành công, thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, mã trạng thái HTTP 400 sẽ được trả về cùng với mã lỗi.

Đọc thêm

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 tại đây.