Library JavaScript Otorisasi Pihak Ketiga Google untuk situs - Referensi API

Referensi ini menjelaskan Google 3P Authorization JavaScript Library API, yang dapat Anda gunakan untuk memuat kode otorisasi atau mengakses token dari Google.

Metode: google.accounts.oauth2.initCodeClient

Metode initCodeClient melakukan inisialisasi dan menampilkan klien kode, dengan konfigurasi dalam parameter.

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

Jenis data: CodeClientConfig

Tabel berikut mencantumkan properti jenis data CodeClientConfig.

Properti
client_id Wajib. Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Konsol API.
scope Wajib. Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi atas nama pengguna. Nilai ini menentukan layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, ditetapkan secara default ke true. Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi disetujui, token akses baru hanya akan mencakup semua cakupan yang diminta oleh scope dalam CodeClientConfig ini.
redirect_uri Diperlukan untuk pengalihan UX. Menentukan di mana server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai harus sama persis dengan salah satu URI pengalihan yang diotorisasi untuk klien OAuth 2.0, yang telah Anda konfigurasi di Konsol API dan harus sesuai dengan aturan validasi URI Pengalihan kami. Properti akan diabaikan oleh UX pop-up.
callback Diperlukan untuk UX pop-up. Fungsi JavaScript yang menangani respons kode yang ditampilkan. Properti akan diabaikan oleh UX pengalihan.
state Opsional. Direkomendasikan untuk pengalihan UX. Menentukan nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi.
enable_granular_consent Opsional, ditetapkan secara default ke true. Jika ditetapkan ke false, izin Akun Google yang lebih terperinci akan dinonaktifkan untuk client ID OAuth yang dibuat sebelum 2019. Jika enable_granular_consent dan enable_serial_consent ditetapkan, hanya nilai enable_granular_consent yang akan diterapkan dan nilai enable_serial_consent akan diabaikan.

Tidak akan berpengaruh untuk client ID OAuth yang lebih baru, karena izin yang lebih terperinci selalu diaktifkan untuk client ID tersebut.
enable_serial_consent Tidak digunakan lagi, sebagai gantinya Anda harus menggunakan enable_granular_consent. Tindakan ini memiliki efek yang sama dengan enable_granular_consent. Aplikasi yang sudah ada yang menggunakan enable_serial_consent dapat terus melakukannya, tetapi Anda dianjurkan untuk mengupdate kode agar dapat menggunakan enable_granular_consent dalam update aplikasi berikutnya.
login_hint Opsional. Jika aplikasi Anda mengetahui pengguna mana yang harus menyetujui permintaan tersebut, aplikasi dapat menggunakan properti ini untuk memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai kolom sub token ID atau alamat email untuk pengguna target. Untuk informasi selengkapnya, lihat kolom login_hint di dokumentasi OpenID Connect.
hd Opsional. Jika aplikasi Anda mengetahui domain Workspace tempat pengguna berada, gunakan domain ini untuk memberikan petunjuk kepada Google. Jika berhasil, akun pengguna dibatasi atau telah dipilih sebelumnya untuk domain yang disediakan. Untuk informasi selengkapnya, lihat kolom hd di dokumentasi OpenID Connect.
ux_mode Opsional. Mode UX yang akan digunakan untuk alur otorisasi. Secara default, alur izin akan terbuka dalam pop-up. Nilai yang valid adalah popup dan redirect.
select_account Opsional, ditetapkan secara default ke 'false'. Nilai boolean untuk meminta pengguna memilih akun.
error_callback Opsional. Fungsi JavaScript yang menangani beberapa error non-OAuth, seperti jendela pop-up gagal dibuka; atau ditutup sebelum respons OAuth ditampilkan.

Kolom `type` dari parameter input memberikan alasan terperinci.
  • popup_failed_to_open Jendela pop-up gagal dibuka.
  • popup_closed Jendela pop-up ditutup sebelum respons OAuth ditampilkan.
  • unknown Placeholder untuk error lainnya.

Jenis data: CodeClient

Class ini hanya memiliki satu metode requestCode publik, yang memulai alur UX Kode OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

Jenis data: CodeResponse

Objek JavaScript CodeResponse akan diteruskan ke metode callback Anda di UX pop-up. Di UX pengalihan, CodeResponse akan diteruskan sebagai parameter URL.

Tabel berikut mencantumkan properti jenis data CodeResponse.

Properti
code Kode otorisasi respons token yang berhasil.
scope Daftar cakupan yang dipisahkan spasi yang disetujui oleh pengguna.
state Nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons.
error Kode error ASCII tunggal.
error_description Teks ASCII yang dapat dibaca manusia yang memberikan informasi tambahan, digunakan untuk membantu developer klien dalam memahami error yang terjadi.
error_uri URI yang mengidentifikasi halaman web yang dapat dibaca manusia dengan informasi tentang error, digunakan untuk memberikan informasi tambahan tentang error tersebut kepada developer klien.

Metode: google.accounts.oauth2.initTokenClient

Metode initTokenClient melakukan inisialisasi dan menampilkan klien token, dengan konfigurasi dalam parameter.

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

Jenis data: TokenClientConfig

Tabel berikut mencantumkan properti jenis data TokenClientConfig.

Properti
client_id Wajib. Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Konsol API.
callback Wajib. Fungsi JavaScript yang menangani respons token yang ditampilkan.
scope Wajib. Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi atas nama pengguna. Nilai ini menentukan layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, ditetapkan secara default ke true. Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi disetujui, token akses baru hanya akan mencakup semua cakupan yang diminta oleh scope dalam TokenClientConfig ini.
prompt Opsional, ditetapkan secara default ke 'select_account'. Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk ditampilkan kepada pengguna. Kemungkinan nilainya adalah:
  • string kosong Pengguna hanya akan diminta melakukannya saat pertama kali aplikasi meminta akses. Tidak dapat ditentukan dengan nilai lain.
  • 'none' Jangan tampilkan layar autentikasi atau izin apa pun. Tidak boleh ditentukan dengan nilai lain.
  • 'consent' Minta pengguna memberikan izin.
  • 'select_account' Minta pengguna memilih akun.
enable_granular_consent Opsional, ditetapkan secara default ke true. Jika ditetapkan ke false, izin Akun Google yang lebih terperinci akan dinonaktifkan untuk client ID OAuth yang dibuat sebelum 2019. Jika enable_granular_consent dan enable_serial_consent ditetapkan, hanya nilai enable_granular_consent yang akan diterapkan dan nilai enable_serial_consent akan diabaikan.

Tidak akan berpengaruh untuk client ID OAuth yang lebih baru, karena izin yang lebih terperinci selalu diaktifkan untuk client ID tersebut.
enable_serial_consent Tidak digunakan lagi, sebagai gantinya Anda harus menggunakan enable_granular_consent. Tindakan ini memiliki efek yang sama dengan enable_granular_consent. Aplikasi yang sudah ada yang menggunakan enable_serial_consent dapat terus melakukannya, tetapi Anda dianjurkan untuk mengupdate kode agar dapat menggunakan enable_granular_consent dalam update aplikasi berikutnya.
login_hint Opsional. Jika aplikasi Anda mengetahui pengguna mana yang harus menyetujui permintaan tersebut, aplikasi dapat menggunakan properti ini untuk memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai kolom sub token ID atau alamat email untuk pengguna target. Untuk informasi selengkapnya, lihat kolom login_hint di dokumentasi OpenID Connect.
hd Opsional. Jika aplikasi Anda mengetahui domain Workspace tempat pengguna berada, gunakan domain ini untuk memberikan petunjuk kepada Google. Jika berhasil, akun pengguna dibatasi atau telah dipilih sebelumnya untuk domain yang disediakan. Untuk informasi selengkapnya, lihat kolom hd di dokumentasi OpenID Connect.
state Opsional. Tidak direkomendasikan. Menentukan nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi.
error_callback Opsional. Fungsi JavaScript yang menangani beberapa error non-OAuth, seperti jendela pop-up gagal dibuka; atau ditutup sebelum respons OAuth ditampilkan.

Kolom `type` dari parameter input memberikan alasan terperinci.
  • popup_failed_to_open Jendela pop-up gagal dibuka.
  • popup_closed Jendela pop-up ditutup sebelum respons OAuth ditampilkan.
  • unknown Placeholder untuk error lainnya.

Jenis data: TokenClient

Class ini hanya memiliki satu metode publik requestAccessToken, yang memulai alur UX Token OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumen
overrideConfig OverridableTokenClientConfig Opsional. Konfigurasi yang akan diganti dalam metode ini.

Jenis data: OverridableTokenClientConfig

Tabel berikut mencantumkan properti jenis data OverridableTokenClientConfig.

Properti
scope Opsional. Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi atas nama pengguna. Nilai ini menentukan layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, ditetapkan secara default ke true. Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi disetujui, token akses baru hanya akan mencakup semua cakupan yang diminta oleh scope dalam OverridableTokenClientConfig ini.
prompt Opsional. Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk ditampilkan kepada pengguna.
enable_granular_consent Opsional, ditetapkan secara default ke true. Jika ditetapkan ke false, izin Akun Google yang lebih terperinci akan dinonaktifkan untuk client ID OAuth yang dibuat sebelum tahun 2019.Jika enable_granular_consent dan enable_serial_consent ditetapkan, hanya nilai enable_granular_consent yang akan diterapkan dan nilai enable_serial_consent yang akan diabaikan.

Tidak akan berpengaruh untuk client ID OAuth yang lebih baru, karena izin yang lebih terperinci selalu diaktifkan untuk client ID tersebut.
enable_serial_consent Tidak digunakan lagi, sebagai gantinya Anda harus menggunakan enable_granular_consent. Tindakan ini memiliki efek yang sama dengan enable_granular_consent. Aplikasi yang sudah ada yang menggunakan enable_serial_consent dapat terus melakukannya, tetapi Anda dianjurkan untuk mengupdate kode agar dapat menggunakan enable_granular_consent dalam update aplikasi berikutnya.
login_hint Opsional. Jika aplikasi Anda mengetahui pengguna mana yang harus menyetujui permintaan tersebut, aplikasi dapat menggunakan properti ini untuk memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai kolom sub token ID atau alamat email untuk pengguna target. Untuk informasi selengkapnya, lihat kolom login_hint di dokumentasi OpenID Connect.
state Opsional. Tidak direkomendasikan. Menentukan nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi.

Jenis data: TokenResponse

Objek JavaScript TokenResponse akan diteruskan ke metode callback Anda di UX pop-up.

Tabel berikut mencantumkan properti jenis data TokenResponse.

Properti
access_token Token akses respons token berhasil.
expires_in Masa pakai token akses dalam hitungan detik.
hd Domain yang dihosting tempat pengguna login.
prompt Nilai permintaan yang digunakan dari daftar nilai yang mungkin yang ditentukan oleh TokenClientConfig atau OverridableTokenClientConfig.
token_type Jenis token yang diterbitkan.
scope Daftar cakupan yang dipisahkan spasi yang disetujui oleh pengguna.
state Nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons.
error Kode error ASCII tunggal.
error_description Teks ASCII yang dapat dibaca manusia yang memberikan informasi tambahan, digunakan untuk membantu developer klien dalam memahami error yang terjadi.
error_uri URI yang mengidentifikasi halaman web yang dapat dibaca manusia dengan informasi tentang error, digunakan untuk memberikan informasi tambahan tentang error tersebut kepada developer klien.

Metode: google.accounts.oauth2.hasGrantedAllScopes

Memeriksa apakah pengguna memberikan semua cakupan atau cakupan yang ditentukan.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Argumen
tokenResponse TokenResponse Wajib. Objek TokenResponse.
firstScope string Wajib. Cakupan yang akan diperiksa.
restScopes string[] Opsional. Cakupan lain untuk diperiksa.
Hasil
boolean True jika semua cakupan diberikan.

Metode: google.accounts.oauth2.hasGrantedAnyScope

Memeriksa apakah pengguna memberikan cakupan atau cakupan yang ditentukan.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Argumen
tokenResponse TokenResponse Wajib. Objek TokenResponse.
firstScope string Wajib. Cakupan yang akan diperiksa.
restScopes string[] Opsional. Cakupan lain untuk diperiksa.
Hasil
boolean True jika salah satu cakupan diberikan.

Metode: google.accounts.oauth2.revoke

Metode revoke mencabut semua cakupan yang diberikan pengguna ke aplikasi. Token akses yang valid diperlukan untuk mencabut izin.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Argumen
accessToken string Wajib. Token akses yang valid.
callback fungsi Opsional. RevocationResponse.

Jenis data: RevocationResponse

Objek JavaScript RevocationResponse akan diteruskan ke metode callback Anda.

Tabel berikut mencantumkan properti jenis data RevocationResponse.

Properti
successful Boolean. true aktif, false jika gagal.
error String. Tidak ditentukan tentang kesuksesan. Kode error ASCII tunggal. Hal ini mencakup, tetapi tidak terbatas pada kode error OAuth 2.0 standar. Error umum untuk metode revoke:
  • invalid_token - Masa berlaku token sudah berakhir atau dicabut sebelum metode revoke dipanggil. Dalam sebagian besar kasus, Anda dapat menganggap bahwa pemberian yang terkait dengan accessToken telah dicabut.
  • invalid_request - Token tidak dapat dibatalkan. Anda harus memastikan accessToken adalah kredensial Google OAuth 2.0 yang valid.
error_description String. Tidak ditentukan tentang kesuksesan. Teks ASCII yang dapat dibaca manusia memberikan informasi tambahan pada properti error. Developer dapat menggunakannya untuk lebih memahami error yang terjadi. String error_description hanya dalam bahasa Inggris. Untuk error umum yang tercantum di error, error_description yang sesuai:
  • invalid_token - Token kedaluwarsa atau dicabut.
  • invalid_request - Token tidak dapat dibatalkan.