Membuat cetak biru identitas agen

Cetak biru identitas agen digunakan untuk membuat identitas agen dan meminta token menggunakan identitas agen tersebut. Selama proses pembuatan cetak biru identitas agen, Anda menetapkan pemilik dan sponsor cetak biru tersebut, untuk membangun akuntabilitas dan hubungan administratif. Anda juga mengonfigurasi URI pengidentifikasi dan menentukan cakupan untuk agen yang dibuat dari cetak biru ini jika agen dirancang untuk menerima permintaan masuk dari agen dan pengguna lain.

Anda dapat membuat cetak biru identitas agen dengan dua cara:

  • pusat admin Microsoft Entra — Gunakan wizard untuk penyiapan cepat yang membuat pola dasar dan entitas utamanya.
  • Microsoft Graph API atau PowerShell — Buat dan konfigurasikan sepenuhnya cetak biru secara terprogram, termasuk kredensial, URI pengidentifikasi, cakupan, dan prinsip cetak biru dalam satu alur kerja.

Prasyarat

Untuk membuat cetak biru identitas agen, Anda memerlukan:

Nota

Pemilik cetak biru identitas agen atau prinsipal cetak biru identitas agen dapat membuat identitas agen untuk cetak biru tersebut tanpa peran ID Agen Microsoft Entra. Pembuat cetak biru identitas agen secara otomatis ditetapkan sebagai pemilik cetak biru dan prinsipal cetak biru identitas agen terkait.

Menyiapkan lingkungan Anda

Untuk menyederhanakan proses, luangkan sedikit waktu untuk menyiapkan lingkungan Anda agar memiliki izin yang tepat.

Mengotorisasi klien untuk membuat cetak biru identitas agen

Dalam artikel ini, Anda menggunakan Microsoft Graph PowerShell atau klien lain untuk membuat cetak biru identitas agen Anda. Anda harus mengotorisasi klien ini untuk membuat dan mengonfigurasi cetak biru identitas agen serta membuat prinsipal cetak biru identitas agen. Klien memerlukan izin Microsoft Graph berikut:

Langkah-langkah dalam panduan ini menggunakan semua izin yang didelegasikan, tetapi Anda dapat menggunakan izin aplikasi untuk skenario yang memerlukannya.

Untuk menyambungkan ke semua cakupan yang diperlukan untuk Microsoft Graph PowerShell, jalankan perintah berikut:

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.AddRemoveCreds.All", "AgentIdentityBlueprint.UpdateAuthProperties.All", "AgentIdentityBlueprintPrincipal.Create", "User.Read" -TenantId <your-tenant-id>

Membuat cetak biru identitas agen

Cetak biru identitas agen harus memiliki sponsor, yaitu pengguna atau grup yang ditunjuk yang bertanggung jawab terhadap agen. Pemilik direkomendasikan, yaitu pengguna atau perwakilan layanan yang dapat membuat perubahan pada cetak biru identitas agen. Untuk informasi lebih lanjut, lihat hubungan Administratif dalam ID Agen Microsoft Entra.

Menggunakan pusat admin Microsoft Entra

Anda dapat membuat cetak biru identitas agen langsung di pusat admin Microsoft Entra. Wizard pusat admin membuat cetak biru identitas agen dan prinsipal cetak birunya secara otomatis.

Nota

Wizard di pusat admin menetapkan nama cetak biru dan menetapkan pemilik serta sponsor. Untuk mengonfigurasi kredensial, URI pengidentifikasi, cakupan, atau izin, gunakan Microsoft Graph API atau PowerShell, atau konfigurasikan setelah dibuat melalui halaman detail cetak biru di pusat admin.

  1. Masuk ke pusat admin Microsoft Entra.

  2. Telusuri Entra ID>Agen>Cetak biru Agen.

  3. Pilih Rencana agen baru (Pratinjau).

  4. Pada tab Dasar , masukkan nama di bidang Nama cetak biru agen dan pilih Berikutnya.

    Tangkapan layar wizard membuat cetak biru agen memperlihatkan tab Dasar-Dasar dengan bidang nama cetak biru agen.

  5. Pada tab Pemilik & Sponsor, jika diinginkan, ubah atau tambahkan pemilik dan sponsor untuk cetak biru.

    • Pilih ikon pensil di samping kolom Pemilik untuk mengubah atau menambahkan pengguna yang dapat mengelola desain.
    • Pilih ikon pensil di samping bidang Sponsor untuk mengubah atau menambahkan pengguna yang dapat menjadi sponsor cetak biru.

    Nota

    Sponsor dapat berupa pengguna, grup keanggotaan dinamis, atau grup Microsoft 365. Grup keamanan dan grup yang dapat ditetapkan peran tidak didukung sebagai sponsor.

  6. Pilih Selanjutnya.

  7. Tinjau pengaturan Anda, lalu pilih Buat.

  8. Pilih Selesai untuk keluar dari wizard atau Buka cetak biru agen untuk melihat halaman detail cetak biru atau mengonfigurasi pengaturan lainnya.

Untuk informasi selengkapnya tentang mengelola cetak biru identitas agen, lihat Mengelola cetak biru identitas agen.

Membuat secara terprogram

Untuk membuat cetak biru identitas agen menggunakan kode, gunakan Microsoft Graph API atau PowerShell.

Langkah ini membuat cetak biru identitas agen, menetapkan pemilik dan sponsor, dan memerlukan detail berikut:

  • Izinnya AgentIdentityBlueprint.Create .
  • Header OData-Version harus diatur ke 4.0.
  • ID pengguna untuk bidang pemilik dan sponsor dalam isi permintaan contoh. Sponsor diperlukan, tetapi pemilik bersifat opsional.
POST https://graph.microsoft.com/v1.0/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>"
  ],
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>"
  ]
}

Setelah membuat cetak biru identitas agen, catat nilai appId untuk langkah berikutnya.

Mengonfigurasi kredensial untuk cetak biru identitas agen

Untuk meminta token akses menggunakan cetak biru identitas agen, Anda harus menambahkan kredensial klien. Sebaiknya gunakan identitas terkelola sebagai kredensial identitas gabungan (FIC) untuk penyebaran produksi. Identitas terkelola memungkinkan Anda mendapatkan token Microsoft Entra tanpa harus mengelola kredensial apa pun. Untuk informasi selengkapnya, lihat identitas Managed untuk sumber daya Azure.

Jenis kredensial aplikasi lainnya termasuk keyCredentials dan passwordCredentials didukung, tetapi tidak direkomendasikan untuk produksi. Mereka dapat nyaman untuk pengembangan dan pengujian lokal atau di mana identitas terkelola tidak akan berfungsi, tetapi opsi ini tidak selaras dengan praktik terbaik keamanan. Untuk informasi selengkapnya, lihat Praktik terbaik keamanan untuk properti aplikasi.

Perlu diingat bahwa untuk menggunakan identitas terkelola, Anda harus menjalankan kode Anda pada layanan Azure, seperti komputer virtual atau Azure App Service. Untuk pengembangan dan pengujian lokal, gunakan rahasia atau sertifikat klien.

Untuk mengirim permintaan ini:

  • Anda memerlukan izin AgentIdentityBlueprint.AddRemoveCreds.All.
  • Ganti <agent-blueprint-id> placeholder dengan cetak biru identitas agen appId.
  • Ganti tempat penampung <managed-identity-principal-id> dengan ID identitas terkelola Anda.

Tambahkan identitas terkelola sebagai kredensial menggunakan permintaan berikut:

POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "my-managed-identity",
    "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
    "subject": "<managed-identity-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Kredensial aplikasi lainnya

Untuk skenario di mana identitas terkelola tidak akan berfungsi atau jika Anda membuat cetak biru secara lokal untuk pengujian, gunakan langkah-langkah berikut untuk menambahkan kredensial.

Untuk mengirim permintaan ini, Anda harus terlebih dahulu mendapatkan token akses dengan izin yang didelegasikan AgentIdentityBlueprint.AddRemoveCreds.All

POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Nota

Penyewa Anda mungkin memiliki kebijakan siklus hidup kredensial yang membatasi masa pakai maksimum untuk rahasia klien. Jika Anda menerima kesalahan tentang masa pakai kredensial, kurangi endDateTime nilai agar selaras dengan kebijakan organisasi Anda.

Pastikan untuk menyimpan nilai yang passwordCredential dihasilkan dengan aman. Itu tidak dapat dilihat setelah dibuat pertama kali. Anda juga dapat menggunakan sertifikat klien sebagai kredensial; lihat Menambahkan kredensial sertifikat.

Jika agen yang dibuat berdasarkan cetak biru akan mendukung agen interaktif, di mana agen bertindak atas nama pengguna, cetak biru Anda harus menyediakan ruang lingkup sehingga frontend agen dapat meneruskan token akses ke backend agen. Token ini kemudian dapat digunakan oleh backend agen untuk mendapatkan token akses untuk bertindak atas nama pengguna.

Mengonfigurasi URI pengidentifikasi dan ruang lingkup

Untuk menerima permintaan masuk dari pengguna dan agen lain, seperti untuk API web apa pun, Anda perlu menentukan URI pengidentifikasi dan cakupan OAuth untuk cetak biru identitas agen Anda:

Untuk mengirim permintaan ini:

  • Anda memerlukan izin AgentIdentityBlueprint.UpdateAuthProperties.All.
  • Ganti <agent-blueprint-id> placeholder dengan cetak biru identitas agen appId.
  • Anda memerlukan Pengidentifikasi Unik Global (GUID). Di PowerShell, jalankan [guid]::NewGuid() atau gunakan generator GUID online. Salin GUID yang dihasilkan dan gunakan untuk mengganti penampung <generate-a-guid>.
PATCH https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Panggilan yang berhasil menghasilkan respons 204.

Membuat cetak biru prinsipal agen

Dalam langkah ini, Anda membuat entitas untuk pola identitas agen. Untuk informasi selengkapnya, lihat Identitas agen, perwakilan layanan, dan aplikasi.

Ganti <agent-blueprint-app-id> dengan appId yang Anda salin dari hasil langkah sebelumnya.

POST https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "appId": "<agent-blueprint-app-id>"
}

Blueprint agen Anda sekarang siap dan terlihat di pusat admin Microsoft Entra. Pada langkah berikutnya, Anda akan menggunakan cetak biru ini untuk membuat identitas agen.

Mendaftarkan agen di registri Agen 365

Setelah Anda membuat cetak biru identitas agen, daftarkan di registri Agent 365 sehingga administrator dapat menemukan, mengatur, dan mengelola agen dari pusat admin Microsoft 365. Bagian ini juga menyediakan instruksi untuk menambahkan cetak biru identitas agen yang ada yang mungkin saat ini tidak muncul di registri Agen 365.

Agen SDK Microsoft 365 sekarang tersedia secara umum dan merupakan cara yang disarankan untuk membangun dan menyediakan agen. SDK SDK menangani pembuatan dan pendaftaran identitas agen di registri Agen 365 untuk Anda, sehingga identitas agen Anda akan muncul secara otomatis tanpa kode tambahan. Jika Anda memulai proyek agen baru, atau memiliki fleksibilitas untuk memigrasikan kode yang ada, gunakan SDK. Ini adalah jalur paling sederhana dan paling tahan lama dan menghindari kebutuhan untuk mengoordinasikan beberapa panggilan API sendiri.

Menggunakan Agent 365 CLI

Agen 365 CLI adalah opsi lain yang menangani penyiapan untuk Anda, termasuk pendaftaran agen. Ikuti instruksi penyiapan menggunakan urutan eksekusi yang direkomendasikan. Gunakan perintah berikut:

a365 setup all

Jika pendaftaran gagal, Anda dapat menjalankan ulang hanya langkah pendaftaran tanpa harus melalui seluruh proses. Gunakan perintah berikut:

a365 setup all --agent-registration-only

Panggil API Registri Agen secara langsung

Jika Anda harus membuat cetak biru identitas agen secara terprogram dengan Microsoft Graph API, misalnya karena Anda memiliki alur kerja penerbitan identitas yang ada, Anda tidak dapat segera mengubahnya, Anda perlu menambahkan panggilan eksplisit ke AGENT Registry API setelahnya membuat cetak biru identitas agen untuk memposting kartu agen yang sesuai. Langkah ini mendaftarkan kartu agen di registri Agen 365 sehingga muncul untuk administrator.

  1. Buat cetak biru identitas agen menggunakan Microsoft Graph API (seperti yang ditunjukkan di bagian sebelumnya).
  2. Segera ikuti dengan panggilan ke Agent Registry API untuk memposting kartu agen yang bersesuaian, termasuk metadata yang diperlukan administrator Anda untuk mengelolanya.
  3. Tangani pola pemanggilan dua kali dengan cara yang aman untuk percobaan ulang, sehingga kegagalan sementara pada salah satu panggilan meninggalkan lingkungan Anda dalam kondisi yang dapat dipulihkan.

Untuk skema permintaan dan respons, izin yang diperlukan, dan sampel kode, lihat referensi API Registri Agen.

Tip

Jika Anda memiliki cetak biru identitas agen yang ada yang tidak muncul di registri Agen 365, daftarkan menggunakan AGENT Registry API. Untuk cetak biru identitas agen secara massal, gunakan titik akhir batch. Untuk informasi selengkapnya, lihat konvergensi Agent Registry dengan agen Microsoft 365.

Cetak biru identitas agen yang sudah ada yang tidak terdapat di registri Agen 365

Untuk cetak biru identitas agen yang sebelumnya dibuat menggunakan ID Agen Microsoft Entra Graph API tetapi saat ini tidak terlihat di registri Agen 365, Anda dapat mendaftarkannya menggunakan AGENT Registry API. Langkah ini memastikan mereka muncul di registri Agen 365.

Menghapus rancangan identitas agen

Saat agen dinonaktifkan, hapus cetak biru identitas agen terkait. Menghapus cetak biru memicu pembersihan otomatis semua identitas agen anak dan akun pengguna agen. Untuk instruksi penghapusan dan pemulihan langkah demi langkah, lihat Menghapus dan memulihkan objek identitas agen.

Langkah selanjutnya

Membuat dan menghapus identitas agen

  • Last updated on