OAuth Itu Seperti Surat Kuasa: Cara Kerja Izin Akses Aplikasi, Scope, Access Token, dan Refresh Token

OAuth 2.0 adalah standar otorisasi yang membuat sebuah aplikasi bisa mengakses akun Anda di layanan lain secara terbatas, tanpa pernah memegang password Anda. Analogi paling gampang: OAuth itu seperti surat kuasa. Saat Anda meminta orang lain mengurus dokumen di kantor layanan, Anda tidak menyerahkan KTP, kunci rumah, dan PIN ATM sekaligus. Anda menulis surat kuasa yang menyebut satu urusan, berlaku sampai tanggal tertentu, dan bisa dicabut.

Setiap kali Anda menekan tombol "Lanjutkan dengan Google" atau "Hubungkan akun GitHub", yang bekerja di belakangnya adalah OAuth. Artikel ini membahas siapa saja yang terlibat, enam langkah alurnya, bedanya access token dan refresh token, fungsi PKCE, serta beberapa salah paham yang sering muncul di kalangan pemula.

Ringkasan cepat: istilah apa saja yang perlu Anda tahu?

Ada delapan istilah yang hampir selalu muncul saat membahas OAuth, dan semuanya bisa dijelaskan dengan surat kuasa.

Istilah	Artinya	Analogi surat kuasa
Resource owner	Pemilik akun, yaitu Anda	Pemberi kuasa
Client	Aplikasi yang meminta akses	Penerima kuasa
Authorization server	Server yang meminta persetujuan Anda dan menerbitkan token	Loket resmi yang mengesahkan surat
Resource server	API tempat data Anda disimpan	Petugas yang memeriksa surat sebelum melayani
Scope	Daftar izin yang diminta, misalnya hanya membaca email	Kalimat "khusus untuk mengurus..."
Authorization code	Kode sementara sekali pakai untuk ditukar dengan token	Nomor antrean di loket
Access token	Kredensial yang dikirim di setiap request ke API	Surat kuasa yang ditunjukkan ke petugas
Refresh token	Kredensial untuk meminta access token baru	Hak memperpanjang surat tanpa memanggil Anda

Empat peran di baris pertama berasal langsung dari RFC 6749, dokumen standar OAuth 2.0 yang terbit pada Oktober 2012.

Apa itu OAuth dan masalah apa yang diselesaikannya?

OAuth menyelesaikan satu masalah lama: cara memberi akses ke aplikasi pihak ketiga tanpa membagikan password. Sebelum OAuth umum dipakai, aplikasi yang ingin membaca kontak email Anda biasanya meminta alamat email dan password, lalu login sebagai Anda.

Cara lama itu punya tiga kelemahan. Pertama, aplikasi memegang akses penuh, padahal hanya butuh daftar kontak. Kedua, satu-satunya cara mencabut akses adalah mengganti password, dan itu memutus semua aplikasi lain sekaligus. Ketiga, bila aplikasi tersebut dibobol, password asli Anda ikut bocor.

RFC 6749 merumuskan tujuannya dengan singkat: OAuth memungkinkan aplikasi pihak ketiga memperoleh akses terbatas ke sebuah layanan HTTP. Kata kuncinya adalah "terbatas".

Bagaimana cara kerja OAuth langkah demi langkah?

Alur yang paling umum bernama authorization code, dan isinya enam langkah: aplikasi mengalihkan Anda ke server otorisasi, Anda login dan setuju di sana, lalu aplikasi menukar kode yang diterimanya dengan access token.

1. Anda menekan tombol hubungkan. Aplikasi menyiapkan permintaan izin.
2. Browser dialihkan ke server otorisasi. URL-nya memuat client_id (identitas aplikasi), scope (izin yang diminta), redirect_uri (alamat kembali), dan state (nilai acak pencegah pemalsuan permintaan).
3. Anda login dan menyetujui. Password diketik di halaman milik penyedia akun, bukan di aplikasi. Layar izin menampilkan apa saja yang diminta, dan Anda boleh menolak.
4. Browser kembali ke aplikasi membawa authorization code. Kode ini wajib berumur pendek. RFC 6749 menyarankan maksimal 10 menit dan melarang pemakaian lebih dari sekali.
5. Aplikasi menukar kode dengan token. Pertukaran terjadi langsung antara server aplikasi dan server otorisasi, tidak lewat browser.
6. Aplikasi memanggil API. Setiap request membawa header Authorization: Bearer <access_token>.

Seperti apa URL di langkah 2?

URL izin hanyalah alamat biasa dengan beberapa parameter. Skrip Python berikut membuatnya, lengkap dengan pasangan PKCE yang dibahas di bawah. Skrip ini sudah kami jalankan dengan Python 3 tanpa pustaka tambahan, dan fungsi buat_pkce menghasilkan nilai yang sama dengan contoh resmi di Lampiran B RFC 7636. Nama domain dan scope hanya contoh.

import base64, hashlib, secrets
from urllib.parse import urlencode

def buat_pkce():
    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
    digest = hashlib.sha256(verifier.encode("ascii")).digest()
    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
    return verifier, challenge

verifier, challenge = buat_pkce()   # verifier disimpan aplikasi, jangan dikirim dulu
state = secrets.token_urlsafe(16)   # dicocokkan lagi saat browser kembali

url = "https://auth.contoh.id/authorize?" + urlencode({
    "response_type": "code",
    "client_id": "aplikasi-saya",
    "redirect_uri": "https://aplikasi.contoh.id/callback",
    "scope": "email.baca kalender.tulis",
    "state": state,
    "code_challenge": challenge,
    "code_challenge_method": "S256",
})
print(url)

Apa bedanya authorization code, access token, dan refresh token?

Ketiganya berbeda tugas dan berbeda umur: authorization code hanya penukar sekali pakai, access token dipakai di setiap request, dan refresh token dipakai untuk meminta access token baru.

Benda	Dikirim ke mana	Umur	Kalau bocor
Authorization code	Server otorisasi, satu kali	Sangat pendek, disarankan maksimal 10 menit	Tidak berguna tanpa code_verifier bila PKCE dipakai
Access token	API, di setiap request	Pendek, ditentukan penyedia	Bisa dipakai sampai kedaluwarsa, sebatas scope-nya
Refresh token	Server otorisasi saja	Panjang, sampai dicabut atau kedaluwarsa	Paling berbahaya, karena bisa mencetak access token baru

Umur access token tidak ditetapkan oleh standar. Contoh respons di RFC 6749 memakai "expires_in": 3600, artinya satu jam, tetapi tiap penyedia bebas memilih angkanya. Karena itu, baca nilai expires_in dari respons dan jangan menuliskan angka tetap di kode.

Apa fungsi scope di OAuth?

Scope adalah daftar izin yang membatasi apa saja yang boleh dilakukan aplikasi dengan token-nya. Token dengan scope "baca email" akan ditolak API ketika dipakai untuk mengirim email atau menghapus berkas.

Praktik yang baik adalah meminta scope sesedikit mungkin dan memintanya saat benar-benar dibutuhkan. Aplikasi kasir yang hanya perlu membuat acara di kalender tidak punya alasan meminta izin membaca seluruh kotak masuk. Bagi pengguna, layar izin yang pendek juga lebih mudah dipercaya.

Apa itu PKCE dan kenapa sekarang wajib?

PKCE (dibaca "pixy") adalah pengaman tambahan yang memastikan hanya aplikasi yang memulai permintaan yang bisa menukar authorization code menjadi token. PKCE didefinisikan di RFC 7636 yang terbit pada September 2015.

Cara kerjanya mirip tiket penitipan helm yang disobek dua. Di langkah 1, aplikasi membuat string acak bernama code_verifier dan menyimpannya. Yang dikirim ke server otorisasi hanya sidik jarinya, yaitu code_challenge, hasil SHA-256 dari verifier. Di langkah 5, aplikasi menyerahkan code_verifier yang asli. Server mencocokkan kedua sobekan. Pencuri yang berhasil menyadap authorization code di tengah jalan tidak punya sobekan satunya, jadi kodenya tidak bisa ditukar.

RFC 9700, panduan praktik keamanan OAuth 2.0 yang terbit pada Januari 2025, mewajibkan PKCE untuk public client seperti aplikasi mobile dan aplikasi web satu halaman, serta menganjurkannya untuk aplikasi yang berjalan di server.

Apa yang sering disalahpahami tentang OAuth?

Salah paham yang paling umum adalah menganggap OAuth sebagai sistem login, padahal OAuth mengatur izin akses, bukan identitas. Berikut lima yang paling sering kami temui.

• "OAuth itu login." OAuth menjawab pertanyaan "aplikasi ini boleh melakukan apa", bukan "siapa pengguna ini". Tombol "Lanjutkan dengan Google" memakai OpenID Connect, lapisan identitas yang dibangun di atas OAuth 2.0 dan menambahkan ID token berisi data login pengguna.
• "Access token sama dengan API key." API key mewakili aplikasi atau akun developer dan biasanya berumur panjang. Access token mewakili izin dari satu pengguna, dibatasi scope, dan cepat kedaluwarsa.
• "Aplikasi tetap tahu password saya." Tidak, selama Anda mengetiknya di halaman resmi penyedia akun. Biasakan memeriksa alamat di bilah browser sebelum mengetik password.
• "Sekali disetujui, berlaku selamanya." Izin bisa dicabut kapan saja dari halaman keamanan akun Anda, dan refresh token bisa berhenti berfungsi karena berbagai sebab, misalnya lama tidak dipakai.
• "Semua alur OAuth sama amannya." RFC 9700 melarang alur yang meminta aplikasi mengumpulkan password pengguna secara langsung, dan menyarankan agar alur implicit tidak dipakai lagi. Untuk aplikasi baru, pilih authorization code dengan PKCE.

Di mana OAuth dipakai di APIPedia?

APIPedia memakai OAuth di fitur Koneksi, yaitu saat Anda menghubungkan akun Gmail, Google Calendar, Google Workspace, LinkedIn, atau GitHub supaya bisa dipakai lewat API dan server MCP. Anda tidak menyerahkan password akun-akun itu ke APIPedia.

Alurnya mengikuti enam langkah di atas, dan bagian rumitnya sudah diurus oleh gateway:

1. Panggil POST /v1/connections/{toolkit}/initiate dengan API key APIPedia Anda. Responsnya berisi tautan persetujuan.
2. Buka tautan itu di browser, login di halaman penyedia akun, lalu setujui izinnya.
3. Cek hasilnya lewat GET /v1/connections/{toolkit}/status, atau lihat semua koneksi lewat GET /v1/connections.
4. Bila sudah tidak dipakai, cabut dengan DELETE /v1/connections/{toolkit}.

Di sini terlihat jelas pembagian tugas dua jenis kredensial. API key APIPedia mengenali siapa Anda sebagai developer. Token OAuth, yang disimpan di sisi gateway, mewakili izin atas akun yang Anda hubungkan.

Tips praktis memakai OAuth dengan aman

Lima kebiasaan berikut menutup sebagian besar celah yang biasa muncul di integrasi OAuth buatan pemula.

1. Minta scope seperlunya. Tambah izin baru hanya saat fiturnya benar-benar dipakai pengguna.
2. Selalu pakai dan periksa state. Tolak balasan yang nilai state-nya tidak cocok dengan yang Anda kirim.
3. Daftarkan redirect_uri secara persis. RFC 9700 meminta server otorisasi mencocokkan alamat ini karakter demi karakter, jadi hindari pola yang longgar.
4. Simpan refresh token di server. Jangan menaruhnya di kode frontend, repositori Git, atau log aplikasi.
5. Siapkan jalur "token ditolak". Saat API menjawab 401, coba perbarui access token sekali. Bila gagal, minta pengguna menghubungkan ulang akunnya dengan pesan yang jelas.

Pertanyaan yang sering diajukan

Apakah OAuth sama dengan login Google?

Tidak persis. Login Google memakai OpenID Connect, yang berjalan di atas OAuth 2.0. OAuth sendiri hanya mengatur izin akses ke data, sedangkan OpenID Connect menambahkan informasi tentang siapa penggunanya.

Apa bedanya OAuth dan API key?

API key adalah satu kunci tetap milik developer untuk mengakses layanan atas namanya sendiri. OAuth dipakai ketika aplikasi perlu bertindak atas akun milik orang lain, dengan izin yang dibatasi scope dan bisa dicabut oleh pemilik akun.

Berapa lama access token berlaku?

Tergantung penyedia layanannya, karena standar OAuth tidak menetapkan angka. Umumnya hitungan menit sampai jam. Nilai pastinya ada di field expires_in pada respons token.

Apakah OAuth 2.0 masih aman dipakai?

Ya, asalkan mengikuti praktik terbaru di RFC 9700: pakai alur authorization code dengan PKCE, cocokkan redirect_uri secara persis, dan hindari alur implicit maupun alur yang mengumpulkan password pengguna.

Bagaimana cara mencabut akses aplikasi yang sudah saya setujui?

Buka halaman keamanan atau "aplikasi pihak ketiga" di akun penyedia layanan, lalu hapus aplikasi yang dimaksud. Akses aplikasi itu berhenti tanpa Anda perlu mengganti password.

Ingin melihat OAuth dipakai untuk menghubungkan alat ke agen AI? Baca apa itu MCP dan bedanya dengan API biasa serta panduan menghubungkan APIPedia ke Claude lewat MCP. Untuk memahami risiko saat kredensial bocor, baca juga LLMjacking: API key AI dicuri.

Sumber

• RFC 6749: The OAuth 2.0 Authorization Framework
• RFC 7636: Proof Key for Code Exchange by OAuth Public Clients (PKCE)
• RFC 9700: Best Current Practice for OAuth 2.0 Security
• OpenID Connect Core 1.0
• Google for Developers: Using OAuth 2.0 to Access Google APIs