Menggunakan OAuth 2.0 untuk Mengakses Google API

API Google menggunakan OAuth protokol 2.0 untuk otentikasi dan otorisasi. Google mendukung skenario OAuth 2.0 umum seperti untuk server web, sisi klien, terinstal, dan aplikasi perangkat dengan input terbatas.

Untuk memulai, mendapatkan OAuth kredensial 2.0 klien dari Google API Console . Kemudian aplikasi klien Anda meminta token akses dari Server Otorisasi Google, mengekstrak token dari respons, dan mengirimkan token ke Google API yang ingin Anda akses. Untuk demonstrasi interaktif menggunakan OAuth 2.0 dengan Google (termasuk pilihan untuk menggunakan kredensial klien Anda sendiri), percobaan dengan OAuth 2.0 Playground .

Laman ini memberikan ikhtisar skenario otorisasi OAuth 2.0 yang didukung Google, dan menyediakan tautan ke konten yang lebih mendetail. Untuk rincian tentang menggunakan OAuth 2.0 untuk otentikasi, lihat OpenID Connect .

Langkah dasar

Semua aplikasi mengikuti pola dasar saat mengakses Google API menggunakan OAuth 2.0. Pada tingkat tinggi, Anda mengikuti lima langkah:

1. Mendapatkan OAuth 2.0 mandat dari Google API Console.

Kunjungi Google API Console untuk mendapatkan OAuth 2.0 mandat seperti klien ID dan klien rahasia yang diketahui Google dan aplikasi Anda. Kumpulan nilai bervariasi berdasarkan jenis aplikasi yang Anda buat. Misalnya, aplikasi JavaScript tidak memerlukan rahasia, tetapi aplikasi server web melakukannya.

2. Dapatkan token akses dari Server Otorisasi Google.

Sebelum aplikasi Anda dapat mengakses data pribadi menggunakan Google API, aplikasi harus mendapatkan token akses yang memberikan akses ke API tersebut. Token akses tunggal dapat memberikan berbagai tingkat akses ke beberapa API. Parameter variabel yang disebut scope kontrol set sumber daya dan operasi yang akses izin tanda. Selama permintaan akses-token, aplikasi Anda mengirimkan satu atau lebih nilai-nilai dalam scope parameter.

Ada beberapa cara untuk membuat permintaan ini, dan berbeda-beda berdasarkan jenis aplikasi yang Anda buat. Misalnya, aplikasi JavaScript mungkin meminta token akses menggunakan browser yang dialihkan ke Google, sedangkan aplikasi yang diinstal pada perangkat yang tidak memiliki browser menggunakan permintaan layanan web.

Beberapa permintaan memerlukan langkah autentikasi di mana pengguna masuk dengan akun Google mereka. Setelah masuk, pengguna ditanya apakah mereka bersedia memberikan satu atau lebih izin yang diminta aplikasi Anda. Proses ini disebut izin pengguna.

Jika pengguna memberikan setidaknya satu izin, Server Otorisasi Google mengirimkan token akses kepada aplikasi Anda (atau kode otorisasi yang dapat digunakan aplikasi Anda untuk mendapatkan token akses) dan daftar cakupan akses yang diberikan oleh token tersebut. Jika pengguna tidak memberikan izin, server mengembalikan kesalahan.

Biasanya merupakan praktik terbaik untuk meminta cakupan secara bertahap, pada saat akses diperlukan, bukan di muka. Misalnya, aplikasi yang ingin mendukung penyimpanan acara ke kalender tidak boleh meminta akses Google Kalender hingga pengguna menekan tombol "Tambahkan ke Kalender"; melihat Incremental otorisasi .

3. Periksa cakupan akses yang diberikan oleh pengguna.

Bandingkan cakupan yang disertakan dalam respons token akses dengan cakupan yang diperlukan untuk mengakses fitur dan fungsionalitas aplikasi Anda yang bergantung pada akses ke Google API terkait. Nonaktifkan semua fitur aplikasi Anda yang tidak dapat berfungsi tanpa akses ke API terkait.

Cakupan yang disertakan dalam permintaan Anda mungkin tidak cocok dengan cakupan yang disertakan dalam respons Anda, meskipun pengguna memberikan semua cakupan yang diminta. Lihat dokumentasi untuk setiap Google API untuk cakupan yang diperlukan untuk akses. API dapat memetakan beberapa nilai string cakupan ke satu cakupan akses, mengembalikan string cakupan yang sama untuk semua nilai yang diizinkan dalam permintaan. Contoh: API Google Orang mungkin mengembalikan lingkup https://www.googleapis.com/auth/contacts ketika sebuah aplikasi meminta pengguna mengotorisasi lingkup https://www.google.com/m8/feeds/ ; metode API Google Orang people.updateContact membutuhkan ruang lingkup yang diberikan dari https://www.googleapis.com/auth/contacts .

4. Kirim token akses ke API.

Setelah aplikasi memperoleh token akses, ia akan mengirimkan token ke API Google dalam header permintaan HTTP Otorisasi . Dimungkinkan untuk mengirim token sebagai parameter string kueri URI, tetapi kami tidak menyarankannya, karena parameter URI dapat berakhir di file log yang tidak sepenuhnya aman. Selain itu, praktik REST yang baik adalah menghindari pembuatan nama parameter URI yang tidak perlu. Perhatikan bahwa dukungan string kueri akan dihentikan pada 1 Juni 2021.

Token akses hanya berlaku untuk set operasi dan sumber daya yang dijelaskan dalam scope permintaan tanda. Misalnya, jika token akses dikeluarkan untuk Google Calendar API, itu tidak memberikan akses ke Google Contacts API. Namun, Anda dapat mengirim token akses tersebut ke Google Calendar API beberapa kali untuk operasi serupa.

5. Refresh token akses, jika perlu.

Token akses memiliki masa pakai yang terbatas. Jika aplikasi Anda memerlukan akses ke Google API di luar masa pakai token akses tunggal, aplikasi dapat memperoleh token penyegaran. Token penyegaran memungkinkan aplikasi Anda mendapatkan token akses baru.

Skenario

Aplikasi server web

Titik akhir Google OAuth 2.0 mendukung aplikasi server web yang menggunakan bahasa dan kerangka kerja seperti PHP, Java, Python, Ruby, dan ASP.NET.

Urutan otorisasi dimulai saat aplikasi Anda mengalihkan browser ke URL Google; URL menyertakan parameter kueri yang menunjukkan jenis akses yang diminta. Google menangani otentikasi pengguna, pemilihan sesi, dan persetujuan pengguna. Hasilnya adalah kode otorisasi, yang dapat ditukar oleh aplikasi dengan token akses dan token penyegaran.

Aplikasi harus menyimpan token penyegaran untuk penggunaan di masa mendatang dan menggunakan token akses untuk mengakses Google API. Setelah token akses kedaluwarsa, aplikasi menggunakan token penyegaran untuk mendapatkan yang baru.

Aplikasi Anda mengirimkan permintaan token ke Server Otorisasi Google, menerima kode otorisasi, menukar kode dengan token, dan menggunakan token untuk memanggil titik akhir Google API.

Untuk rincian, lihat Menggunakan OAuth 2.0 untuk Web Server Aplikasi .

Aplikasi yang diinstal

Titik akhir Google OAuth 2.0 mendukung aplikasi yang diinstal pada perangkat seperti komputer, perangkat seluler, dan tablet. Ketika Anda membuat ID klien melalui Google API Console , menentukan bahwa ini adalah sebuah aplikasi Terpasang, kemudian pilih Android, aplikasi Chrome, iOS, Universal Platform Windows (UWP), atau aplikasi Desktop sebagai jenis aplikasi.

Proses tersebut menghasilkan ID klien dan, dalam beberapa kasus, rahasia klien, yang Anda sematkan dalam kode sumber aplikasi Anda. (Dalam konteks ini, rahasia klien jelas tidak diperlakukan sebagai rahasia.)

Urutan otorisasi dimulai saat aplikasi Anda mengalihkan browser ke URL Google; URL menyertakan parameter kueri yang menunjukkan jenis akses yang diminta. Google menangani otentikasi pengguna, pemilihan sesi, dan persetujuan pengguna. Hasilnya adalah kode otorisasi, yang dapat ditukar oleh aplikasi dengan token akses dan token penyegaran.

Aplikasi harus menyimpan token penyegaran untuk penggunaan di masa mendatang dan menggunakan token akses untuk mengakses Google API. Setelah token akses kedaluwarsa, aplikasi menggunakan token penyegaran untuk mendapatkan yang baru.

Aplikasi Anda mengirimkan permintaan token ke Server Otorisasi Google, menerima kode otorisasi, menukar kode dengan token, dan menggunakan token untuk memanggil titik akhir Google API.

Untuk rincian, lihat Menggunakan OAuth 2.0 untuk Aplikasi Terpasang .

Aplikasi sisi klien (JavaScript)

Titik akhir Google OAuth 2.0 mendukung aplikasi JavaScript yang berjalan di browser.

Urutan otorisasi dimulai saat aplikasi Anda mengalihkan browser ke URL Google; URL menyertakan parameter kueri yang menunjukkan jenis akses yang diminta. Google menangani otentikasi pengguna, pemilihan sesi, dan persetujuan pengguna.

Hasilnya adalah token akses, yang harus divalidasi oleh klien sebelum memasukkannya ke dalam permintaan Google API. Ketika token kedaluwarsa, aplikasi mengulangi prosesnya.

Aplikasi JS Anda mengirimkan permintaan token ke Server Otorisasi Google, menerima token, memvalidasi token, dan menggunakan token untuk memanggil titik akhir Google API.

Untuk rincian, lihat Menggunakan OAuth 2.0 untuk Aplikasi Client-side .

Aplikasi pada perangkat dengan input terbatas

Titik akhir Google OAuth 2.0 mendukung aplikasi yang berjalan pada perangkat dengan input terbatas seperti konsol game, kamera video, dan printer.

Urutan otorisasi dimulai dengan aplikasi membuat permintaan layanan web ke URL Google untuk kode otorisasi. Respons berisi beberapa parameter, termasuk URL dan kode yang ditampilkan aplikasi kepada pengguna.

Pengguna memperoleh URL dan kode dari perangkat, lalu beralih ke perangkat atau komputer terpisah dengan kemampuan input yang lebih kaya. Pengguna meluncurkan browser, menavigasi ke URL yang ditentukan, masuk, dan memasukkan kode.

Sementara itu, aplikasi melakukan polling URL Google pada interval tertentu. Setelah pengguna menyetujui akses, respons dari server Google berisi token akses dan token penyegaran. Aplikasi harus menyimpan token penyegaran untuk penggunaan di masa mendatang dan menggunakan token akses untuk mengakses Google API. Setelah token akses kedaluwarsa, aplikasi menggunakan token penyegaran untuk mendapatkan yang baru.

Pengguna masuk pada perangkat terpisah yang memiliki browser

Untuk rincian, lihat Menggunakan OAuth 2.0 untuk Perangkat .

Akun layanan

Google API seperti Prediction API dan Google Cloud Storage dapat bertindak atas nama aplikasi Anda tanpa mengakses informasi pengguna. Dalam situasi ini, aplikasi Anda perlu membuktikan identitasnya sendiri ke API, tetapi persetujuan pengguna tidak diperlukan. Demikian pula, dalam skenario perusahaan, aplikasi Anda dapat meminta akses yang didelegasikan ke beberapa sumber daya.

Untuk jenis server-ke-server interaksi Anda memerlukan account layanan, yang merupakan akun yang dimiliki aplikasi Anda, bukan untuk pengguna akhir individual. Aplikasi Anda memanggil Google API atas nama akun layanan, dan persetujuan pengguna tidak diperlukan. (Dalam skenario akun non-layanan, aplikasi Anda memanggil Google API atas nama pengguna akhir, dan persetujuan pengguna terkadang diperlukan.)

Kredensial Account layanan, yang Anda peroleh dari Google API Console, termasuk alamat yang dihasilkan email yang unik, ID klien, dan setidaknya satu pasangan kunci publik / privat. Anda menggunakan ID klien dan satu kunci pribadi untuk membuat JWT yang ditandatangani dan membuat permintaan token akses dalam format yang sesuai. Aplikasi Anda kemudian mengirimkan permintaan token ke Server Otorisasi Google OAuth 2.0, yang mengembalikan token akses. Aplikasi menggunakan token untuk mengakses Google API. Ketika token kedaluwarsa, aplikasi mengulangi prosesnya.

Aplikasi server Anda menggunakan JWT untuk meminta token dari Server Otorisasi Google, lalu menggunakan token untuk memanggil titik akhir Google API. Tidak ada pengguna akhir yang terlibat.

Untuk rincian, lihat dokumentasi layanan-akun .

Ukuran token

Token dapat bervariasi dalam ukuran, hingga batas berikut:

  • Kode otorisasi: 256 byte
  • Token akses: 2048 byte
  • Segarkan token: 512 byte

Akses token dikembalikan oleh Google Cloud Security Token Service API yang terstruktur mirip dengan Google API OAuth 2.0 token akses tetapi memiliki batas ukuran tanda yang berbeda. Untuk rincian, lihat dokumentasi API .

Google berhak mengubah ukuran token dalam batas ini, dan aplikasi Anda harus mendukung ukuran token variabel yang sesuai.

Segarkan kedaluwarsa token

Anda harus menulis kode untuk mengantisipasi kemungkinan bahwa token penyegaran yang diberikan mungkin tidak lagi berfungsi. Token penyegaran mungkin berhenti berfungsi karena salah satu alasan berikut:

  • Pengguna telah dicabut akses aplikasi Anda .
  • Token penyegaran belum digunakan selama enam bulan.
  • Pengguna mengubah sandi dan token penyegaran berisi cakupan Gmail.
  • Akun pengguna telah melampaui jumlah maksimum token penyegaran (langsung) yang diberikan.
  • Pengguna termasuk dalam organisasi Google Cloud Platform yang memiliki kebijakan kontrol sesi yang berlaku.

Project Google Cloud Platform dengan layar izin OAuth yang dikonfigurasi untuk jenis pengguna eksternal dan status publikasi "Pengujian" akan diberikan token penyegaran yang akan berakhir dalam 7 hari.

Saat ini ada batas 50 token penyegaran per Akun Google per ID klien OAuth 2.0. Jika batas tercapai, membuat token penyegaran baru secara otomatis membatalkan token penyegaran tertua tanpa peringatan. Batas ini tidak berlaku untuk account layanan .

Ada juga batasan yang lebih besar pada jumlah total token penyegaran yang dapat dimiliki akun pengguna atau akun layanan di semua klien. Sebagian besar pengguna normal tidak akan melebihi batas ini, tetapi akun pengembang yang digunakan untuk menguji implementasi mungkin.

Jika Anda perlu untuk mengotorisasi beberapa program, mesin, atau perangkat, salah satu solusi adalah dengan membatasi jumlah klien yang Anda mengotorisasi per Akun Google untuk 15 atau 20. Jika Anda adalah admin Google Workspace , Anda dapat membuat pengguna tambahan hak akses administratif dan menggunakannya untuk mengotorisasi beberapa klien.

Berurusan dengan kebijakan kontrol sesi untuk organisasi Google Cloud Platform (GCP)

Administrator organisasi GCP mungkin memerlukan sering reauthentication pengguna saat mereka mengakses sumber GCP, menggunakan fitur kontrol sesi Google Cloud . Dampak kebijakan ini akses ke Google Cloud Console, yang Google Cloud SDK (juga dikenal sebagai CLI gcloud), dan aplikasi OAuth pihak ketiga yang membutuhkan ruang lingkup Cloud Platform. Jika pengguna memiliki kebijakan pengendalian sesi di tempat maka pada berakhirnya durasi sesi, panggilan API Anda akan error keluar mirip dengan apa yang akan terjadi jika refresh token dicabut - panggilan akan gagal dengan jenis kesalahan invalid_token ; jenis sub-kesalahan dapat digunakan untuk membedakan antara token pencabutan dan kegagalan karena kebijakan kontrol sesi. Karena durasi sesi bisa sangat terbatas (antara 1 jam hingga 24 jam), skenario ini harus ditangani dengan baik dengan memulai kembali sesi autentikasi.

Demikian pula, Anda tidak boleh menggunakan, atau mendorong penggunaan, kredensial pengguna untuk penyebaran server ke server. Jika kredensial pengguna disebarkan di server untuk pekerjaan atau operasi yang berjalan lama dan pelanggan menerapkan kebijakan kontrol sesi pada pengguna tersebut, aplikasi server akan gagal karena tidak ada cara untuk mengautentikasi ulang pengguna saat durasi sesi berakhir.

Untuk informasi lebih lanjut tentang bagaimana untuk membantu pelanggan Anda menyebarkan fitur ini, lihat ini admin-difokuskan artikel bantuan.

Pustaka klien

Pustaka klien berikut terintegrasi dengan kerangka kerja populer, yang membuat penerapan OAuth 2.0 menjadi lebih sederhana. Lebih banyak fitur akan ditambahkan ke perpustakaan dari waktu ke waktu.