Library Layanan Identitas Google memungkinkan pengguna meminta kode otorisasi dari Google menggunakan alur Popup atau Pengalihan UX berbasis browser. Tindakan ini akan memulai alur OAuth 2.0 yang aman dan menghasilkan token akses yang digunakan untuk memanggil Google API atas nama pengguna.
Ringkasan alur kode otorisasi OAuth 2.0:
- Dari browser, dengan gestur seperti mengklik tombol, pemilik Akun Google akan meminta kode otorisasi dari Google.
- Google akan merespons, dengan mengirimkan kode otorisasi unik ke callback di aplikasi web JavaScript yang berjalan di browser pengguna, atau langsung memanggil endpoint kode otorisasi Anda menggunakan pengalihan browser.
- Platform backend Anda menghosting endpoint kode otorisasi dan menerima kode tersebut. Setelah divalidasi, kode ini ditukar dengan token refresh per pengguna dan token refresh menggunakan permintaan ke endpoint token Google.
- Google memvalidasi kode otorisasi, mengonfirmasi permintaan yang berasal dari platform aman Anda, menerbitkan akses dan token refresh, serta menampilkan token dengan memanggil endpoint login yang dihosting oleh platform Anda.
- Endpoint login Anda menerima token akses dan refresh, yang menyimpan token refresh dengan aman untuk digunakan nanti.
Menginisialisasi Code Client
Metode google.accounts.oauth2.initCodeClient()
melakukan inisialisasi klien kode.
Mode pop-up atau Pengalihan
Anda dapat memilih untuk membagikan kode autentikasi menggunakan alur pengguna mode Pengalihan atau Pop-up. Dengan mode Pengalihan, Anda menghosting endpoint otorisasi OAuth2 di server Anda dan Google mengalihkan agen pengguna ke endpoint ini, yang membagikan kode autentikasi sebagai parameter URL. Untuk mode Pop-up, Anda menentukan pengendali callback JavaScript, yang mengirimkan kode otorisasi ke server Anda. Mode pop-up dapat digunakan untuk memberikan pengalaman pengguna yang lancar tanpa mengharuskan pengunjung meninggalkan situs Anda.
Untuk melakukan inisialisasi klien untuk:
Alihkan alur UX, tetapkan
ux_mode
keredirect
, dan nilairedirect_uri
ke endpoint kode otorisasi platform Anda. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0 yang Anda konfigurasikan di Konsol API. URL tersebut juga harus sesuai dengan aturan validasi URI Pengalihan kami.Alur UX pop-up, tetapkan
ux_mode
kepopup
, dan nilaicallback
ke nama fungsi yang akan digunakan untuk mengirim kode otorisasi ke platform Anda.
Mencegah serangan CSRF
Untuk membantu mencegah serangan Cross-Site-Request-Forgery (CSRF) menggunakan teknik yang sedikit berbeda untuk alur UX mode Pengalihan dan Pop-up. Untuk mode Pengalihan, parameter state OAuth 2.0 digunakan. Lihat RFC6749 bagian 10.12 Pemalsuan Permintaan Lintas Situs untuk informasi selengkapnya tentang membuat dan memvalidasi parameter state. Dengan mode Pop-up, Anda menambahkan header HTTP kustom ke permintaan, kemudian di server Anda mengonfirmasi bahwa header tersebut cocok dengan nilai dan asal yang diharapkan.
Pilih mode UX untuk melihat cuplikan kode yang menunjukkan kode autentikasi dan penanganan CSRF:
Mode pengalihan
Lakukan inisialisasi klien saat Google mengalihkan browser pengguna ke endpoint autentikasi Anda, dengan membagikan kode autentikasi sebagai parameter URL.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'redirect',
redirect_uri: "https://your.domain/code_callback_endpoint",
state: "YOUR_BINDING_VALUE"
});
Mode pop-up
Lakukan inisialisasi klien saat browser pengguna menerima kode autentikasi dari Google dan mengirimkannya ke server Anda.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'popup',
callback: (response) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', code_receiver_uri, true);
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
// Set custom header for CRSF
xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
xhr.onload = function() {
console.log('Auth code response: ' + xhr.responseText);
};
xhr.send('code=' + response.code);
},
});
Memicu Alur Kode OAuth 2.0
Panggil metode requestCode()
klien kode untuk memicu alur pengguna:
<button onclick="client.requestCode();">Authorize with Google</button>
Tindakan ini akan mengharuskan pengguna untuk login ke Akun Google dan memberikan izin untuk membagikan setiap cakupan sebelum menampilkan kode otorisasi ke endpoint pengalihan atau pengendali callback Anda.
Penanganan kode Auth
Google membuat kode otorisasi unik per pengguna yang Anda terima dan verifikasi di server backend Anda.
Untuk mode Pop-up, pengendali yang ditentukan oleh callback
, yang berjalan di browser
pengguna, menyampaikan kode otorisasi ke endpoint yang dihosting oleh platform Anda.
Untuk mode Pengalihan, permintaan GET
dikirim ke endpoint yang ditentukan oleh
redirect_url
, yang membagikan kode otorisasi dalam parameter kode URL. Untuk menerima kode otorisasi:
Buat endpoint Otorisasi baru jika Anda belum memiliki penerapan, atau
Perbarui endpoint yang ada untuk menerima permintaan
GET
dan parameter URL. Sebelumnya, permintaanPUT
dengan nilai kode otorisasi dalam payload digunakan.
Endpoint otorisasi
Endpoint kode otorisasi Anda harus menangani permintaan GET
dengan parameter string kueri URL berikut:
Nama | Nilai |
---|---|
pengguna autentikasi | Meminta autentikasi login pengguna |
kode | Kode otorisasi OAuth2 yang dibuat oleh Google |
hd | Domain yang dihosting dari akun pengguna |
perintah | Dialog izin pengguna |
cakupan | Daftar yang dipisahkan spasi dari satu atau beberapa cakupan OAuth2 yang akan diizinkan |
state | Variabel status CRSF |
Contoh permintaan GET
dengan parameter URL ke endpoint yang bernama auth-code dan dihosting oleh example.com:
Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent
Saat alur kode otorisasi dimulai oleh library JavaScript sebelumnya, atau dengan panggilan langsung ke endpoint Google OAuth 2.0, permintaan POST
akan digunakan.
Contoh permintaan POST
yang berisi kode otorisasi sebagai payload dalam isi permintaan HTTP:
Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw
Memvalidasi permintaan
Di server Anda, lakukan hal berikut untuk membantu menghindari serangan CSRF.
Periksa nilai parameter state untuk mode pengalihan.
Konfirmasi bahwa header X-Requested-With: XmlHttpRequest
disetel untuk mode pop-up.
Selanjutnya, Anda harus melanjutkan dengan mendapatkan token refresh dan akses dari Google hanya jika Anda telah berhasil memverifikasi permintaan kode autentikasi terlebih dahulu.
Mendapatkan token akses dan refresh
Setelah platform backend Anda menerima kode otorisasi dari Google dan memverifikasi permintaan, gunakan kode autentikasi untuk mendapatkan akses dan token refresh dari Google untuk melakukan panggilan API.
Ikuti petunjuk mulai dari Langkah 5: Kode otorisasi Exchange untuk token refresh dan akses dalam panduan Menggunakan OAuth 2.0 untuk Aplikasi Server Web.
Mengelola token
Platform Anda menyimpan token refresh dengan aman. Hapus token refresh yang disimpan saat
akun pengguna dihapus, atau izin pengguna dicabut oleh
google.accounts.oauth2.revoke
atau langsung dari
https://myaccount.google.com/permissions.
Secara opsional, Anda dapat mempertimbangkan RISC untuk melindungi akun pengguna dengan Perlindungan Lintas Akun.
Biasanya, platform backend Anda akan memanggil Google API menggunakan token akses. Jika aplikasi web Anda juga akan langsung memanggil Google API dari browser pengguna, Anda harus mengimplementasikan cara untuk berbagi token akses dengan aplikasi web, hal tersebut di luar cakupan panduan ini. Saat mengikuti pendekatan ini dan menggunakan Library Klien Google API untuk JavaScript, gunakan gapi.client.SetToken()
untuk menyimpan token akses sementara di memori browser, dan mengaktifkan library untuk memanggil Google API.