OAuth untuk Agen AI: Memastikan Keamanan saat Mewakili Pengguna

OAuth Terdelegasi untuk Agen AI: Token, Lingkup, Penyegaran, dan Pencabutan

Agen yang membaca kalender pelanggan, mengirim pesan dari akun mereka, atau membuat tiket atas nama mereka tidak boleh memakai satu akun layanan berakses luas. Gunakan otorisasi terdelegasi: pengguna memberi token yang terlingkup dan dapat dicabut, agen bertindak sebagai pengguna itu, dan audit log mencatat identitas yang benar.

Coba Apidog hari ini

OAuth 2.0 dirancang untuk model ini, tetapi alur persetujuan mengasumsikan ada peramban dan manusia yang menekan Izinkan. Solusinya adalah memisahkan waktu koneksi—saat manusia memberi persetujuan—dari waktu berjalan—saat agen memakai pemberian yang sudah ada di latar belakang.

Jika Anda masih memilih antara kunci API dan OAuth, mulai dari perbandingan kunci API vs OAuth. Apidog membantu menguji jalur sukses, kedaluwarsa, dan pencabutan sebelum agen menemukannya di produksi.

Akun layanan vs akses terdelegasi

Pilih model berdasarkan kepemilikan data:

• Akun layanan adalah identitas agen dengan izin sendiri. Gunakan untuk sumber daya Anda: layanan internal, infrastruktur, basis data internal, atau pekerjaan terjadwal. Terapkan prinsip kunci API hak istimewa terkecil untuk agen dan rotasi kredensial.
• Akses terdelegasi membuat agen bertindak sebagai pengguna tertentu, dengan izin pengguna tersebut dan tidak lebih. Gunakan ketika data milik orang lain.

Akses terdelegasi memberi tiga manfaat penting:

1. Pengguna dapat melihat izin yang diberikan.
2. Pengguna dapat mencabut akses kapan saja.
3. Audit log mencatat siapa yang tindakan agen wakili.

Hindari akun layanan seluruh organisasi yang dipakai untuk bertindak “sebagai” pengguna. Satu kredensial yang bocor akan mengekspos semua akun, tanpa pencabutan per pengguna dan tanpa audit trail yang jujur.

Pilih alur OAuth yang tepat

Spesifikasi OAuth 2.0 mendefinisikan beberapa jenis pemberian. Untuk agen, gunakan yang berikut.

Kode otorisasi dengan PKCE

Ini adalah alur utama untuk bertindak sebagai pengguna:

1. Pengguna diarahkan ke penyedia OAuth.
2. Pengguna menyetujui lingkup.
3. Layanan Anda menukar kode otorisasi dengan token.
4. Agen memakai token akses dan token penyegaran hasil pertukaran.

PKCE melindungi pertukaran kode dan merupakan rekomendasi default menurut OAuth 2.0 Security Best Current Practice. Lihat mekanik lengkapnya dalam panduan pemberian kode otorisasi.

Aturan penting: alur ini hanya berjalan sekali saat pengguna menghubungkan akun. Agen tidak pernah menjalankan persetujuan sendiri; agen hanya memakai token penyegaran yang dihasilkan.

Kredensial klien

Gunakan untuk mesin-ke-mesin dan akun layanan. Jangan gunakan untuk bertindak sebagai pengguna karena tidak ada pengguna yang menyetujui akses.

Pemberian otorisasi perangkat

Gunakan untuk agen CLI atau mesin tanpa peramban. Pengguna mendapat kode, lalu menyetujui akses dari perangkat lain seperti ponsel.

Pertukaran token

RFC 8693 memungkinkan Anda menukar token yang lebih luas dengan token yang lebih sempit. Ini cocok untuk sub-agen: berikan token terbatas untuk satu tugas, bukan salinan token pengguna asli.

Dalam sistem multi-agen, pertukaran token membuat kredensial per agen praktis dan mendukung batas yang dijelaskan dalam panduan serah terima multi-agen.

Minta lingkup minimum, per agen

Lingkup adalah nilai utama dari akses terdelegasi. Jangan meminta semua izin yang mungkin dibutuhkan aplikasi.

• Minta hanya izin yang diperlukan agen tertentu. Agen penjadwal membutuhkan akses tulis kalender, bukan email, kontak, atau berkas.
• Minta izin secara bertahap. Awali dengan minimum, lalu minta tambahan saat pengguna meminta fitur yang memerlukannya.
• Gunakan token terpisah untuk setiap agen. Agen riset dan agen penagihan yang bertindak untuk pengguna sama harus memakai token dengan lingkup berbeda.
• Jadikan baca sebagai default. Minta eskalasi eksplisit untuk tulis atau tindakan destruktif.

Pelajari cara penyedia memodelkan izin dalam panduan lingkup OAuth 2. Gabungkan token tulis dengan gerbang persetujuan untuk aksi berisiko tinggi, seperti pola pembatas agen AI.

Simpan, segarkan, dan cabut token dengan benar

Token adalah kredensial. Perlakukan seperti kata sandi.

Penyimpanan

• Enkripsi token penyegaran saat tidak digunakan, idealnya dengan kunci per pengguna.
• Jangan pernah menulis token ke log.
• Jangan pernah memasukkan token ke prompt.
• Jangan pernah membiarkan model melihat token.

Token yang masuk konteks model dapat muncul dalam jejak, ringkasan, log penyedia, atau respons kesalahan. Terapkan penyuntingan di batas eksekutor, sebagaimana dibahas dalam panduan pelacakan panggilan alat agen.

Penyegaran token

Token akses harus berumur pendek. Agen tidak boleh menangani penyegaran sendiri; letakkan manajer token di depan klien HTTP:

class TokenManager:
    def __init__(self, store, provider):
        self.store, self.provider = store, provider

    def access_token(self, user_id, agent_scope):
        rec = self.store.get(user_id, agent_scope)
        if rec.expires_in() > 60:
            return rec.access_token
        fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
        self.store.save(user_id, agent_scope, fresh)   # rotasi: simpan token penyegaran baru
        return fresh.access_token

Terapkan dua aturan:

1. Simpan token penyegaran baru segera. Banyak penyedia merotasi token penyegaran dan membatalkan token lama.
2. Serialkan penyegaran per pengguna. Dua penyegaran bersamaan dapat saling membatalkan saat penyedia melakukan rotasi token.

Pencabutan dan kegagalan autentikasi

Pengguna dapat mencabut akses, token dapat kedaluwarsa, atau administrator dapat menghapus akun. Perlakukan 401 dan 403 sebagai kegagalan terminal:

• Jangan coba ulang kegagalan autentikasi.
• Hentikan pekerjaan terkait.
• Laporkan pengguna dan lingkup yang terdampak.
• Minta pengguna menghubungkan ulang bila diperlukan.

Ikuti pola pesan yang dapat ditindaklanjuti dari panduan desain kesalahan API untuk agen.

Pisahkan waktu koneksi dari waktu berjalan

Persetujuan OAuth membutuhkan manusia. Agen latar belakang tidak.

Rancang alurnya seperti ini:

• Waktu koneksi: pengguna membuka peramban, menyetujui lingkup, dan sistem menyimpan token penyegaran.
• Waktu berjalan: agen memakai pemberian yang telah ada tanpa interaksi manusia.

Rencanakan dua kondisi:

1. Pemberian kedaluwarsa. Deteksi, hentikan eksekusi, dan beri tahu pengguna untuk menghubungkan ulang.
2. Lingkup belum diberikan. Agen harus meminta persetujuan baru, bukan meningkatkan izin sendiri.

Untuk tindakan berisiko tinggi, tambahkan persetujuan saat tindakan akan dilakukan. Token menjawab “bolehkah agen bertindak?”, sedangkan gerbang persetujuan menjawab “haruskah agen bertindak sekarang?”

Uji lima jalur autentikasi di CI

Jangan hanya menguji jalur sukses. Buat mock untuk lima skenario berikut:

1. Jalur sukses: token akses valid dan panggilan berhasil.
2. Token akses kedaluwarsa: API mengembalikan 401, manajer menyegarkan token, lalu panggilan diulang sekali dan berhasil.
3. Token penyegaran dicabut: penyegaran mengembalikan invalid_grant; agen berhenti dan melaporkan masalah.
4. Lingkup tidak memadai: API mengembalikan 403; agen tidak mencoba lagi dan menyebutkan lingkup yang hilang.
5. Penyegaran bersamaan: dua panggilan untuk pengguna sama; hanya satu penyegaran boleh terjadi.

Di Apidog, definisikan endpoint token dan endpoint terlindungi, lalu mock respons sukses maupun error tanpa menyentuh penyedia OAuth asli. Baca juga panduan menjalankan agen terhadap mock, bukan produksi dan pengujian API OAuth 2.

Contoh integrasi

Asisten kalender

Untuk membaca ketersediaan dan menjadwalkan rapat bagi satu pengguna:

• Gunakan akses terdelegasi.
• Minta dua lingkup kalender yang diperlukan.
• Jalankan persetujuan di peramban saat koneksi.
• Gunakan token hasil pemberian untuk pekerjaan latar belakang.

Jika pengguna mencabut akses, eksekusi malam hari harus berhenti dan memberi tahu pengguna—bukan mengulang pemberian yang sudah mati selama seminggu.

Agen dukungan untuk kotak masuk bersama

Jika agen bertindak pada tiket milik tim, identitas perlu dirancang dengan jelas. Bertindak sebagai akun bersama bisa dibenarkan bila sumber daya benar-benar milik tim, tetapi semua balasan akan tampak identik di audit log.

Pilihan yang lebih baik adalah identitas bot dengan lingkup sendiri, ditambah pencatatan manusia yang memicu eksekusi. Dengan begitu, atribusi manusia dan identitas agen tetap jelas.

Agen operasi internal

Untuk mengulang layanan atau membaca dasbor di infrastruktur sendiri, tidak ada data pengguna dan tidak ada delegasi. Gunakan akun layanan berlingkup sempit; fokuskan keamanan pada rotasi dan radius ledakan.

Simpan atribusi manusia

OAuth terdelegasi menjawab “atas nama siapa agen bertindak?”, tetapi belum menjawab “siapa yang meminta tindakan ini?”

Simpan kedua identitas bersama pekerjaan:

• ID pengguna yang tokennya dipakai.
• Nama atau ID agen.
• Lingkup yang digunakan.
• Manusia yang meminta atau menyetujui pekerjaan.
• Pengidentifikasi token, bukan tokennya.

Sistem manajemen pekerjaan adalah tempat alami untuk menyimpan data ini. Misalnya, Sharkly mencatat penanggung jawab manusia bersama Agen atau Kru yang menjalankan pekerjaan; dokumentasinya menjelaskan pemisahan tersebut.

Jangan biarkan model memegang kredensial

Tetapkan satu aturan arsitektur: model tidak pernah melihat token.

Eksekutor HTTP harus menyuntikkan header Authorization setelah model memilih alat dan menghasilkan argumen. Konsekuensinya:

• Skema alat tidak memiliki parameter token.
• Prompt tidak berisi kredensial.
• Respons yang dapat dibaca model sudah menghapus header autentikasi.
• Eksekutor, bukan model, menentukan pengguna dan token untuk eksekusi.

Apa pun yang dilihat model dapat masuk ke ringkasan, handoff, trace, pesan kesalahan, atau jawaban pengguna. Kredensial tidak boleh berada dalam jalur itu.

Daftar periksa implementasi

• [ ] Gunakan akses terdelegasi untuk data pengguna; akun layanan hanya untuk sumber daya sendiri.
• [ ] Gunakan kode otorisasi dengan PKCE saat koneksi dan pemberian perangkat untuk mesin tanpa kepala.
• [ ] Minta lingkup minimum, per agen, lalu eskalasi secara bertahap.
• [ ] Beri sub-agen token hasil pertukaran, bukan salinan token pengguna.
• [ ] Enkripsi token penyegaran dan jangan pernah memasukkannya ke prompt, log, atau trace.
• [ ] Gunakan manajer token; serialkan penyegaran dan simpan token hasil rotasi.
• [ ] Perlakukan 401 dan 403 sebagai terminal.
• [ ] Deteksi pemberian kedaluwarsa dan minta pengguna menghubungkan ulang.
• [ ] Tambahkan persetujuan eksplisit untuk tindakan berisiko tinggi.
• [ ] Uji lima skenario autentikasi terhadap mock di CI.

Otorisasi terdelegasi memang lebih banyak pekerjaan daripada kunci bersama, tetapi pengguna dapat mencabut akses dan audit log menunjukkan siapa melakukan apa. Unduh Apidog untuk membangun serta menguji alur token dan kasus kegagalannya sebelum agen berjalan tanpa pengawasan.

Pertanyaan yang sering diajukan

Bisakah agen menyelesaikan persetujuan OAuth sendiri?

Tidak, dan seharusnya tidak mencoba. Persetujuan harus dilakukan manusia yang memutuskan izin apa yang diberikan. Setelah itu, agen memakai pemberian yang dihasilkan.

Haruskah setiap agen memiliki klien OAuth sendiri?

Gunakan klien terpisah per integrasi produk, lalu token terpisah per agen di dalamnya—biasanya melalui pertukaran token. Klien berbeda membantu bila penyedia menerapkan batas laju per klien atau Anda membutuhkan pencabutan independen.

Apa yang terjadi jika token penyegaran berputar dan token baru hilang?

Pengguna terkunci dan harus menghubungkan ulang. Simpan token penyegaran baru dalam transaksi yang sama saat token lama dipakai, serta serialkan penyegaran per pengguna.

Apakah aman membiarkan model melihat token akses?

Tidak. Token harus disuntikkan oleh eksekutor pada lapisan HTTP. Apa pun yang dilihat model dapat berakhir di trace, ringkasan, atau respons.

Bagaimana mengaudit agen mana yang melakukan apa?

Catat ID pengguna, nama agen, lingkup, dan pengidentifikasi token pada setiap panggilan—jangan pernah mencatat token mentah.

Bagaimana jika penyedia tidak mendukung pertukaran token?

Simpan pemberian terpisah per agen bila penyedia mengizinkannya. Jika tidak, terapkan pembatasan lingkup di gateway Anda sendiri agar panggilan setiap agen difilter ke operasi yang diizinkan sebelum keluar dari jaringan.