Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan OAuth 2.0 untuk Mengakses Google API

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

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

Halaman ini menyediakan ringkasan 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 tingkat tinggi, Anda mengikuti lima langkah:

1. Dapatkan kredensial OAuth 2.0 dari Google API Console.

Buka Google API Console untuk mendapatkan kredensial OAuth 2.0, seperti client ID dan rahasia klien yang diketahui Google dan aplikasi Anda. Rangkaian nilai ini 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 sisi server atau aplikasi web JavaScript, gunakan jenis klien "web". Jangan gunakan jenis klien ini untuk aplikasi lain, seperti aplikasi native atau seluler.
Untuk aplikasi Android, gunakan jenis klien "Android".
Untuk aplikasi iOS dan macOS, gunakan jenis klien "iOS".
Untuk aplikasi Universal Windows Platform, gunakan jenis klien "Universal Windows Platform".
Untuk perangkat input terbatas, seperti TV atau perangkat sematan, gunakan jenis klien "TV dan Perangkat Input Terbatas".
Untuk interaksi server ke server, gunakan akun layanan.

2. Mendapatkan token akses dari Server Otorisasi Google.

Sebelum dapat mengakses data pribadi menggunakan Google API, aplikasi Anda harus mendapatkan 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 akan mengirim satu atau beberapa nilai dalam parameter scope.

Ada beberapa cara untuk membuat permintaan ini, dan permintaan tersebut bervariasi berdasarkan jenis aplikasi yang Anda build. Misalnya, aplikasi JavaScript mungkin meminta token akses menggunakan pengalihan browser ke Google, sementara aplikasi yang diinstal di perangkat yang tidak memiliki browser menggunakan permintaan layanan web.

Beberapa permintaan memerlukan langkah autentikasi yang memungkinkan pengguna login dengan Akun Google-nya. Setelah login, pengguna ditanya apakah mereka bersedia memberikan satu atau beberapa izin yang diminta aplikasi Anda. Proses ini disebut izin pengguna.

Jika pengguna memberikan setidaknya satu izin, Server Otorisasi Google akan mengirim token akses (atau kode otorisasi yang dapat digunakan aplikasi Anda untuk mendapatkan token akses) dan daftar cakupan akses yang diberikan oleh token tersebut ke aplikasi Anda. Jika pengguna tidak memberikan izin, server akan menampilkan error.

Secara umum, praktik terbaik adalah meminta cakupan secara bertahap, tetapi 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 inkremental.

3. Memeriksa 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, bergantung pada akses ke Google API terkait. Menonaktifkan fitur apa pun pada 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 setiap Google API untuk mengetahui 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 untuk memberi otorisasi cakupan https://www.google.com/m8/feeds/; metode Google People API people.updateContact memerlukan cakupan https://www.googleapis.com/auth/contacts yang diberikan.

4. Mengirim token akses ke API.

Setelah aplikasi mendapatkan token akses, aplikasi akan mengirim token tersebut ke Google API di header permintaan Otorisasi HTTP. Anda dapat 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 dengan menghindari pembuatan nama parameter URI yang tidak perlu.

Token akses hanya valid untuk rangkaian operasi dan resource yang dijelaskan dalam scope permintaan token. Misalnya, jika token akses dikeluarkan untuk Google Calendar API, token tersebut tidak akan memberikan akses ke Google Contacts API. Namun, Anda dapat mengirim token akses tersebut ke Google Kalender API beberapa kali untuk operasi yang serupa.

5. Muat ulang token akses, jika perlu.

Token akses memiliki masa berlaku terbatas. Jika aplikasi Anda memerlukan akses ke Google API setelah masa berlaku satu token akses, aplikasi dapat memperoleh token refresh. Token refresh memungkinkan aplikasi Anda mendapatkan token akses baru.

Skenario

Aplikasi server web

Endpoint Google OAuth 2.0 mendukung aplikasi server web yang menggunakan bahasa dan framework seperti PHP, Java, 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, pilihan sesi, dan izin pengguna. Hasilnya adalah kode otorisasi, yang dapat ditukarkan dengan token akses dan token refresh.

Aplikasi harus menyimpan token refresh untuk digunakan 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.

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

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 Anda membuat client ID melalui Google API Console, tentukan bahwa ini adalah Aplikasi terinstal, lalu pilih aplikasi Android, Chrome, iOS, Universal Windows Platform (UWP), 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.)

Untuk mengetahui detailnya, lihat Menggunakan OAuth 2.0 untuk Aplikasi yang Diinstal.

Aplikasi sisi klien (JavaScript)

Endpoint Google OAuth 2.0 mendukung aplikasi JavaScript yang berjalan di browser.

Hasilnya adalah token akses, yang harus divalidasi klien sebelum menyertakannya dalam permintaan Google API. Setelah masa berlaku token habis, aplikasi akan mengulangi proses ini.

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

Untuk mengetahui detailnya, lihat Menggunakan OAuth 2.0 untuk Aplikasi Sisi Klien.

Aplikasi di perangkat dengan input terbatas

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

Urutan otorisasi dimulai dengan aplikasi yang membuat permintaan layanan web ke URL Google untuk kode otorisasi. Responsnya 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 lain dengan kemampuan input yang lebih kaya. Pengguna meluncurkan browser, membuka URL yang ditentukan, login, lalu 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 refresh. Aplikasi harus menyimpan token refresh untuk digunakan 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.

Pengguna login di perangkat terpisah yang memiliki browser

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 harus membuktikan identitasnya sendiri ke API tersebut, tetapi izin pengguna tidak diperlukan. 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, yang merupakan 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 terkadang izin pengguna diperlukan.)

Kredensial akun layanan, yang Anda peroleh dari Google API Console, mencakup alamat email yang dibuat secara 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. Setelah masa berlaku token habis, aplikasi akan mengulangi proses ini.

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

Untuk mengetahui detailnya, lihat dokumentasi akun layanan.

Ukuran token

Ukuran token dapat bervariasi, hingga batas berikut:

Kode otorisasi: 256 byte
Token akses: 2048 byte
Token refresh: 512 byte

Token akses yang ditampilkan oleh Security Token Service API Google Cloud memiliki struktur yang 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 sesuai batas ini, dan aplikasi Anda harus mendukung berbagai ukuran token variabel.

Masa berlaku token refresh

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

Pengguna telah mencabut akses aplikasi.
Token refresh tidak digunakan selama enam bulan.
Pengguna mengubah sandi dan token refresh berisi cakupan Gmail.
Akun pengguna telah melampaui jumlah maksimum token refresh (live) yang diperbarui.
Jika admin menetapkan salah satu layanan yang diminta dalam cakupan aplikasi ke Dibatasi (errornya adalah admin_policy_enforced).
Untuk Google Cloud Platform API - durasi sesi yang ditetapkan oleh admin mungkin telah terlampaui.

Project Google Cloud Platform dengan layar izin OAuth yang dikonfigurasi untuk jenis pengguna eksternal dan status publikasi "Pengujian" akan dikeluarkan token refresh yang masa berlakunya akan 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 setara OpenID Connect).

Saat ini ada batas 100 token refresh per Akun Google per client ID OAuth 2.0. Jika batas tersebut tercapai, membuat 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 seluruh klien. Sebagian besar pengguna normal tidak akan melampaui batas ini, tetapi akun developer yang digunakan untuk menguji penerapan mungkin akan terlampaui.

Jika Anda perlu memberikan otorisasi ke beberapa program, mesin, atau perangkat, salah satu solusinya adalah membatasi jumlah klien yang Anda beri otorisasi per Akun Google hingga 15 atau 20 klien. Jika Anda adalah admin Google Workspace, Anda dapat membuat pengguna tambahan dengan hak istimewa administratif dan menggunakannya untuk memberi otorisasi 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 Google Cloud Console, Google Cloud SDK (juga dikenal sebagai gcloud CLI), dan aplikasi OAuth pihak ketiga apa pun yang memerlukan cakupan Cloud Platform. Jika pengguna menerapkan kebijakan kontrol sesi, pada akhir durasi sesi, panggilan API Anda akan mengalami error yang serupa 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 menjadi sangat terbatas (antara 1 jam hingga 2 jam, durasi autentikasi harus ditangani dengan baik).

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 mengautentikasi ulang pengguna saat durasi sesi berakhir.

Untuk informasi selengkapnya tentang cara membantu pelanggan men-deploy fitur ini, lihat artikel bantuan yang berfokus pada admin.

Library klien

Library klien berikut terintegrasi dengan framework populer, yang mempermudah penerapan OAuth 2.0. Seiring waktu, lebih banyak fitur akan ditambahkan ke library.