Account Linking API

Trang tham chiếu này ghi lại các điểm cuối API mà dịch vụ của bạn phải triển khai để hỗ trợ tính năng Liên kết tài khoản với Google. Trong đó có Liên kết tài khoản dựa trên OAuth, Liên kết tài khoản đơn giản và Chuyển đổi ứng dụng.

Điều kiện tiên quyết và tiêu chuẩn

Để triển khai thành công các điểm cuối này, dịch vụ của bạn phải tuân thủ các tiêu chuẩn sau:

  • OAuth 2.0: Tuân thủ RFC 6749.
  • Thu hồi mã thông báo: Tuân thủ RFC 7009.
  • Mã thông báo web JSON (JWT): Tuân thủ RFC 7519 (bắt buộc đối với tính năng Liên kết tinh giản).
  • HTTPS: Tất cả các điểm cuối phải được phân phát qua một kết nối HTTPS bảo mật.

Điểm cuối uỷ quyền

Điểm cuối uỷ quyền chịu trách nhiệm xác thực người dùng và nhận được sự đồng ý của họ để liên kết tài khoản với Google.

  • URL: Được định cấu hình trong Bảng điều khiển Actions hoặc bảng điều khiền Cloud.
  • Phương thức: GET

Tham số yêu cầu

Thông số Mô tả
client_id Mã ứng dụng khách mà bạn đã chỉ định cho Google.
redirect_uri URL mà bạn gửi phản hồi cho yêu cầu này.
state Giá trị kế toán được truyền trở lại Google mà không thay đổi trong URI chuyển hướng.
response_type Phải là code đối với quy trình sử dụng mã uỷ quyền.
scope (Không bắt buộc) Danh sách các phạm vi được phân tách bằng dấu cách cho dữ liệu mà Google đang yêu cầu.
user_locale (Không bắt buộc) Chế độ cài đặt ngôn ngữ của Tài khoản Google, được chỉ định bằng thẻ ngôn ngữ BCP-47 (ví dụ: en-US).

Điểm cuối trao đổi mã thông báo

Điểm cuối này chịu trách nhiệm trao đổi mã uỷ quyền để lấy mã thông báo và làm mới mã truy cập đã hết hạn.

  • URL: Được định cấu hình trong Bảng điều khiển Actions hoặc bảng điều khiền Cloud.
  • Phương thức: POST
  • Content-Type: application/x-www-form-urlencoded

Đổi mã uỷ quyền lấy mã thông báo

Các tham số sau đây được dùng trong yêu cầu trao đổi mã thông báo ban đầu.

Tham số yêu cầu

Thông số Mô tả
client_id Mã ứng dụng khách mà bạn đã chỉ định cho Google.
client_secret Khoá bí mật của ứng dụng khách mà bạn đã chỉ định cho Google.
grant_type Phải là authorization_code.
code Mã uỷ quyền nhận được từ điểm cuối uỷ quyền.
redirect_uri Cùng một URI chuyển hướng được dùng trong yêu cầu ban đầu.

Trao đổi mã làm mới để lấy mã truy cập

Các tham số sau đây được dùng khi làm mới mã truy cập.

Tham số yêu cầu

Thông số Mô tả
client_id Mã ứng dụng khách mà bạn đã chỉ định cho Google.
client_secret Khoá bí mật của ứng dụng khách mà bạn đã chỉ định cho Google.
grant_type Phải là refresh_token.
refresh_token Mã làm mới đã được cấp cho Google trước đó.

Phản hồi (JSON)

Trả về một phản hồi thành công bằng một đối tượng JSON trong nội dung của phản hồi HTTPS.

  • Trạng thái HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
Trường Mô tả
token_type Bắt buộc. Phải là bearer.
access_token Bắt buộc. Mã thông báo ngắn hạn dùng để truy cập vào các API của dịch vụ.
refresh_token Bắt buộc đối với authorization_code grant_type. Mã thông báo có thời hạn sử dụng lâu dài, dùng để lấy mã thông báo truy cập mới.
expires_in Bắt buộc. Thời gian tồn tại còn lại của mã truy cập tính bằng giây.

Phản hồi lỗi

Nếu yêu cầu đến điểm cuối của mã thông báo không thành công, hãy trả về lỗi HTTP 400 Yêu cầu không hợp lệ cùng với một phản hồi JSON chứa các trường sau:

  • Trạng thái HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
Trường lỗi (JSON) Mô tả
error Bắt buộc. Phải là invalid_grant.
error_description (Không bắt buộc) Văn bản mà con người có thể đọc để cung cấp thêm thông tin.

Xử lý ý định liên kết đơn giản

Nếu dịch vụ của bạn hỗ trợ tính năng Liên kết tài khoản đơn giản (OAuth có tính năng Đăng nhập bằng Google), thì điểm cuối trao đổi mã thông báo của bạn cũng phải hỗ trợ các câu khẳng định Mã thông báo web JSON (JWT) và triển khai các ý định check, create và get.

Các tham số sau đây được dùng trong những yêu cầu này:

Tham số yêu cầu

Thông số Mô tả
intent Ý định liên kết tinh giản cụ thể đang được yêu cầu: check, get hoặc create.
grant_type Đối với những yêu cầu này, tham số này luôn có giá trị urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Mã thông báo Web JSON (JWT) cung cấp một câu khẳng định đã ký về danh tính của người dùng Google. JWT chứa thông tin bao gồm mã nhận dạng Tài khoản Google, tên và địa chỉ email của người dùng.

Máy chủ của bạn phải xác thực JWT này bằng các tiêu chí được nêu trong phần Xác thực JWT.
client_id Mã ứng dụng khách mà bạn đã chỉ định cho Google.
client_secret Khoá bí mật của ứng dụng khách mà bạn đã chỉ định cho Google.
scope Không bắt buộc: Mọi phạm vi mà bạn đã định cấu hình để Google yêu cầu người dùng cung cấp. Thường xuất hiện trong các ý định get và create.
response_type Bắt buộc đối với ý định create: Phải được đặt thành token.

Xác thực JWT

Để đảm bảo tính bảo mật của quy trình liên kết tinh giản, máy chủ của bạn phải xác thực assertion (JWT) theo các tiêu chí sau:

  • Chữ ký: Xác minh chữ ký dựa trên khoá công khai của Google (có tại điểm cuối JWK của Google).
  • Nhà phát hành (iss): Phải là https://accounts.google.com.
  • Đối tượng (aud): Phải khớp với mã ứng dụng khách Google API được chỉ định cho hoạt động tích hợp của bạn.
  • Ngày hết hạn (exp): Phải là ngày trong tương lai.

Câu trả lời cho ý định check

Yêu cầu có intent=check sẽ xác minh xem Tài khoản Google (được xác định bằng giá trị khai báo sub hoặc email trong câu khẳng định JWT đã giải mã) có tồn tại trong cơ sở dữ liệu người dùng của bạn hay không.

  • Trạng thái HTTP: 200 OK (Tìm thấy tài khoản) hoặc 404 Not Found (Không tìm thấy tài khoản)
  • Content-Type: application/json;charset=UTF-8
Trường Mô tả
account_found Bắt buộc. true nếu tài khoản tồn tại, false nếu không.

Câu trả lời cho ý định get

Yêu cầu có intent=get yêu cầu mã truy cập cho một Tài khoản Google hiện có.

  • Trạng thái HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Đối tượng JSON phản hồi thành công có cấu trúc giống hệt như một phản hồi Trao đổi mã thông báo tiêu chuẩn thành công (trả về access_token, refresh_token, v.v.).

Nếu không liên kết được tài khoản, hệ thống sẽ trả về lỗi HTTP 401.

  • Trạng thái HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Trường lỗi (JSON) Mô tả
error Bắt buộc. Phải là linking_error.
login_hint (Không bắt buộc) Địa chỉ email của người dùng để truyền đến quy trình liên kết OAuth dự phòng.

Câu trả lời cho ý định create

Yêu cầu có intent=create yêu cầu tạo một tài khoản người dùng mới bằng thông tin được cung cấp trong JWT.

  • Trạng thái HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Đối tượng JSON phản hồi thành công có cấu trúc giống hệt như một phản hồi Trao đổi mã thông báo tiêu chuẩn thành công (trả về access_token, refresh_token, v.v.).

Nếu người dùng đã tồn tại, thì lỗi HTTP 401 sẽ được trả về để nhắc người dùng liên kết tài khoản hiện có của họ.

  • Trạng thái HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Trường lỗi (JSON) Mô tả
error Bắt buộc. Phải là linking_error.
login_hint Địa chỉ email của người dùng để truyền đến quy trình liên kết OAuth dự phòng.

Điểm cuối UserInfo (Không bắt buộc)

Được dùng để truy xuất thông tin cơ bản về hồ sơ của người dùng được liên kết, như được chỉ định trong quy cách OpenID Connect Core 1.0. Đây là yêu cầu bắt buộc đối với các tính năng như "Liên kết tinh giản" hoặc "Đăng nhập bằng một lần chạm".

  • Phương thức: GET
  • Xác thực: Authorization: Bearer ACCESS_TOKEN

Phản hồi (JSON)

Trả về một phản hồi thành công bằng một đối tượng JSON trong nội dung của phản hồi HTTPS.

  • Trạng thái HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Trường phản hồi

Trường Mô tả
sub Bắt buộc. Một mã nhận dạng riêng biệt giúp xác định người dùng trong hệ thống của bạn.
email Bắt buộc. Địa chỉ email của người dùng.
email_verified Bắt buộc. Một giá trị boolean cho biết địa chỉ email đã được xác minh hay chưa.
given_name (Không bắt buộc) Tên của người dùng.
family_name (Không bắt buộc) Họ của người dùng.
name (Không bắt buộc) Họ và tên của người dùng.
picture (Không bắt buộc) URL đến ảnh hồ sơ của người dùng.

Phản hồi lỗi

Nếu mã truy cập không hợp lệ hoặc đã hết hạn, hãy trả về lỗi HTTP 401 Unauthorized. Bạn cũng nên thêm tiêu đề phản hồi WWW-Authenticate.

Mọi phản hồi không thành công (4xx hoặc 5xx) được trả về trong quá trình liên kết đều được coi là không thể khôi phục. Trong những trường hợp này, Google sẽ loại bỏ mọi mã thông báo đã truy xuất và người dùng phải bắt đầu lại quy trình liên kết tài khoản.

Điểm cuối thu hồi mã thông báo (Không bắt buộc)

Cho phép Google thông báo cho dịch vụ của bạn khi người dùng huỷ liên kết tài khoản của họ với nền tảng của Google. Điểm cuối này phải đáp ứng các yêu cầu được mô tả trong RFC 7009.

  • Phương thức: POST
  • Content-Type: application/x-www-form-urlencoded

Tham số yêu cầu

Thông số Mô tả
client_id Một chuỗi xác định nguồn gốc của yêu cầu là Google. Chuỗi này phải được đăng ký trong hệ thống của bạn dưới dạng giá trị nhận dạng riêng biệt của Google.
client_secret Một chuỗi bí mật mà bạn đăng ký với Google cho dịch vụ của mình.
token Mã thông báo cần thu hồi.
token_type_hint (Không bắt buộc) Gợi ý về loại mã thông báo đang bị thu hồi, có thể là access_token hoặc refresh_token. Nếu bạn không chỉ định, giá trị mặc định sẽ là access_token.

Phản hồi

Trả về một phản hồi thành công khi mã thông báo bị xoá thành công hoặc nếu mã thông báo đã không hợp lệ.

  • Trạng thái HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Phản hồi lỗi

Nếu không thể xoá mã thông báo vì bất kỳ lý do nào (ví dụ: cơ sở dữ liệu không hoạt động), hãy trả về lỗi HTTP 503. Google sẽ thử lại yêu cầu sau hoặc theo chỉ dẫn của tiêu đề Retry-After.

  • Trạng thái HTTP: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • Tiêu đề: Retry-After: <HTTP-date / delay-seconds>