Thư viện JavaScript cấp quyền của Google dành cho trang web – Tài liệu tham khảo API

Tài liệu tham khảo này mô tả API Thư viện JavaScript Uỷ quyền bên thứ ba của Google, mà bạn có thể dùng để tải 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 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 Bảng điều khiển API.
scope Bắt buộc. Danh sách phạm vi, phân tách bằng dấu cách giúp xác định các tài nguyên mà ứng dụng của bạn có thể truy cập thay mặt người dùng. Các giá trị này cho người dùng biết màn hình xin phép mà Google sẽ hiển thị cho người dùng.
include_granted_scopes Không bắt buộc, giá trị mặc định là true. Cho phép các ứng dụng sử dụng chế độ gia tăng uỷ quyền để yêu cầu quyền truy cập vào 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, sau đó 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 để chuyển hướng đến trải nghiệm người dùng. Xác định nơi máy chủ API chuyển hướng người dùng 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 Bảng điều khiển API, đồng thời phải tuân thủ Quy tắc xác thực URI chuyển hướng của chúng tôi. Trải nghiệm người dùng bật lên sẽ bỏ qua thuộc tính này.
callback Bắt buộc đối với trải nghiệm người dùng cửa sổ bật lên. Hàm JavaScript xử lý phản hồi mã được trả về. Trải nghiệm người dùng chuyển hướng sẽ bỏ qua thuộc tính này.
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 bất kỳ giá trị chuỗi nào mà ứng dụng của bạn sử dụng để duy trì trạng thái giữa yêu cầu uỷ quyền của bạn và phản hồi của máy chủ uỷ quyền.
enable_granular_consent Không bắt buộc, giá trị mặc định là true. Nếu đặt chính sách này thành false, các quyền chi tiết hơn đối với Tài khoản Google sẽ bị vô hiệu hoá đối với các mã ứng dụng OAuth được tạo trước năm 2019. Nếu bạn đặt cả enable_granular_consentenable_serial_consent thì chỉ có enable_granular_consent sẽ có hiệu lực và giá trị enable_serial_consent sẽ bị bỏ qua.

Các mã ứng dụng OAuth mới hơn sẽ không bị ảnh hưởng vì luôn bật các quyền chi tiết hơn cho các mã ứng dụng này.
enable_serial_consent Không dùng nữa, bạn nên sử dụng enable_granular_consent. Chiến dịch này có tác dụng tương tự như enable_granular_consent. Ứng dụng hiện có sử dụng enable_serial_consent có thể tiếp tục làm như vậy, nhưng bạn nên cập nhật mã của bạn để sử dụng enable_granular_consent trong bản cập nhật ứng dụng tiếp theo.
login_hint Không bắt buộc. Nếu biết người dùng nào nên cho phép yêu cầu này, ứng dụng của bạn có thể sử dụng thuộc tính này để cung cấp gợi ý đăng nhập cho Google. Khi thành công, lựa chọn tài khoản sẽ được bỏ qua. Giá trị trường sub cho địa chỉ email hoặc mã thông báo nhận dạng 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 về OpenID Connect.
hd Không bắt buộc. Nếu ứng dụng của bạn biết người dùng thuộc miền Workspace nào, hãy sử dụng thông tin 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 sẵn cho miền đã cung cấp. Để biết thêm thông tin, hãy xem trường hd trong tài liệu về 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, thao tác này sẽ mở quy trình đồng ý trong cửa sổ bật lên. Các giá trị hợp lệ là popupredirect.
select_account Không bắt buộc, giá trị 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 bị trả lại.

Trường "type" của tham số đầu vào sẽ cho biết 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 OAuth được trả về.
  • Phần giữ chỗ không xác định 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 bắt đầu OAuth 2.0) Quy trình trải nghiệm người dùng mã.

interface CodeClient {
  requestCode(): void;
}

Loại dữ liệu: CodeResponse

Đối tượng JavaScript CodeResponse sẽ được truyền vào phương thức callback của bạn trong trải nghiệm người dùng bật lên. Trong trải nghiệm người dùng chuyển hướng, CodeResponse sẽ được chuyển dưới dạng URL tham số.

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 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 sử 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.
error_description Văn bản ASCII mà con người có thể đọc được cung cấp thêm thông tin, dùng để hỗ trợ nhà phát triển ứng dụng hiểu lỗi đã xảy ra.
error_uri URI xác định trang web chứa thông tin về lỗi mà con người có thể đọc được, dùng để cung cấp cho nhà phát triển ứng dụng thông tin bổ sung về lỗi đó.

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 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 Bảng điều khiển API.
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. Danh sách phạm vi, phân tách bằng dấu cách giúp xác định các tài nguyên mà ứng dụng của bạn có thể truy cập thay mặt người dùng. Các giá trị này cho người dùng biết màn hình xin phép mà Google sẽ hiển thị cho người dùng.
include_granted_scopes Không bắt buộc, giá trị mặc định là true. Cho phép các ứng dụng sử dụng chế độ gia tăng uỷ quyền để yêu cầu quyền truy cập vào 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, sau đó 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, giá trị mặc định là 'select_account'. Tệp được phân tách bằng dấu cách, danh sách các câu lệnh (có phân biệt chữ hoa chữ thường) để trình bày cho người dùng. Các giá trị có thể có 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 bằng các giá trị khác.
  • "none" Không cho thấy màn hình xác thực hoặc màn hình xin phép sự đồng ý. Không được chỉ định bằng 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 bắt buộc, giá trị mặc định là true. Nếu đặt chính sách này thành false, các quyền chi tiết hơn đối với Tài khoản Google sẽ bị vô hiệu hoá đối với các mã ứng dụng OAuth được tạo trước năm 2019. Nếu bạn đặt cả enable_granular_consentenable_serial_consent thì chỉ có enable_granular_consent sẽ có hiệu lực và giá trị enable_serial_consent sẽ bị bỏ qua.

Các mã ứng dụng OAuth mới hơn sẽ không bị ảnh hưởng vì luôn bật các quyền chi tiết hơn cho các mã ứng dụng này.
enable_serial_consent Không dùng nữa, bạn nên sử dụng enable_granular_consent. Chiến dịch này có tác dụng tương tự như enable_granular_consent. Ứng dụng hiện có sử dụng enable_serial_consent có thể tiếp tục làm như vậy, nhưng bạn nên cập nhật mã của bạn để sử dụng enable_granular_consent trong bản cập nhật ứng dụng tiếp theo.
login_hint Không bắt buộc. Nếu biết người dùng nào nên cho phép yêu cầu này, ứng dụng của bạn có thể sử dụng thuộc tính này để cung cấp gợi ý đăng nhập cho Google. Khi thành công, lựa chọn tài khoản sẽ được bỏ qua. Giá trị trường sub cho địa chỉ email hoặc mã thông báo nhận dạng 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 về OpenID Connect.
hd Không bắt buộc. Nếu ứng dụng của bạn biết người dùng thuộc miền Workspace nào, hãy sử dụng thông tin 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 sẵn cho miền đã cung cấp. Để biết thêm thông tin, hãy xem trường hd trong tài liệu về OpenID Connect.
state Không bắt buộc. Không nên. Chỉ định bất kỳ giá trị chuỗi nào mà ứng dụng của bạn sử dụng để duy trì trạng thái giữa yêu cầu uỷ quyền của bạ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 bị trả lại.

Trường "type" của tham số đầu vào sẽ cho biết 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 OAuth được trả về.
  • Phần giữ chỗ không xác định 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, phương thức này sẽ khởi động Quy trình trải nghiệm người dùng bằng 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ấ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 OverridableTokenClientConfig loại dữ liệu.

Thuộc tính
scope Không bắt buộc. Danh sách phạm vi, phân tách bằng dấu cách giúp xác định tài nguyên mà ứng dụng của bạn có thể truy cập thay mặt người dùng. Các 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.
include_granted_scopes Không bắt buộc, giá trị mặc định là true. Cho phép các ứng dụng sử dụng chế độ gia tăng uỷ quyền để yêu cầu quyền truy cập vào 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, sau đó 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. Danh sách câu lệnh, phân tách bằng dấu cách, phân biệt chữ hoa chữ thường để trình bày cho người dùng.
enable_granular_consent Không bắt buộc, giá trị mặc định là true. Nếu đặt chính sách này thành false, các quyền chi tiết hơn đối với Tài khoản Google sẽ bị tắt đối với các mã ứng dụng OAuth được tạo trước năm 2019.Nếu bạn đặt cả enable_granular_consentenable_serial_consent thì chỉ enable_granular_consent sẽ có hiệu lực và giá trị enable_serial_consent sẽ bị bỏ qua.

Các mã ứng dụng OAuth mới hơn sẽ không bị ảnh hưởng vì luôn bật các quyền chi tiết hơn cho các mã ứng dụng này.
enable_serial_consent Không dùng nữa, bạn nên sử dụng enable_granular_consent. Chiến dịch này có tác dụng tương tự như enable_granular_consent. Ứng dụng hiện có sử dụng enable_serial_consent có thể tiếp tục làm như vậy, nhưng bạn nên cập nhật mã của bạn để sử dụng enable_granular_consent trong bản cập nhật ứng dụng tiếp theo.
login_hint Không bắt buộc. Nếu biết người dùng nào nên cho phép yêu cầu này, ứng dụng của bạn có thể sử dụng thuộc tính này để cung cấp gợi ý đăng nhập cho Google. Khi thành công, lựa chọn tài khoản sẽ được bỏ qua. Giá trị trường sub cho địa chỉ email hoặc mã thông báo nhận dạng 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 về OpenID Connect.
state Không bắt buộc. Không nên. Chỉ định bất kỳ giá trị chuỗi nào mà ứng dụng của bạn sử dụng để duy trì trạng thái giữa yêu cầu uỷ quyền của bạn và phản hồi của máy chủ uỷ quyền.

Loại dữ liệu: TokenResponse

Đối tượng JavaScript TokenResponse sẽ được truyền đến phương pháp gọi lại của bạn trong trải nghiệm người dùng 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ã 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 tính bằng giây của mã truy cập.
hd Miền được lưu trữ nơi 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ể có 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 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 sử 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.
error_description Văn bản ASCII mà con người có thể đọc được cung cấp thêm thông tin, dùng để hỗ trợ nhà phát triển ứng dụng hiểu lỗi đã xảy ra.
error_uri URI xác định trang web chứa thông tin về lỗi mà con người có thể đọc được, dùng để cung cấp cho nhà phát triển ứng dụng thông tin bổ sung về lỗi đó.

Phương pháp: google.accounts.oauth2.hasRightedAllScopes

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

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

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

Kiểm tra xem người dùng đã cấp quyền nào trong phạm vi hoặc phạm vi đã chỉ định hay chưa.

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

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

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

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Đối số
accessToken string 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

Đối tượng JavaScript RevocationResponse 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 bật thành công, false khi không thành công.
error Chuỗi. Không xác định về thành công. Một mã lỗi ASCII. Điều này bao gồm nhưng không giới hạn ở OAuth tiêu chuẩn 2.0. Các lỗi thường gặp cho 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 gọi phương thức revoke. Trong hầu hết các trường hợp, bạn có thể xem xét khoản tài trợ liên quan đến accessToken đã bị thu hồi.
  • invalid_request – Mã thông báo không thể thu hồi. Bạn cần đảm bảo accessToken là thông tin đăng nhập Google OAuth 2.0 hợp lệ.
error_description Chuỗi. Không xác định về 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 lỗi đã xảy ra. Chuỗi error_description chỉ có bằng tiếng Anh. Đối với các lỗi phổ biến được liệt kê trong error, error_description tương ứng:
  • invalid_token – Mã thông báo đã hết hạn hoặc bị thu hồi.
  • invalid_request – Mã thông báo không thể thu hồi.