Google API menggunakan protokol OAuth 2.0 untuk autentikasi dan otorisasi. Google mendukung skenario OAuth 2.0 umum seperti skenario untuk aplikasi server web, sisi klien, terinstal, dan perangkat input terbatas.
Untuk memulai, dapatkan kredensial klien OAuth 2.0 dari Konsol API Google. Kemudian, aplikasi klien Anda meminta token akses dari Server Otorisasi Google, mengekstrak token dari respons, dan mengirim token ke Google API yang ingin Anda akses. Untuk demonstrasi interaktif tentang penggunaan OAuth 2.0 dengan Google (termasuk opsi untuk menggunakan kredensial klien Anda sendiri), bereksperimenlah dengan OAuth 2.0 Playground.
Halaman ini memberikan ringkasan tentang skenario otorisasi OAuth 2.0 yang didukung Google, dan menyediakan link ke konten yang lebih mendetail. Untuk mengetahui detail tentang penggunaan OAuth 2.0 untuk autentikasi, lihat OpenID Connect.
Langkah dasar
Semua aplikasi mengikuti pola dasar saat mengakses Google API menggunakan OAuth 2.0. Pada intinya, Anda perlu mengikuti lima langkah:
1. Dapatkan kredensial OAuth 2.0 dari Konsol API Google.
Buka Konsol API Google untuk mendapatkan kredensial OAuth 2.0 seperti client ID dan rahasia klien yang diketahui oleh Google dan aplikasi Anda. Kumpulan nilai akan bervariasi berdasarkan jenis aplikasi yang Anda buat. Misalnya, aplikasi JavaScript tidak memerlukan rahasia, tetapi aplikasi server web memerlukannya.
Anda harus membuat klien OAuth yang sesuai untuk platform tempat aplikasi Anda akan berjalan, misalnya:
-
Untuk aplikasi Android, gunakan
Android . -
Untuk aplikasi iOS dan macOS, gunakan
jenis klien iOS . -
code
Untuk aplikasi web sisi server atau JavaScript, gunakan
jenis klien
Aplikasi web . Jangan gunakan jenis klien ini untuk aplikasi lain, seperti aplikasi native atau seluler. - chrome_extension Untuk ekstensi Chrome, gunakan jenis klien Ekstensi Chrome.
-
tv
Untuk perangkat input terbatas, seperti TV atau perangkat tersemat, gunakan jenis klien
TV dan Perangkat Input Terbatas . - host Untuk interaksi server ke server, gunakan akun layanan. Tidak diperlukan Client ID OAuth.
2. Dapatkan token akses dari Server Otorisasi Google.
Sebelum dapat mengakses data pribadi menggunakan Google API, aplikasi Anda harus mendapatkan an
token akses yang memberikan akses ke API tersebut. Satu token akses dapat memberikan berbagai tingkat
akses ke beberapa API. Parameter variabel yang disebut scope mengontrol kumpulan
resource dan operasi yang diizinkan oleh token akses. Selama permintaan token akses,
aplikasi Anda mengirimkan satu atau beberapa nilai dalam parameter scope.
Ada beberapa cara untuk membuat permintaan ini, dan cara tersebut bervariasi berdasarkan jenis aplikasi yang Anda buat. Misalnya, aplikasi JavaScript mungkin meminta token akses menggunakan pengalihan browser ke Google, sedangkan aplikasi yang diinstal di perangkat yang tidak memiliki browser menggunakan permintaan layanan web. Untuk mengetahui informasi selengkapnya tentang cara membuat permintaan, lihat Scenarios dan panduan penerapan mendetail untuk setiap jenis aplikasi.
Beberapa permintaan memerlukan langkah autentikasi saat pengguna login dengan Akun Google akunnya. Setelah login, pengguna akan ditanya apakah mereka bersedia memberikan satu atau beberapa izin yang diminta oleh aplikasi Anda. Proses ini disebut izin pengguna.
Jika pengguna memberikan setidaknya satu izin, Server Otorisasi Google akan mengirimkan aplikasi Anda token akses (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 akan menampilkan error.
Sebaiknya minta cakupan secara bertahap, pada saat akses diperlukan, bukan di awal. Misalnya, aplikasi yang ingin mendukung penyimpanan acara ke kalender tidak boleh meminta akses Google Kalender hingga pengguna menekan tombol "Tambahkan ke Kalender"; lihat Otorisasi bertahap.
3. Periksa cakupan akses yang diberikan oleh pengguna.
Bandingkan cakupan yang disertakan dalam respons token akses dengan cakupan yang diperlukan untuk mengakses fitur dan fungsi aplikasi Anda yang bergantung pada akses ke Google API terkait. Nonaktifkan 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, bahkan
jika 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, yang menampilkan string cakupan yang sama untuk semua nilai yang diizinkan dalam permintaan.
Contoh: Google People API dapat menampilkan cakupan
https://www.googleapis.com/auth/contacts saat aplikasi meminta pengguna mengotorisasi
cakupan https://www.google.com/m8/feeds/; metode Google People API
people.updateContact
memerlukan cakupan https://www.googleapis.com/auth/contacts yang diberikan.
4. Kirim token akses ke API.
Setelah mendapatkan token akses, aplikasi akan mengirimkan token ke Google API di header permintaan Otorisasi HTTP. Token dapat dikirim sebagai parameter string kueri URI, tetapi kami tidak merekomendasikannya, karena parameter URI dapat berakhir di file log yang tidak sepenuhnya aman. Selain itu, sebaiknya hindari pembuatan nama parameter URI yang tidak diperlukan.
Token akses hanya berlaku untuk kumpulan operasi dan resource yang dijelaskan dalam
scope permintaan token. Misalnya, jika token akses dikeluarkan untuk Google Calendar API, token tersebut tidak memberikan akses ke Google Contacts API. Namun, Anda dapat mengirim token akses tersebut ke Google Calendar API beberapa kali untuk operasi serupa.
5. Perbarui token akses, jika diperlukan.
Token akses memiliki masa berlaku terbatas. Jika aplikasi Anda memerlukan akses ke Google API di luar masa berlaku satu token akses, aplikasi tersebut dapat memperoleh token refresh. Token refresh memungkinkan aplikasi Anda mendapatkan token akses baru.
Scenarios
Skenario ini menjelaskan cara menggunakan OAuth 2.0 untuk meminta kode otorisasi dan mendapatkan token akses dan refresh untuk berbagai jenis aplikasi.
Aplikasi server web
Endpoint Google OAuth 2.0 mendukung aplikasi server web yang menggunakan bahasa dan framework seperti PHP, Java, Go, Python, Ruby, dan ASP.NET.
Urutan otorisasi dimulai saat aplikasi Anda mengalihkan browser ke URL Google ; URL tersebut menyertakan parameter kueri yang menunjukkan jenis akses yang diminta. Google menangani autentikasi pengguna, pemilihan sesi, dan izin pengguna. Hasilnya adalah kode otorisasi, yang dapat ditukar oleh aplikasi dengan token akses dan token refresh.
Aplikasi harus menyimpan token refresh untuk penggunaan di masa mendatang dan menggunakan token akses untuk mengakses Google API. Setelah masa berlaku token akses berakhir, aplikasi akan menggunakan token refresh untuk mendapatkan token baru.
Untuk mengetahui detailnya, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server Web.
Aplikasi terpasang
Endpoint Google OAuth 2.0 mendukung aplikasi yang diinstal di perangkat seperti komputer, perangkat seluler, dan tablet. Saat membuat client ID melalui Konsol API Google, tentukan bahwa ini adalah aplikasi Terinstal, lalu pilih aplikasi Android, Ekstensi Chrome, iOS, atau Desktop sebagai jenis aplikasi.
Proses ini menghasilkan client ID 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 tersebut menyertakan parameter kueri yang menunjukkan jenis akses yang diminta. Google menangani autentikasi pengguna, pemilihan sesi, dan izin pengguna. Hasilnya adalah kode otorisasi, yang dapat ditukar oleh aplikasi dengan token akses. Aplikasi harus memvalidasi token akses sebelum menyertakannya dalam permintaan Google API permintaan. Saat masa berlaku token berakhir, aplikasi akan mengulangi prosesnya.
Secara opsional, server backend dapat menukar kode otorisasi dengan token refresh, menyimpannya di lokasi yang aman. Setelah masa berlaku token akses berakhir, server backend akan menggunakan token refresh untuk mendapatkan token baru bagi aplikasi.
Untuk mengetahui detailnya, lihat Mengotorisasi akses ke data pengguna Google untuk Android, dan OAuth 2.0 untuk Aplikasi iOS & Desktop.
Aplikasi sisi klien (JavaScript)
Endpoint Google OAuth 2.0 mendukung aplikasi JavaScript yang berjalan di browser.
Urutan otorisasi dimulai saat aplikasi Anda mengalihkan browser ke URL Google ; URL tersebut menyertakan parameter kueri yang menunjukkan jenis akses yang diminta. Google menangani autentikasi pengguna, pemilihan sesi, dan izin pengguna.
Hasilnya adalah token akses, yang harus divalidasi oleh klien sebelum menyertakannya dalam permintaan Google API. Saat masa berlaku token berakhir, aplikasi akan mengulangi prosesnya.
Untuk mengetahui detailnya, lihat Menggunakan OAuth 2.0 untuk Aplikasi Sisi Klien.
Aplikasi pada perangkat input terbatas
Endpoint Google OAuth 2.0 mendukung aplikasi yang berjalan di perangkat input terbatas seperti konsol game, kamera video, dan printer.
Urutan otorisasi dimulai dengan aplikasi yang membuat permintaan layanan web ke a Google URL untuk kode otorisasi. Respons berisi beberapa parameter, termasuk a URL dan kode yang ditampilkan aplikasi kepada pengguna.
Pengguna mendapatkan URL dan kode dari perangkat, lalu beralih ke perangkat atau komputer terpisah dengan kemampuan input yang lebih lengkap. Pengguna meluncurkan browser, membuka URL yang ditentukan, login, dan memasukkan kode.
Sementara itu, aplikasi melakukan polling URL Google pada interval yang ditentukan. Setelah pengguna menyetujui akses, respons dari server Google akan berisi token akses dan token refresh. Aplikasi harus menyimpan token refresh untuk penggunaan di masa mendatang dan menggunakan token akses untuk mengakses Google API. Setelah masa berlaku token akses berakhir, aplikasi akan menggunakan token refresh untuk mendapatkan token baru.
Untuk mengetahui detailnya, 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 tidak diperlukan izin pengguna. Demikian pula, dalam skenario perusahaan, aplikasi Anda dapat meminta akses yang didelegasikan ke beberapa resource.
Untuk jenis interaksi server ke server ini, Anda memerlukan akun layanan, yaitu akun milik aplikasi Anda, bukan milik pengguna akhir individu. Aplikasi Anda memanggil Google API atas nama akun layanan, dan izin pengguna tidak diperlukan. (Dalam skenario non-akun layanan, aplikasi Anda memanggil Google API atas nama pengguna akhir, dan izin pengguna terkadang diperlukan.)
Kredensial akun layanan, yang Anda dapatkan dari Konsol API Google, mencakup alamat email yang dibuat dan unik, client ID, dan setidaknya satu pasangan kunci publik/pribadi. Anda menggunakan client ID 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 menampilkan token akses. Aplikasi menggunakan token untuk mengakses Google API. Saat masa berlaku token berakhir, aplikasi akan mengulangi prosesnya.
Untuk mengetahui detailnya, lihat dokumentasi akun layanan.
Ukuran token
Ukuran token dapat bervariasi, hingga batas berikut:
Token akses yang ditampilkan oleh Security Token Service API Google Cloud disusun mirip dengan token akses OAuth 2.0 Google API, tetapi memiliki batas ukuran token yang berbeda. Untuk mengetahui detailnya, lihat dokumentasi API.
Google berhak mengubah ukuran token dalam batas ini, dan aplikasi Anda harus mendukung ukuran token variabel.
Masa berlaku token refresh
Anda harus menulis kode untuk mengantisipasi kemungkinan token refresh yang diberikan mungkin tidak lagi berfungsi. Token refresh mungkin berhenti berfungsi karena salah satu alasan berikut:
Project Google Cloud Platform dengan layar izin OAuth yang dikonfigurasi untuk jenis pengguna eksternal
dan status publikasi "Pengujian" akan diberi token refresh yang masa berlakunya berakhir dalam
7 hari, kecuali jika satu-satunya cakupan OAuth yang diminta adalah subset nama, alamat email, dan
profil pengguna (melalui cakupan
userinfo.email, userinfo.profile, openid, atau OpenID Connect yang setara).
Saat ini, batasnya adalah 100 token refresh per Akun Google per client ID OAuth 2.0. Jika batas tersebut tercapai, pembuatan token refresh baru akan otomatis membatalkan token refresh terlama tanpa peringatan. Batas ini tidak berlaku untuk akun layanan.
Ada juga batas yang lebih besar pada jumlah total token refresh yang dapat dimiliki akun pengguna atau akun layanan di semua klien. Sebagian besar pengguna normal tidak akan melebihi batas ini, tetapi akun developer yang digunakan untuk menguji penerapan mungkin akan melebihi batas ini.
Jika Anda perlu mengotorisasi beberapa program, mesin, atau perangkat, salah satu solusinya adalah membatasi jumlah klien yang Anda otorisasi per Akun Google menjadi 15 atau 20. Jika Anda adalah admin Google Workspace, Anda dapat membuat pengguna tambahan dengan hak administratif dan menggunakannya untuk mengotorisasi beberapa klien.
Menangani kebijakan kontrol sesi untuk organisasi Google Cloud Platform (GCP)
Administrator organisasi GCP mungkin memerlukan autentikasi ulang pengguna yang sering saat mereka mengakses resource GCP, menggunakan fitur kontrol sesi Google Cloud. Kebijakan ini memengaruhi akses ke Konsol Google Cloud, Google Cloud SDK (juga dikenal sebagai gcloud
CLI), dan aplikasi OAuth pihak ketiga yang memerlukan cakupan Cloud Platform. Jika pengguna memiliki kebijakan kontrol sesi, saat durasi sesi berakhir, panggilan API Anda akan menampilkan error yang mirip dengan yang akan terjadi jika token refresh dicabut - panggilan akan gagal dengan jenis error invalid_grant; kolom error_subtype dapat digunakan untuk membedakan antara token yang dicabut dan kegagalan karena kebijakan kontrol sesi (misalnya, "error_subtype": "invalid_rapt"). Karena durasi sesi dapat sangat terbatas (antara 1 jam hingga 24 jam), skenario ini harus ditangani dengan baik dengan memulai ulang sesi autentikasi.
Demikian pula, Anda tidak boleh menggunakan, atau mendorong penggunaan, kredensial pengguna untuk deployment server ke server. Jika kredensial pengguna di-deploy di server untuk tugas atau operasi yang berjalan lama dan pelanggan menerapkan kebijakan kontrol sesi pada pengguna tersebut, aplikasi server akan gagal karena tidak ada cara untuk melakukan autentikasi ulang pengguna saat durasi sesi berakhir.
Untuk mengetahui informasi selengkapnya tentang cara membantu pelanggan Anda men-deploy fitur ini, lihat artikel bantuan yang berfokus pada admin ini.
Library klien
Library klien berikut terintegrasi dengan framework populer, yang membuat penerapan OAuth 2.0 menjadi lebih sederhana. Fitur lainnya akan ditambahkan ke library seiring waktu.
- Library Google Auth untuk Java
- Library Klien Google API untuk Python
- Library Klien Google API untuk Dart
- Library Klien Google API untuk Go
- Library Klien Google API untuk .NET
- Library Klien Google API untuk Ruby
- Library Klien Google API untuk PHP
- Library Klien Google API untuk JavaScript
- GTMAppAuth - Library Klien OAuth untuk Mac dan iOS