Tài liệu tham khảo về API JavaScript Uỷ quyền tài khoản Google

Tài liệu tham khảo này mô tả API Uỷ quyền Tài khoản Google bằng JavaScript, được dùng để lấy mã uỷ quyền hoặc mã truy cập từ Google.

Phương thức: google.accounts.oauth2.initCodeClient

Phương thức initCodeClient khởi chạy và trả về một ứng dụng khách mã, với các cấu hình trong tham số.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig) 

Loại dữ liệu: CodeClientConfig

Bảng sau đây liệt kê các thuộc tính của kiểu dữ liệu CodeClientConfig.

Thuộc tính
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.
scope Bắt buộc. Một danh sách các phạm vi được phân tách bằng dấu cách, xác định những tài nguyên mà ứng dụng của bạn có thể truy cập thay cho người dùng. Những giá trị này cho biết màn hình đồng ý mà Google hiển thị cho người dùng.
include_granted_scopes Không bắt buộc, mặc định là true. Cho phép các ứng dụng sử dụng tính năng uỷ quyền từng phần để yêu cầu quyền truy cập vào các phạm vi bổ sung theo ngữ cảnh. Nếu bạn đặt giá trị của tham số này thành false và yêu cầu uỷ quyền được cấp, thì mã truy cập mới sẽ chỉ bao gồm mọi phạm vi mà scope đã yêu cầu trong CodeClientConfig này.
redirect_uri Bắt buộc đối với trải nghiệm người dùng chuyển hướng. Xác định vị trí mà máy chủ API chuyển hướng người dùng đến sau khi người dùng hoàn tất quy trình uỷ quyền. 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 và phải tuân thủ các quy tắc xác thực URI chuyển hướng của chúng tôi. Thuộc tính này sẽ bị bỏ qua bởi UX của cửa sổ bật lên.
callback Bắt buộc đối với trải nghiệm người dùng của cửa sổ bật lên. Hàm JavaScript xử lý phản hồi mã đã trả về. Thuộc tính này sẽ bị UX chuyển hướng bỏ qua.
state Không bắt buộc. Nên dùng cho trải nghiệm người dùng chuyển hướng. Chỉ định mọi giá trị chuỗi 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.
enable_granular_consent Không dùng nữa, không có hiệu lực nếu được đặt. Hãy xem các quyền ở cấp độ chi tiết để biết thông tin chi tiết về hành vi đồng ý.
enable_serial_consent Không dùng nữa, không có hiệu lực nếu được đặt. Hãy xem các quyền ở cấp độ chi tiết để biết thông tin chi tiết về hành vi đồng ý.
login_hint Không bắt buộc. Nếu biết người dùng nào sẽ uỷ quyền cho yêu cầu, ứng dụng của bạn có thể dùng thuộc tính này để cung cấp gợi ý đăng nhập cho Google. Nếu thành công, hệ thống sẽ bỏ qua bước chọn tài khoản. Giá trị trường địa chỉ email hoặc mã thông báo nhận dạng sub cho người dùng mục tiêu. Để biết thêm thông tin, hãy xem trường login_hint trong tài liệu OpenID Connect.
hd Không bắt buộc. Nếu ứng dụng của bạn biết miền Workspace mà người dùng thuộc về, hãy sử dụng miền này để cung cấp gợi ý cho Google. Khi thành công, tài khoản người dùng sẽ bị giới hạn hoặc được chọn trước cho miền được cung cấp. Để biết thêm thông tin, hãy xem trường hd trong tài liệu OpenID Connect.
ux_mode Không bắt buộc. Chế độ trải nghiệm người dùng để sử dụng cho quy trình uỷ quyền. Theo mặc định, chế độ này sẽ mở quy trình đồng ý trong một cửa sổ bật lên. Các giá trị hợp lệ là popupredirect.
select_account Không bắt buộc, mặc định là "false". Giá trị Boolean để nhắc người dùng chọn một tài khoản.
error_callback Không bắt buộc. Hàm JavaScript xử lý một số lỗi không phải OAuth, chẳng hạn như không mở được cửa sổ bật lên hoặc đóng trước khi phản hồi OAuth được trả về.

Trường "type" của tham số đầu vào cung cấp lý do chi tiết.
  • popup_failed_to_open Không mở được cửa sổ bật lên.
  • popup_closed Cửa sổ bật lên bị đóng trước khi phản hồi OAuth được trả về.
  • unknown Phần giữ chỗ cho các lỗi khác.

Loại dữ liệu: CodeClient

Lớp này chỉ có một phương thức công khai requestCode, phương thức này sẽ bắt đầu quy trình UX mã OAuth 2.0.

interface CodeClient {   requestCode(): void; } 

Loại dữ liệu: CodeResponse

Một đối tượng CodeResponse JavaScript sẽ được truyền đến phương thức callback của bạn trong UX cửa sổ bật lên. Trong UX chuyển hướng, CodeResponse sẽ được truyền dưới dạng tham số URL.

Bảng sau đây liệt kê các thuộc tính của kiểu dữ liệu CodeResponse.

Thuộc tính
code Mã uỷ quyền của một phản hồi mã thông báo thành công.
scope Danh sách các phạm vi được phân tách bằng dấu cách mà người dùng phê duyệt.
state Giá trị chuỗi 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.
error Một mã lỗi ASCII duy nhất.
error_description Văn bản ASCII mà con người có thể đọc được, cung cấp thông tin bổ sung, dùng để hỗ trợ nhà phát triển ứng dụng hiểu rõ lỗi đã xảy ra.
error_uri Một URI xác định trang web mà con người có thể đọc được, có thông tin về lỗi, được dùng để cung cấp thêm thông tin về lỗi cho nhà phát triển ứng dụng.

Phương thức: google.accounts.oauth2.initTokenClient

Phương thức initTokenClient khởi chạy và trả về một ứng dụng khách mã thông báo, với các cấu hình trong tham số.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig) 

Loại dữ liệu: TokenClientConfig

Bảng sau đây liệt kê các thuộc tính của kiểu dữ liệu TokenClientConfig.

Thuộc tính
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.
callback Bắt buộc. Hàm JavaScript xử lý phản hồi mã thông báo được trả về.
scope Bắt buộc. Một danh sách các phạm vi được phân tách bằng dấu cách, xác định những tài nguyên mà ứng dụng của bạn có thể truy cập thay cho người dùng. Những giá trị này cho biết màn hình đồng ý mà Google hiển thị cho người dùng.
include_granted_scopes Không bắt buộc, mặc định là true. Cho phép các ứng dụng sử dụng tính năng uỷ quyền từng phần để yêu cầu quyền truy cập vào các phạm vi bổ sung theo ngữ cảnh. Nếu bạn đặt giá trị của tham số này thành false và yêu cầu uỷ quyền được cấp, thì mã truy cập mới sẽ chỉ bao gồm mọi phạm vi mà scope đã yêu cầu trong TokenClientConfig này.
prompt Không bắt buộc, mặc định là 'select_account'. Một danh sách phân tách bằng dấu cách, phân biệt chữ hoa chữ thường gồm các câu lệnh để trình bày cho người dùng. Các giá trị có thể là:
  • chuỗi trống Người dùng sẽ chỉ được nhắc vào lần đầu tiên ứng dụng của bạn yêu cầu quyền truy cập. Không thể chỉ định cùng với các giá trị khác.
  • "none" Không hiển thị bất kỳ màn hình xác thực hoặc đồng ý nào. Không được chỉ định cùng với các giá trị khác.
  • "consent" Nhắc người dùng đồng ý.
  • 'select_account' Nhắc người dùng chọn một tài khoản.
enable_granular_consent Không dùng nữa, không có hiệu lực nếu được đặt. Hãy xem các quyền ở cấp độ chi tiết để biết thông tin chi tiết về hành vi đồng ý.
enable_serial_consent Không dùng nữa, không có hiệu lực nếu được đặt. Hãy xem các quyền ở cấp độ chi tiết để biết thông tin chi tiết về hành vi đồng ý.
login_hint Không bắt buộc. Nếu biết người dùng nào sẽ uỷ quyền cho yêu cầu, ứng dụng của bạn có thể dùng thuộc tính này để cung cấp gợi ý đăng nhập cho Google. Nếu thành công, hệ thống sẽ bỏ qua bước chọn tài khoản. Giá trị trường địa chỉ email hoặc mã thông báo nhận dạng sub cho người dùng mục tiêu. Để biết thêm thông tin, hãy xem trường login_hint trong tài liệu OpenID Connect.
hd Không bắt buộc. Nếu ứng dụng của bạn biết miền Workspace mà người dùng thuộc về, hãy sử dụng miền này để cung cấp gợi ý cho Google. Khi thành công, tài khoản người dùng sẽ bị giới hạn hoặc được chọn trước cho miền được cung cấp. Để biết thêm thông tin, hãy xem trường hd trong tài liệu OpenID Connect.
state Không bắt buộc. Không nên. Chỉ định mọi giá trị chuỗi 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.
error_callback Không bắt buộc. Hàm JavaScript xử lý một số lỗi không phải OAuth, chẳng hạn như không mở được cửa sổ bật lên hoặc đóng trước khi phản hồi OAuth được trả về.

Trường "type" của tham số đầu vào cung cấp lý do chi tiết.
  • popup_failed_to_open Không mở được cửa sổ bật lên.
  • popup_closed Cửa sổ bật lên bị đóng trước khi phản hồi OAuth được trả về.
  • unknown Phần giữ chỗ cho các lỗi khác.

Loại dữ liệu: TokenClient

Lớp này chỉ có một phương thức công khai requestAccessToken, bắt đầu quy trình UX mã thông báo OAuth 2.0.

interface TokenClient {   requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void; } 
Đối số
overrideConfig OverridableTokenClientConfig Không bắt buộc. Các cấu hình sẽ bị ghi đè trong phương thức này.

Loại dữ liệu: OverridableTokenClientConfig

Bảng sau đây liệt kê các thuộc tính của kiểu dữ liệu OverridableTokenClientConfig.

Thuộc tính
scope Không bắt buộc. Một danh sách các phạm vi được phân tách bằng dấu cách, xác định những tài nguyên mà ứng dụng của bạn có thể truy cập thay cho người dùng. Những giá trị này thông báo cho màn hình đồng ý mà Google hiển thị cho người dùng.
include_granted_scopes Không bắt buộc, mặc định là true. Cho phép các ứng dụng sử dụng tính năng uỷ quyền từng phần để yêu cầu quyền truy cập vào các phạm vi bổ sung theo ngữ cảnh. Nếu bạn đặt giá trị của tham số này thành false và yêu cầu uỷ quyền được cấp, thì mã truy cập mới sẽ chỉ bao gồm mọi phạm vi mà scope đã yêu cầu trong OverridableTokenClientConfig này.
prompt Không bắt buộc. Một danh sách phân tách bằng dấu cách, phân biệt chữ hoa chữ thường gồm các câu lệnh để trình bày cho người dùng.
enable_granular_consent Không dùng nữa, không có hiệu lực nếu được đặt. Hãy xem các quyền ở cấp độ chi tiết để biết thông tin chi tiết về hành vi đồng ý.
enable_serial_consent Không dùng nữa, không có hiệu lực nếu được đặt. Hãy xem các quyền ở cấp độ chi tiết để biết thông tin chi tiết về hành vi đồng ý.
login_hint Không bắt buộc. Nếu biết người dùng nào sẽ uỷ quyền cho yêu cầu, ứng dụng của bạn có thể dùng thuộc tính này để cung cấp gợi ý đăng nhập cho Google. Nếu thành công, hệ thống sẽ bỏ qua bước chọn tài khoản. Giá trị trường địa chỉ email hoặc mã thông báo nhận dạng sub cho người dùng mục tiêu. Để biết thêm thông tin, hãy xem trường login_hint trong tài liệu OpenID Connect.
state Không bắt buộc. Không nên. Chỉ định mọi giá trị chuỗi 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.

Loại dữ liệu: TokenResponse

Một đối tượng TokenResponse JavaScript sẽ được truyền đến phương thức gọi lại của bạn trong UX cửa sổ bật lên.

Bảng sau đây liệt kê các thuộc tính của kiểu dữ liệu TokenResponse.

Thuộc tính
access_token Mã thông báo truy cập của một phản hồi mã thông báo thành công.
expires_in Thời gian tồn tại của mã truy cập tính bằng giây.
hd Miền được lưu trữ mà người dùng đã đăng nhập thuộc về.
prompt Giá trị lời nhắc được dùng trong danh sách các giá trị có thể do TokenClientConfig hoặc OverridableTokenClientConfig chỉ định.
token_type Loại mã thông báo được phát hành.
scope Danh sách các phạm vi được phân tách bằng dấu cách mà người dùng phê duyệt.
state Giá trị chuỗi 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.
error Một mã lỗi ASCII duy nhất.
error_description Văn bản ASCII mà con người có thể đọc được, cung cấp thông tin bổ sung, dùng để hỗ trợ nhà phát triển ứng dụng hiểu rõ lỗi đã xảy ra.
error_uri Một URI xác định trang web mà con người có thể đọc được, có thông tin về lỗi, được dùng để cung cấp thêm thông tin về lỗi cho nhà phát triển ứng dụng.

Phương thức: google.accounts.oauth2.hasGrantedAllScopes

Kiểm tra xem người dùng đã cấp tất cả các phạm vi được chỉ định hay chưa.

google.accounts.oauth2.hasGrantedAllScopes(                                             tokenResponse: TokenResponse,                                             firstScope: string, ...restScopes: string[]                                           ): boolean; 
Đối số
tokenResponse TokenResponse Bắt buộc. Một đối tượng TokenResponse.
firstScope chuỗi Bắt buộc. Phạm vi cần kiểm tra.
restScopes string[] Không bắt buộc. Các phạm vi khác cần kiểm tra.
Giá trị trả về
boolean True nếu tất cả các phạm vi đều được cấp.

Phương thức: google.accounts.oauth2.hasGrantedAnyScope

Kiểm tra xem người dùng có cấp bất kỳ phạm vi nào được chỉ định hay không.

google.accounts.oauth2.hasGrantedAnyScope(                                            tokenResponse: TokenResponse,                                            firstScope: string, ...restScopes: string[]                                          ): boolean; 
Đối số
tokenResponse TokenResponse Bắt buộc. Một đối tượng TokenResponse.
firstScope chuỗi Bắt buộc. Phạm vi cần kiểm tra.
restScopes string[] Không bắt buộc. Các phạm vi khác cần kiểm tra.
Giá trị trả về
boolean True nếu bất kỳ phạm vi nào được cấp.

Phương thức: google.accounts.oauth2.revoke

Phương thức revoke sẽ thu hồi tất cả các phạm vi mà người dùng đã cấp cho ứng dụng. Bạn cần có mã thông báo truy cập hợp lệ để thu hồi quyền.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void; 
Đối số
accessToken chuỗi Bắt buộc. Mã truy cập hợp lệ.
callback hàm Không bắt buộc. Trình xử lý RevocationResponse.

Loại dữ liệu: RevocationResponse

Một đối tượng RevocationResponse JavaScript sẽ được truyền đến phương thức gọi lại của bạn.

Bảng sau đây liệt kê các thuộc tính của kiểu dữ liệu RevocationResponse.

Thuộc tính
successful Boolean. true khi thành công, false khi không thành công.
error Chuỗi. Không xác định khi thành công. Một mã lỗi ASCII duy nhất. Điều này bao gồm nhưng không giới hạn ở mã lỗi OAuth 2.0 tiêu chuẩn. Các lỗi thường gặp đối với phương thức revoke:
  • invalid_token – Mã thông báo đã hết hạn hoặc bị thu hồi trước khi phương thức revoke được gọi. Trong hầu hết các trường hợp, bạn có thể coi khoản cấp quyền liên kết với accessToken là đã bị thu hồi.
  • invalid_request – Không thể thu hồi mã thông báo. Bạn nên đảm bảo rằng accessToken là thông tin xác thực hợp lệ của Google OAuth 2.0.
error_description Chuỗi. Không xác định khi thành công. Văn bản ASCII mà con người có thể đọc được cung cấp thêm thông tin về thuộc tính error. Nhà phát triển có thể sử dụng thông tin này để hiểu rõ hơn về lỗi đã xảy ra. Chuỗi error_description chỉ có bằng tiếng Anh. Đối với các lỗi thường gặp được liệt kê trong error, hãy xem error_description tương ứng:
  • invalid_token – Mã thông báo đã hết hạn hoặc bị thu hồi.
  • invalid_request – Không thể thu hồi mã thông báo.