Referensi Google Account Authorization JavaScript API

Referensi ini menjelaskan Google Account Authorization JavaScript API, yang digunakan untuk mendapatkan 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 dengan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini memberi tahu layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, defaultnya adalah true. Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi diberikan, maka token akses baru hanya akan mencakup cakupan yang diminta scope dalam CodeClientConfig ini.
redirect_uri Diperlukan untuk UX pengalihan. Menentukan ke mana server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai harus sama persis dengan salah satu URI pengalihan yang sah untuk klien OAuth 2.0, yang 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 UX pengalihan. Menentukan nilai string apa pun yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi.
enable_granular_consent Tidak digunakan lagi, tidak berpengaruh jika disetel. Lihat izin terperinci untuk mengetahui detail perilaku izin.
enable_serial_consent Tidak digunakan lagi, tidak berpengaruh jika disetel. Lihat izin terperinci untuk mengetahui detail perilaku izin.
login_hint Opsional. Jika aplikasi Anda mengetahui pengguna mana yang harus mengizinkan permintaan, aplikasi dapat menggunakan properti ini untuk memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai kolom sub alamat email atau token ID untuk pengguna target. Untuk mengetahui 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 mengetahui informasi selengkapnya, lihat kolom hd dalam dokumentasi OpenID Connect.
ux_mode Opsional. Mode UX yang akan digunakan untuk alur otorisasi. Secara default, alur izin akan terbuka di jendela 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 gagal membuka jendela pop-up; 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.
  • Placeholder unknown untuk error lainnya.

Jenis data: CodeClient

Class ini hanya memiliki satu metode publik, yaitu 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. 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 dan 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 mudah dibaca dengan informasi tentang error, yang digunakan untuk memberikan informasi tambahan tentang error kepada developer klien.

Metode: google.accounts.oauth2.initTokenClient

Metode initTokenClient menginisialisasi 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 dengan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini memberi tahu layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, defaultnya adalah true. Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi diberikan, maka token akses baru hanya akan mencakup cakupan yang diminta scope dalam TokenClientConfig ini.
prompt Opsional, defaultnya adalah 'select_account'. Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk ditampilkan kepada pengguna. Nilai yang mungkin adalah:
  • string kosong Pengguna hanya akan diminta saat aplikasi Anda meminta akses untuk pertama kalinya. Tidak dapat ditentukan dengan nilai lain.
  • 'none' Jangan menampilkan layar izin atau autentikasi 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 disetel. Lihat izin terperinci untuk mengetahui detail perilaku izin.
enable_serial_consent Tidak digunakan lagi, tidak berpengaruh jika disetel. Lihat izin terperinci untuk mengetahui detail perilaku izin.
login_hint Opsional. Jika aplikasi Anda mengetahui pengguna mana yang harus mengizinkan permintaan, aplikasi dapat menggunakan properti ini untuk memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai kolom sub alamat email atau token ID untuk pengguna target. Untuk mengetahui 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 mengetahui 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 Anda dan respons server otorisasi.
error_callback Opsional. Fungsi JavaScript yang menangani beberapa error non-OAuth, seperti gagal membuka jendela pop-up; 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.
  • Placeholder unknown 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 dengan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini memberi tahu layar izin yang ditampilkan Google kepada pengguna.
include_granted_scopes Opsional, defaultnya adalah true. Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke false dan permintaan otorisasi diberikan, maka token akses baru hanya akan mencakup cakupan yang diminta scope dalam OverridableTokenClientConfig ini.
prompt Opsional. Daftar perintah yang dipisahkan dengan spasi dan peka huruf besar/kecil untuk ditampilkan kepada pengguna.
enable_granular_consent Tidak digunakan lagi, tidak berpengaruh jika disetel. Lihat izin terperinci untuk mengetahui detail perilaku izin.
enable_serial_consent Tidak digunakan lagi, tidak berpengaruh jika disetel. Lihat izin terperinci untuk mengetahui detail perilaku izin.
login_hint Opsional. Jika aplikasi Anda mengetahui pengguna mana yang harus mengizinkan permintaan, aplikasi dapat menggunakan properti ini untuk memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai kolom sub alamat email atau token ID untuk pengguna target. Untuk mengetahui 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 Anda 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 hitungan 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 dan 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 mudah dibaca dengan informasi tentang error, yang digunakan untuk memberikan informasi tambahan tentang error kepada developer klien.

Metode: google.accounts.oauth2.hasGrantedAllScopes

Memeriksa apakah pengguna memberikan semua 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 memberikan cakupan atau cakupan tertentu.

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. Handler RevocationResponse.

Jenis data: RevocationResponse

Objek JavaScript RevocationResponse akan diteruskan ke metode callback Anda.

Tabel berikut mencantumkan properti jenis data RevocationResponse.

Properti
successful Boolean. true saat berhasil, false saat 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. Dalam sebagian besar kasus, Anda dapat menganggap bahwa pemberian yang terkait dengan accessToken telah dibatalkan.
  • 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 menggunakan ini 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.