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 token akses 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 Anda atas nama pengguna. Nilai ini akan menentukan layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, default ke true. Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi diberikan, token akses baru hanya akan mencakup cakupan yang diminta oleh scope dalam CodeClientConfig ini.
redirect_uri Diperlukan untuk UX pengalihan. Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai ini harus sama persis dengan salah satu URI alihan yang diotorisasi untuk klien OAuth 2.0, yang Anda konfigurasi di API Console dan harus sesuai dengan Aturan validasi URI alihan 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 UX pengalihan. Menentukan nilai string apa pun yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi.
enable_granular_consent Tidak digunakan lagi, tidak berpengaruh jika ditetapkan. Lihat izin terperinci untuk mengetahui detail perilaku izin.
enable_serial_consent Tidak digunakan lagi, tidak berpengaruh jika ditetapkan. Lihat izin terperinci untuk mengetahui detail perilaku izin.
login_hint Opsional. Jika mengetahui pengguna mana yang harus memberikan otorisasi untuk permintaan tersebut, aplikasi Anda 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 dalam dokumentasi OpenID Connect.
hd Opsional. Jika aplikasi Anda mengetahui domain Workspace tempat pengguna berada, gunakan ini untuk memberikan petunjuk kepada Google. Jika berhasil, akun pengguna akan dibatasi atau dipilih sebelumnya untuk domain yang diberikan. Untuk informasi selengkapnya, lihat kolom hd dalam dokumentasi OpenID Connect.
ux_mode Opsional. Mode UX yang akan digunakan untuk alur otorisasi. Secara default, tindakan ini akan membuka alur izin di pop-up. Nilai yang valid adalah popup dan redirect.
select_account Opsional, defaultnya adalah 'false'. Nilai Boolean untuk meminta pengguna memilih akun.
error_callback Opsional. Fungsi JavaScript yang menangani beberapa error non-OAuth, seperti jendela pop-up gagal terbuka; atau ditutup sebelum respons OAuth ditampilkan.

Kolom `type` dari parameter input memberikan alasan mendetail.
  • 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 publik requestCode, 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. Dalam 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 Satu kode error ASCII.
error_description Teks ASCII yang dapat dibaca manusia yang memberikan informasi tambahan, digunakan untuk membantu developer klien memahami error yang terjadi.
error_uri URI yang mengidentifikasi halaman web yang dapat dibaca manusia dengan informasi tentang error, yang digunakan untuk memberi developer klien informasi tambahan tentang error.

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 Anda atas nama pengguna. Nilai ini akan menentukan layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, default ke true. Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi diberikan, token akses baru hanya akan mencakup cakupan yang diminta oleh scope dalam TokenClientConfig ini.
prompt Opsional, defaultnya adalah 'select_account'. Daftar perintah yang peka huruf besar/kecil dan dipisahkan spasi untuk ditampilkan kepada pengguna. Kemungkinan nilainya adalah:
  • string kosong Pengguna hanya akan diminta saat pertama kali aplikasi Anda meminta akses. Tidak dapat ditentukan dengan nilai lain.
  • 'none' Jangan tampilkan layar autentikasi atau izin apa pun. Tidak boleh ditentukan dengan nilai lain.
  • 'consent' Meminta izin pengguna.
  • 'select_account' Meminta pengguna untuk memilih akun.
enable_granular_consent Tidak digunakan lagi, tidak berpengaruh jika ditetapkan. Lihat izin terperinci untuk mengetahui detail perilaku izin.
enable_serial_consent Tidak digunakan lagi, tidak berpengaruh jika ditetapkan. Lihat izin terperinci untuk mengetahui detail perilaku izin.
login_hint Opsional. Jika mengetahui pengguna mana yang harus memberikan otorisasi untuk permintaan tersebut, aplikasi Anda 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 dalam dokumentasi OpenID Connect.
hd Opsional. Jika aplikasi Anda mengetahui domain Workspace tempat pengguna berada, gunakan ini untuk memberikan petunjuk kepada Google. Jika berhasil, akun pengguna akan dibatasi atau dipilih sebelumnya untuk domain yang diberikan. Untuk informasi selengkapnya, lihat kolom hd dalam dokumentasi OpenID Connect.
state Opsional. Tidak direkomendasikan. Menentukan nilai string apa pun 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 terbuka; atau ditutup sebelum respons OAuth ditampilkan.

Kolom `type` dari parameter input memberikan alasan mendetail.
  • 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 Anda atas nama pengguna. Nilai ini menginformasikan layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, default ke true. Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi diberikan, token akses baru hanya akan mencakup cakupan yang diminta oleh scope dalam OverridableTokenClientConfig ini.
prompt Opsional. Daftar perintah yang peka huruf besar/kecil dan dipisahkan spasi untuk ditampilkan kepada pengguna.
enable_granular_consent Tidak digunakan lagi, tidak berpengaruh jika ditetapkan. Lihat izin terperinci untuk mengetahui detail perilaku izin.
enable_serial_consent Tidak digunakan lagi, tidak berpengaruh jika ditetapkan. Lihat izin terperinci untuk mengetahui detail perilaku izin.
login_hint Opsional. Jika mengetahui pengguna mana yang harus memberikan otorisasi untuk permintaan tersebut, aplikasi Anda 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 dalam dokumentasi OpenID Connect.
state Opsional. Tidak direkomendasikan. Menentukan nilai string apa pun 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 dari respons token yang berhasil.
expires_in Masa berlaku token akses dalam detik.
hd Domain yang dihosting tempat pengguna yang login berada.
prompt Nilai perintah yang digunakan dari kemungkinan daftar nilai 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 Satu kode error ASCII.
error_description Teks ASCII yang dapat dibaca manusia yang memberikan informasi tambahan, digunakan untuk membantu developer klien memahami error yang terjadi.
error_uri URI yang mengidentifikasi halaman web yang dapat dibaca manusia dengan informasi tentang error, yang digunakan untuk memberi developer klien informasi tambahan tentang error.

Metode: google.accounts.oauth2.hasGrantedAllScopes

Memeriksa apakah pengguna telah 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 yang perlu diperiksa.
Hasil
boolean Benar jika semua cakupan diberikan.

Metode: google.accounts.oauth2.hasGrantedAnyScope

Memeriksa apakah pengguna telah memberikan salah satu 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 yang perlu diperiksa.
Hasil
boolean Benar 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. Pengendali RevocationResponse.

Jenis data: RevocationResponse

Objek JavaScript RevocationResponse akan diteruskan ke metode callback Anda.

Tabel berikut mencantumkan properti jenis data RevocationResponse.

Properti
successful Boolean. true jika berhasil, false jika gagal.
error String. Tidak ditentukan jika berhasil. Satu kode error ASCII. Hal ini mencakup, tetapi tidak terbatas pada, kode error OAuth 2.0 standar. Error umum untuk metode revoke:
  • invalid_token - Token sudah tidak berlaku atau dicabut sebelum metode revoke dipanggil. Pada umumnya, Anda dapat menganggap bahwa pemberian yang terkait dengan accessToken dicabut.
  • invalid_request - Token tidak dapat dicabut. Anda harus memastikan accessToken adalah kredensial Google OAuth 2.0 yang valid.
error_description String. Tidak ditentukan jika berhasil. Teks ASCII yang dapat dibaca manusia memberikan informasi tambahan tentang 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 telah habis masa berlakunya atau dicabut.
  • invalid_request - Token tidak dapat dicabut.