Agen Anda perlu membaca kalender pelanggan, mengirim pesan dari akun mereka, atau mengajukan tiket atas nama mereka. Versi singkatnya adalah memegang satu akun layanan dengan akses luas dan bertindak melaluinya. Setiap tindakan muncul sebagai "integrasi", tidak ada yang bisa mengetahui pengguna mana yang memicu apa, dan satu kredensial yang disusupi mengungkap setiap akun yang Anda sentuh.
Versi yang benar adalah otorisasi terdelegasi: pengguna memberikan agen Anda token terlingkup dan dapat dicabut, agen bertindak sebagai pengguna tersebut, dan jejak audit mencatat nama mereka. Inilah alasan OAuth 2.0 dibangun. Yang membuatnya canggung untuk agen adalah bahwa OAuth mengasumsikan peramban dan orang yang hadir untuk mengklik "Izinkan", dan agen berjalan di latar belakang pada jam 3 pagi.
Panduan ini mencakup alur OAuth mana yang cocok untuk agen, cara melingkupi dan menyimpan token, apa yang harus dilakukan tentang penyegaran dan pencabutan, serta cara menguji seluruh jalur tanpa akun langsung. Jika Anda masih memilih antara otorisasi berbasis kunci dan terdelegasi, perbandingan kami mengenai kunci API dan OAuth adalah tempat untuk memulai.
Apidog membantu bagian yang diremehkan tim: melatih setiap cabang alur, termasuk kedaluwarsa dan pencabutan, sebelum agen menemukannya di produksi.
Akun layanan atau akses terdelegasi
Pilihlah dengan cermat, karena kedua model ini gagal dengan cara yang berbeda.
Sebuah akun layanan adalah identitas agen Anda sendiri, dengan izinnya sendiri. Ini cocok untuk pekerjaan yang agen lakukan atas nama Anda: membaca basis data Anda sendiri, memanggil layanan internal Anda sendiri, menjalankan pekerjaan terjadwal terhadap infrastruktur Anda. Lingkupkan secara ketat, seperti dalam postingan kami tentang kunci API hak istimewa terkecil untuk agen, dan rotasi.
Akses terdelegasi adalah agen yang bertindak sebagai pengguna tertentu, dengan izin pengguna tersebut dan tidak lebih. Ini diperlukan setiap kali data milik orang lain. Tiga properti membuatnya sepadan dengan usaha ekstra: pengguna dapat melihat apa yang diberikan, pengguna dapat mencabutnya, dan setiap tindakan membawa identitas mereka di log.
Mode kegagalan yang harus dihindari adalah akun layanan dengan akses seluruh organisasi yang digunakan untuk bertindak "sebagai" pengguna. Ini berfungsi, dan itu berarti satu kredensial yang bocor mengekspos semua orang, tanpa pencabutan per-pengguna dan tanpa jejak audit yang jujur.
Alur mana yang cocok untuk agen
OAuth 2.0 mendefinisikan beberapa jenis pemberian, dan hanya beberapa yang masuk akal di sini. Spesifikasi OAuth 2.0 memiliki set lengkap; ini adalah yang akan Anda gunakan.
Kode otorisasi dengan PKCE. Alur standar untuk bertindak sebagai pengguna. Pengguna dialihkan ke penyedia, menyetujui lingkup, dan layanan Anda menukar kode untuk token. PKCE melindungi pertukaran dan sekarang menjadi rekomendasi default untuk setiap jenis klien, sesuai Praktik Terbaik Keamanan OAuth 2.0. Panduan kami tentang pemberian kode otorisasi mencakup mekanika langkah demi langkah.
Poin khusus agen: alur ini berjalan sekali, dengan manusia hadir, pada waktu koneksi. Agen tidak pernah menjalankannya. Ini menggunakan token penyegaran yang dihasilkan alur. Pisahkan kedua momen itu dalam desain Anda dan sebagian besar kecanggungan akan hilang.
Kredensial klien. Mesin-ke-mesin, tidak ada pengguna yang terlibat. Benar untuk akun layanan dan salah untuk bertindak sebagai pengguna, karena tidak ada pengguna untuk menyetujui.
Pemberian otorisasi perangkat. Untuk agen pada mesin tanpa peramban. Pengguna mendapatkan kode dan menyetujui di ponsel mereka. Berguna untuk agen CLI dan lingkungan tanpa kepala.
Pertukaran token. RFC 8693 memungkinkan layanan menukar token dengan yang lebih sempit. Ini adalah cara Anda memberi sub-agen token yang terbatas pada satu lingkup untuk satu tugas, yang berasal dari pemberian pengguna yang lebih luas, tanpa menyerahkan yang asli. Jika Anda menjalankan sistem multi-agen, ini adalah mekanisme yang membuat kredensial per-agen praktis, dan itu sesuai dengan aturan batas dalam postingan kami tentang serah terima multi-agen.
Lingkupkan secara sempit, dan per agen
Lingkup adalah tempat akses terdelegasi mendapatkan nilainya, dan di mana sebagian besar implementasi menjadi malas dengan meminta semua yang mungkin dibutuhkan aplikasi.
Minta hanya apa yang dilakukan agen ini. Agen penjadwal membutuhkan penulisan kalender dan tidak ada yang lain. Bukan email, bukan kontak, bukan berkas. Pengguna membaca layar persetujuan, dan daftar panjang adalah masalah kepercayaan dan masalah radius ledakan. Penjelasan kami tentang lingkup OAuth 2 mencakup bagaimana penyedia memodelkannya.
Mintalah secara bertahap. Minta yang minimum pada waktu koneksi, lalu minta lebih banyak ketika pengguna meminta fitur yang membutuhkannya. Persetujuan yang terkait dengan permintaan konkret lebih mudah diberikan dan lebih mudah dibenarkan.
Berikan setiap agen tokennya sendiri. Jika agen penelitian dan agen penagihan keduanya bertindak untuk pengguna yang sama, dapatkan dua token dengan lingkup yang berbeda daripada berbagi satu. Maka agen penelitian yang disusupi tidak dapat mengeluarkan pengembalian dana, dan log memberi tahu Anda agen mana yang bertindak.
Pilih lingkup baca secara default dan minta eskalasi eksplisit untuk penulisan. Gabungkan ini dengan gerbang persetujuan pada panggilan destruktif, seperti dalam postingan kami tentang pembatas agen AI, sehingga token yang dapat menulis bukan satu-satunya hal yang berdiri antara agen dan kesalahan.
Simpan, segarkan, dan cabut
Token adalah kredensial, jadi perlakukanlah sebagai kredensial.
Penyimpanan. Enkripsi token penyegaran saat tidak digunakan, dengan kunci per pengguna. Jangan pernah menuliskannya ke log, jangan pernah memasukkannya ke dalam prompt, dan jangan pernah biarkan model melihatnya. Token dalam konteks adalah token di penyimpanan jejak Anda, log penyedia Anda, dan mungkin ringkasan. Postingan kami tentang pelacakan panggilan alat agen membahas penyuntingan pada batas daripada pada waktu pembacaan.
Penyegaran. Token akses berumur pendek sesuai desain. Agen tidak boleh mengelola ini sendiri; manajer token di depan klien HTTP menyegarkan saat kedaluwarsa sudah dekat dan mencoba kembali panggilan sekali pada `401`.
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
Dua detail penting. Penyedia semakin banyak merotasi token penyegaran, mengeluarkan yang baru setiap kali penyegaran dan membatalkan yang lama, jadi simpan yang baru segera atau Anda akan mengunci pengguna. Dan serikan penyegaran per pengguna, karena dua penyegaran bersamaan dengan penyedia yang berputar akan saling berebut dan salah satunya akan kalah.
Pencabutan. Pengguna mencabut akses, token kedaluwarsa, administrator menghapus akun. Agen harus menangani `401` dan `403` sebagai terminal daripada dapat dicoba ulang. Mencoba kembali kegagalan autentikasi tidak pernah membantu dan dapat memicu perlindungan penyalahgunaan. Kembalikan pesan yang jelas yang menyebutkan pengguna dan lingkup sehingga manusia dapat bertindak, mengikuti pola kesalahan dalam postingan kami tentang desain kesalahan API untuk agen.
Masalah persetujuan
Bagian canggung dari agen ditambah OAuth: persetujuan membutuhkan manusia, dan agen berjalan tanpa pengawasan.
Pisahkan waktu koneksi dari waktu berjalan dan itu menjadi mudah dikelola. Pada waktu koneksi, seseorang mengotorisasi sekali, dengan peramban, dan Anda menyimpan token penyegaran. Pada waktu berjalan, agen menggunakan pemberian itu tanpa ada manusia yang terlibat. Ini berfungsi untuk agen terjadwal dan latar belakang, yang merupakan sebagian besar dari mereka.
Dua batasan yang harus direncanakan. Pemberian kedaluwarsa, kadang-kadang setelah berbulan-bulan tidak digunakan, kadang-kadang karena kebijakan. Deteksi pemberian yang kedaluwarsa, hentikan jalannya, dan beri tahu pengguna, daripada gagal secara diam-diam setiap malam. Dan persetujuan memiliki batas atas lingkup: agen yang membutuhkan lingkup yang tidak pernah diberikan pengguna harus meminta daripada meningkatkan sendiri.
Untuk apa pun yang berisiko tinggi, tambahkan gerbang kedua pada waktu tindakan. Token membuktikan bahwa agen boleh bertindak; gerbang persetujuan memutuskan apakah agen harus bertindak. Itu adalah pertanyaan yang berbeda dan keduanya pantas mendapat jawaban.
Uji alurnya sebelum agen menemukannya
Jalur kode autentikasi adalah bagian yang paling jarang diuji dari sebagian besar integrasi, karena menjalankannya secara manual berarti mengklik layar penyedia.
Bangun lima kasus ini:
- Jalur sukses. Token akses yang valid, panggilan yang berhasil. Dasar.
- Token akses kedaluwarsa. Penyedia mengembalikan `401`, manajer menyegarkan, panggilan mencoba kembali sekali dan berhasil. Ini adalah jalur nyata yang paling umum dan seringkali paling jarang diuji.
- Token penyegaran dicabut. Penyegaran mengembalikan `invalid_grant`. Agen harus berhenti dan melaporkan, tidak mengulang.
- Lingkup tidak memadai. `403` dengan kesalahan lingkup. Agen tidak boleh mencoba lagi, dan harus mengatakan lingkup mana yang hilang.
- Penyegaran bersamaan. Dua panggilan untuk pengguna yang sama sekaligus. Tepat satu penyegaran harus terjadi.
Jalankan mereka terhadap mock. Di Apidog Anda dapat mendefinisikan titik akhir token dan titik akhir yang dilindungi, lalu mock setiap respons termasuk badan kesalahan, sehingga seluruh matriks berjalan tanpa menyentuh penyedia nyata. Postingan kami tentang menjalankan agen terhadap mock daripada produksi membahas kebiasaan yang lebih luas, dan panduan pengujian API OAuth 2 kami membahas detail tingkat permintaan.
Tiga integrasi dan apa yang mereka butuhkan
Asisten kalender. Membaca ketersediaan dan menjadwalkan rapat untuk satu pengguna. Akses terdelegasi, dua lingkup, persetujuan waktu koneksi di peramban, berjalan di latar belakang sesudahnya. Kegagalan yang menarik adalah pencabutan: pengguna memutuskan integrasi dan eksekusi malam hari harus menyadari dan berhenti daripada mencoba ulang pemberian yang mati selama seminggu.
Agen dukungan di kotak masuk bersama. Bertindak atas tiket milik tim. Di sini pertanyaan identitas menjadi lebih tajam. Bertindak sebagai akun bersama tim dapat dibela, karena sumber daya benar-benar milik tim, tetapi setiap balasan kemudian terlihat identik di log audit. Lebih baik adalah identitas bot dengan lingkupnya sendiri ditambah catatan manusia mana yang memicu eksekusi, yang menjaga atribusi tetap utuh tanpa berpura-pura agen itu adalah manusia.
Agen operasi internal. Mengulang layanan dan membaca dasbor di infrastruktur Anda sendiri. Tidak ada data pengguna, tidak ada delegasi. Akun layanan dengan lingkup sempit adalah jawaban yang tepat, dan pekerjaan berpusat pada rotasi dan radius ledakan daripada persetujuan.
Garis pemisah adalah kepemilikan. Jika data milik seseorang yang secara wajar ingin mencabut akses Anda, gunakan otorisasi terdelegasi. Jika data milik Anda, gunakan akun layanan dan curahkan upaya pada pembatasan ruang lingkup.
Jaga manusia dalam atribusi
Otorisasi terdelegasi menjawab "atas nama siapa." Itu tidak menjawab "atas permintaan siapa," dan untuk pekerjaan agen Anda menginginkan keduanya. Token membuktikan bahwa agen dapat bertindak sebagai pengguna; itu tidak mencatat siapa yang meminta eksekusi.
Simpan identitas kedua itu di samping pekerjaan. Di mana agen menjalankan tugas yang ditugaskan, lapisan manajemen pekerjaan adalah tempat alami: Tugas Sharkly mencatat orang yang bertanggung jawab atas pekerjaan bersama dengan Agen atau Kru yang ditugaskan untuk melaksanakannya, yang menjaga akuntabilitas manusia dan eksekusi agen sebagai dua fakta terpisah dan terlihat. Dokumentasi Sharkly menjelaskan pemisahan itu secara rinci. Bagaimana pun Anda menyimpannya, pertanyaan audit setelah insiden biasanya "siapa yang meminta ini," dan token saja tidak dapat menjawabnya.
Jangan biarkan model memegang kredensial
Satu aturan arsitektur mencegah sebagian besar insiden otentikasi dalam sistem agen: model tidak pernah melihat token.
Token disuntikkan oleh eksekutor pada lapisan HTTP, setelah model memilih alat dan menghasilkan argumen. Skema alat tidak memiliki parameter `token`, prompt tidak berisi kredensial, dan respons yang dibaca model telah menghapus header `Authorization`.
Ini lebih penting untuk agen daripada klien biasa karena ke mana masukan model bergerak. Apa pun dalam konteks dapat diringkas menjadi serah terima, ditulis ke jejak, digemakan dalam pesan kesalahan, atau dikembalikan kepada pengguna yang meminta agen untuk menjelaskan dirinya sendiri. Tidak ada jalur tersebut yang berbahaya; semuanya adalah fitur normal yang menjadi kebocoran saat kredensial berada dalam lingkup.
Aturan yang sama berlaku untuk identitas pengguna. Eksekutor tahu pengguna mana yang dilakukan eksekusi ini, dan memilih token dari itu. Membiarkan model menamai pengguna adalah keputusan otorisasi yang dibuat oleh komponen yang paling tidak dapat diprediksi dalam sistem.
Daftar periksa
- Akses terdelegasi di mana pun data milik pengguna, akun layanan hanya untuk sumber daya Anda sendiri.
- Kode otorisasi dengan PKCE pada waktu koneksi, pemberian perangkat untuk mesin tanpa kepala.
- Lingkup diminta per agen, minimal, diekskalasi secara bertahap.
- Sub-agen mendapatkan token yang ditukar, bukan salinan pemberian pengguna.
- Token penyegaran dienkripsi saat tidak digunakan dan tidak pernah dalam prompt, log, atau jejak.
- Penyegaran ditangani oleh manajer token, diserialisasi per pengguna, rotasi dipertahankan.
- `401` dan `403` diperlakukan sebagai terminal, dengan pesan yang menyebutkan pengguna dan lingkup.
- Pemberian yang kedaluwarsa terdeteksi dan ditampilkan kepada pengguna, tidak dicoba ulang setiap malam.
- Tindakan berisiko tinggi diatur oleh persetujuan di atas token.
- Kelima skenario otentikasi diuji terhadap mock di CI.
Otorisasi terdelegasi lebih banyak pekerjaan daripada kunci bersama, dan itu memberi Anda dua hal yang Anda butuhkan ketika agen bertindak untuk orang lain: pengguna dapat mengambilnya kembali, dan log mengatakan siapa yang melakukan apa. Unduh Apidog untuk membangun alur token dan kasus kegagalannya sebelum agen menjalankannya tanpa pengawasan.
Pertanyaan yang sering diajukan
Bisakah agen menyelesaikan alur persetujuan OAuth sendiri? Tidak, dan seharusnya tidak mencoba. Persetujuan membutuhkan orang yang memutuskan apa yang akan diberikan. Biarkan manusia mengotorisasi sekali melalui alur peramban normal, lalu biarkan agen menggunakan pemberian yang dihasilkan.
Haruskah setiap agen memiliki klien OAuth sendiri? Klien terpisah per integrasi produk, dan token terpisah per agen di dalamnya, biasanya melalui pertukaran token. Klien yang berbeda membantu ketika penyedia menerapkan batas laju per klien atau ketika Anda menginginkan pencabutan independen.
Apa yang terjadi jika token penyegaran berputar dan saya kehilangan yang baru? Pengguna terkunci dan harus terhubung kembali. Pertahankan token penyegaran baru dalam transaksi yang sama yang menggunakan yang lama, dan serikan penyegaran per pengguna sehingga dua pekerja tidak dapat bersaing.
Apakah aman membiarkan model melihat token akses? Tidak. Token milik lapisan HTTP, disuntikkan oleh eksekutor Anda. Apa pun yang dilihat model dapat berakhir di jejak, ringkasan, atau respons, seperti yang dibahas dalam postingan kami tentang kunci API hak istimewa terkecil untuk agen.
Bagaimana cara mengaudit agen mana yang melakukan apa? Catat ID pengguna, nama agen, lingkup yang digunakan, dan pengidentifikasi token pada setiap panggilan, bukan token itu sendiri. Postingan kami tentang pelacakan panggilan alat agen membahas bentuk rekaman.
Bagaimana jika penyedia tidak mendukung pertukaran token? Simpan pemberian terpisah per agen di mana penyedia memungkinkan beberapa, atau terapkan pembatasan lingkup di gateway Anda sendiri sehingga panggilan setiap agen disaring ke operasi yang diizinkan sebelum meninggalkan jaringan Anda.