Bagikan melalui

Memperoleh token dan memanggil API hilir dengan Microsoft Entra SDK untuk ID Agen

Microsoft Entra SDK untuk ID Agen adalah layanan web kontainer yang menangani akuisisi token, validasi, dan panggilan API hilir untuk agen. SDK ini berkomunikasi dengan aplikasi Anda melalui API HTTP, menyediakan pola integrasi yang konsisten terlepas dari tumpukan teknologi Anda. Alih-alih menyematkan logika identitas langsung dalam kode aplikasi Anda, Microsoft Entra SDK untuk ID Agen mengelola akuisisi token, validasi, dan panggilan API melalui permintaan HTTP standar.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Mengimplementasikan layanan terkontainerisasi Anda

Terapkan Microsoft Entra SDK untuk ID Agen sebagai layanan kontainer di lingkungan Anda. Ikuti instruksi dalam panduan Siapkan Microsoft Entra SDK untuk ID Agen untuk mengonfigurasi layanan dengan detail identitas agen Anda.

Mengonfigurasi Microsoft Entra SDK Anda untuk pengaturan ID Agen

Ikuti langkah-langkah berikut untuk mengonfigurasi Microsoft Entra SDK Anda untuk pengaturan ID Agen:

Peringatan

Rahasia klien tidak boleh digunakan sebagai kredensial klien di lingkungan produksi untuk cetak biru identitas agen karena risiko keamanan. Sebagai gantinya, gunakan metode autentikasi yang lebih aman seperti kredensial identitas gabungan (FIC) dengan identitas terkelola atau sertifikat klien. Metode ini memberikan keamanan yang ditingkatkan dengan menghilangkan kebutuhan untuk menyimpan rahasia sensitif langsung dalam konfigurasi aplikasi Anda.

  1. Siapkan komponen yang diperlukan di MICROSOFT Entra ID. Pastikan Anda mendaftarkan aplikasi Anda di tenant Microsoft Entra ID.

  2. Konfigurasikan kredensial klien Anda. Kredensial ini bisa menjadi rahasia klien, sertifikat, atau identitas terkelola yang Anda gunakan sebagai kredensial identitas gabungan.

  3. Jika Anda memanggil API hilir, pastikan bahwa izin yang diperlukan diberikan. Memanggil API web kustom mengharuskan Anda untuk memberikan detail pendaftaran API dalam konfigurasi SDK.

Untuk informasi selengkapnya, lihat Konfigurasi Microsoft Entra SDK Anda untuk pengaturan AgentID

Memperoleh token menggunakan Microsoft Entra SDK untuk ID Agen

Ini adalah langkah-langkah untuk memperoleh token menggunakan Microsoft Entra SDK untuk ID Agen:

  1. Dapatkan token menggunakan Microsoft Entra SDK untuk ID Agen. Ini bervariasi berdasarkan apakah agen beroperasi secara otonom atau atas nama pengguna. Ada tiga skenario yang perlu dipertimbangkan:

    • Agen otonom: Agen yang beroperasi atas nama mereka sendiri menggunakan principal layanan yang dibuat untuk agen tersebut (secara otonom).
    • Pengguna agen otonom: Agen yang beroperasi atas nama mereka sendiri menggunakan prinsipal pengguna yang dibuat khusus untuk agen (misalnya agen yang memiliki kotak surat mereka sendiri).
    • Agen interaktif: Agen yang beroperasi atas nama pengguna manusia.

    Tentukan API hilir dengan menyertakan namanya di URL permintaan berdasarkan konfigurasi SDK ID agen Anda. Titik akhir header otorisasi mengambil format /AuthorizationHeader/{serviceName} di mana serviceName adalah nama API hilir yang dikonfigurasi dalam pengaturan SDK.

  2. Untuk memperoleh token aplikasi hanya untuk agen otonom, Anda memberikan ID klien identitas agen dalam permintaan.

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-ID>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

  3. Untuk memperoleh token bagi pengguna agen otonom, berikan ID objek pengguna atau Nama Prinsipal Pengguna tetapi tidak keduanya. Ini berarti menyediakan baik AgentUsername atau AgentUserId. Menyediakan keduanya menyebabkan kesalahan validasi. Anda juga harus menyediakan AgentIdentity untuk menentukan identitas agen mana yang akan digunakan untuk akuisisi token. Jika parameter identitas agen hilang, permintaan gagal dengan kesalahan validasi.

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-id>&AgentUserId=<agent-user-object-id>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

    GET /AuthorizationHeader/Graph?AgentIdentity=<agent-id-client-id>&AgentUsername=<agent-user-principal-name>
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

  4. Untuk agen interaktif, gunakan atas nama alur. Agen terlebih dahulu memvalidasi token pengguna yang diberikan kepadanya sebelum memperoleh token sumber daya untuk memanggil API hilir.

    API web agen menerima token pengguna dari aplikasi yang memanggil dan memvalidasi token tersebut melalui titik akhir SDK ID agen /Validate. Peroleh token untuk API hilir (downstream) dengan memanggil /AuthorizationHeader hanya dengan AgentIdentity dan menggunakan header otorisasi yang telah diterima.

    # Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

Memanggil sebuah API

Saat memperoleh header otorisasi untuk memanggil API lanjutan, Microsoft Entra SDK untuk Agen ID mengembalikan Authorization sebagai nilai header yang bisa langsung digunakan dalam panggilan API Anda.

Anda dapat menggunakan header ini untuk memanggil API hilir. API web harus memanggil endpoint /Validate dari Microsoft Entra SDK untuk memvalidasi token Agen ID. Titik akhir ini mengembalikan klaim token untuk keputusan otorisasi lebih lanjut.

Konten terkait

  • Last updated on