Autentikasi dan otorisasi di Microsoft Foundry

Autentikasi dan otorisasi di Microsoft Foundry mengontrol bagaimana prinsipal membuktikan identitas dan mendapatkan izin untuk melakukan operasi. Foundry membagi operasi menjadi bidang kontrol (manajemen sumber daya) dan bidang data (penggunaan runtime), masing-masing dengan permukaan autentikasi dan kontrol akses berbasis peran (RBAC) sendiri.

Foundry mendukung dua metode autentikasi: Microsoft Entra ID dan kunci API. Microsoft Entra ID memungkinkan akses kondisional, identitas terkelola, dan RBAC (Kontrol Akses Berdasarkan Peran) yang terperinci. Kunci API tetap tersedia untuk prototipe cepat tetapi tidak memiliki keterlacakan per pengguna. Artikel ini membandingkan metode ini, memetakan identitas dengan peran, dan menjelaskan skenario hak istimewa paling sedikit umum.

Penting

Gunakan Microsoft Entra ID untuk penggunaan produksi guna mengaktifkan akses bersyarat, identitas yang dikelola, dan hak istimewa RBAC seminimal mungkin. Kunci API nyaman untuk evaluasi cepat tetapi menyediakan akses dengan tingkat yang kurang detil.

Prasyarat

Langganan Azure. Jika Anda tidak memilikinya, buat akun gratis.
Sumber daya Microsoft Foundry dengan subdomain kustom yang dikonfigurasi.
Memahami konsep RBAC Azure.
Untuk menetapkan peran, Anda memerlukan peran Owner atau peran Pengguna Access Administrator pada cakupan yang sesuai.
(Opsional) Azure CLI atau Azure SDK untuk Python diinstal untuk autentikasi terprogram.
(Opsional) paket Python untuk sampel kode: pip install azure-identity requests

Bidang kendali dan bidang data

Operasi Azure dibagi menjadi dua kategori: lapisan kontrol dan lapisan data. Azure memisahkan manajemen sumber daya (sarana kontrol) dari runtime operasional (data plane). Oleh karena itu, Anda menggunakan sarana kontrol untuk mengelola sumber daya dalam langganan Anda dan menggunakan bidang data untuk menggunakan kemampuan yang diekspos oleh instans jenis sumber daya Anda. Untuk mempelajari selengkapnya tentang control plane dan data plane, lihat Azure control plane dan data plane. Di Foundry, ada perbedaan yang jelas antara operasi sarana kontrol versus operasi sarana data. Tabel berikut menjelaskan perbedaan antara keduanya, cakupan di Foundry, operasi pengguna yang lazim, alat dan fitur yang khas, dan area otorisasi untuk menggunakan masing-masing.

Pesawat	Lingkup di Foundry	Operasi umum	Contoh alat	Antarmuka Otorisasi
Pesawat pengendali	Menyiapkan dan mengonfigurasi sumber daya, proyek, jaringan, enkripsi, dan koneksi	Membuat atau menghapus sumber daya, menetapkan peran, memutar kunci, menyiapkan Private Link	portal Azure, Azure CLI, templat ARM, Bicep, Terraform	Azure aksi RBAC
Bidang data	Menjalankan dan menggunakan inferensi model, interaksi dengan agen, tugas evaluasi, dan panggilan terkait keamanan konten	Penyelesaian obrolan, pembuatan penyematan, mulai menyempurnakan pekerjaan, mengirim pesan agen, menganalisis, dan operasi pengklasifikasi	SDK, REST API, taman bermain portal Foundry	Azure RBAC dataActions

Untuk semua sampel Bicep, Terraform, dan SDK, lihat repositori sampel foundry pada GitHub untuk Foundry.

Daftar dan diagram berikut mengilustrasikan pemisahan antara tindakan sarana kontrol dan bidang data secara terperinci. Tindakan pesawat kontrol dalam Foundry meliputi:

Pembuatan sumber daya untuk foundry
Pembuatan proyek "Foundry"
Pembuatan Kapabilitas Akun Host
Pembuatan Host Kemampuan Proyek
Penerapan Model
Pembuatan akun dan koneksi proyek

Tindakan sarana data dalam Foundry meliputi:

Membuat agen perangkat lunak
Menjalankan evaluasi
Pelacakan dan pemantauan
Fine-tuning

Diagram berikut menunjukkan tampilan pemisahan antara control plane dan data plane di Foundry, bersama dengan penetapan kontrol akses berbasis peran (RBAC) dan akses apa yang mungkin dimiliki oleh seorang pengguna baik di control plane, data plane, atau keduanya. Seperti yang terlihat dalam diagram, "tindakan" RBAC dikaitkan dengan sarana kontrol sementara RBAC "dataActions" dikaitkan dengan bidang data.

Metode autentikasi

Foundry mendukung kunci Microsoft Entra ID (berbasis token, tanpa kunci) dan API.

Microsoft Entra ID

Microsoft Entra ID menggunakan token pembawa OAuth 2.0 yang dilingkup ke https://ai.azure.com/.default.

Gunakan Microsoft Entra ID untuk:

Beban kerja produksi.
Akses bersyarat, autentikasi multifaktor (MFA), dan akses tepat waktu.
Hak akses minimum RBAC dan integrasi identitas terkelola.

Keuntungan: Penetapan peran yang terperinci, audit per individu, masa pakai token yang dapat dikontrol, pengelolaan rahasia secara otomatis, dan identitas yang dikelola untuk layanan.

Batasan: Kompleksitas penyiapan awal yang lebih tinggi. Memerlukan pemahaman tentang kontrol akses berbasis peran (RBAC). Untuk informasi selengkapnya tentang RBAC di Foundry, lihat kontrol akses berbasis peran untuk Microsoft Foundry.

Kunci API

Kunci API adalah rahasia statis yang dibatasi untuk sumber daya Foundry.

Gunakan kunci API untuk:

Prototipe cepat.
Lingkungan pengujian terisolasi di mana rotasi rahasia tunggal dapat diterima.

Keuntungan: Sederhana, agnostik bahasa, dan tidak memerlukan akuisisi token.

Batasan: Tidak dapat mengekspresikan identitas pengguna, sulit untuk cakupan secara terperinci, dan lebih sulit untuk diaudit. Umumnya tidak diterima oleh beban kerja produksi perusahaan dan tidak direkomendasikan oleh Microsoft.

Untuk informasi selengkapnya tentang mengaktifkan autentikasi tanpa kunci, lihat Konfigurasi autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengautentikasi dengan Microsoft Entra ID (Python)

Contoh berikut menunjukkan cara mengautentikasi dengan Microsoft Entra ID dengan menggunakan pustaka azure-identity serta mengajukan permintaan ke titik akhir Foundry.

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Cognitive Services scope
token = credential.get_token("https://ai.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Output yang diharapkan: Respons JSON yang mencantumkan penyebaran model Anda, atau kesalahan autentikasi jika kredensial hilang atau penetapan peran tidak dikonfigurasi.

Referensi: DefaultAzureCredential | azure-identity library

Mengautentikasi dengan kunci API (Python)

Contoh berikut menunjukkan cara mengautentikasi dengan menggunakan kunci API. Gunakan pendekatan ini hanya untuk prototipe cepat; Microsoft Entra ID direkomendasikan untuk produksi.

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Peringatan

Kunci API menyediakan access penuh ke sumber daya dan tidak dapat dicakup ke pengguna atau tindakan tertentu. Putar kunci secara teratur dan hindari menerapkannya ke kontrol sumber.

Output yang diharapkan: Respons JSON yang mencantumkan penyebaran model Anda, atau kesalahan 401 jika kunci API tidak valid.

Referensi: Rotasi Kunci Akses API

Matriks dukungan fitur

Referensikan matriks berikut untuk memahami kemampuan apa di Foundry mendukung kunci API versus Microsoft Entra ID.

Kemampuan atau fitur	Kunci API	Microsoft Entra ID	Catatan
Inferensi model dasar (obrolan, penyematan)	Yes	Yes	Didukung penuh.
Operasi penyempurnaan	Yes	Yes	Entra ID menambahkan audit per prinsipal.
Layanan agen	Tidak.	Yes	Gunakan Entra ID untuk akses alat identitas terkelola.
Evaluations	Tidak.	Yes	Gunakan Entra ID.
Panggilan analisis keamanan konten	Yes	Yes	Gunakan RBAC untuk membatasi operasi berisiko tinggi.
Pekerjaan analisis batch (Pemahaman Konten)	Yes	Yes	Entra ID direkomendasikan untuk skalabilitas.
Penggunaan portal playground	Yes	Yes	Playground menggunakan mode koneksi proyek.
Isolasi jaringan dengan Private Link	Yes	Yes	Entra ID menambahkan akses bersyarah.
Hak akses minimum dengan peran bawaan dan kustom	Tidak.	Yes	Kunci adalah semua atau tidak sama sekali per sumber daya.
Identitas yang dikelola (sistem atau pengguna yang ditugaskan)	Tidak.	Yes	Mengaktifkan autentikasi tanpa rahasia.
Atribusi pengguna per permintaan	Tidak.	Yes	Token berisi ID penyewa dan objek.
Pencabutan (segera)	Putar kunci	Menghapus peran atau menonaktifkan prinsipal	Masa pakai token pendek berlaku.
Dukungan dalam jalur otomatisasi	Ya (rahasia)	Ya (prinsipal layanan atau identitas terkelola)	Entra ID mengurangi frekuensi pergantian kunci rahasia.
API Asisten	Yes	Yes	Disarankan untuk menggunakan Entra ID.
Melakukan inferensi batch	Yes	Yes

Jenis identitas

Azure sumber daya dan aplikasi mengautentikasi dengan menggunakan jenis identitas yang berbeda, masing-masing dirancang untuk skenario tertentu. Prinsipal pengguna mewakili pengguna manusia, perwakilan layanan mewakili aplikasi atau proses otomatis, dan identitas terkelola menyediakan cara yang aman dan bebas kredensial bagi sumber daya Azure untuk mengakses layanan lain. Memahami perbedaan ini membantu Anda memilih identitas yang tepat untuk masuk interaktif, komunikasi aplikasi ke aplikasi, atau otomatisasi beban kerja.

Azure mendukung jenis identitas berikut.

Jenis identitas	Deskripsi
Pengguna utama	Pengguna individual di Microsoft Entra ID
Service Principal (pendaftaran aplikasi)	Identitas aplikasi yang menggunakan rahasia atau sertifikat klien
Identitas terkelola (ditetapkan sistem)	Identitas terikat sumber daya Azure yang dikelola otomatis oleh platform.
Identitas terkelola (ditetapkan pengguna)	Identitas mandiri yang melekat pada beberapa sumber daya.

Gambaran umum peran bawaan

Di Foundry, gunakan peran bawaan untuk memisahkan tindakan yang diizinkan bagi pengguna. Sebagian besar perusahaan menginginkan pemisahan kontrol dan tindakan bidang data untuk peran bawaan mereka. Yang lain mengharapkan data gabungan dan peran sarana kontrol untuk meminimalkan jumlah penetapan peran yang diperlukan. Tabel berikut ini mencantumkan skenario dan peran Foundry bawaan terkait yang paling sesuai dengan setiap skenario.

Skenario	Peran bawaan umum	Catatan
Membangun agen dengan model yang telah di-deploy sebelumnya	Pengguna AI Azure	Hanya penggunaan data plane; tidak ada penulisan konfigurasi manajemen.
Mengelola penyebaran atau menyempurnakan model	Manajer Proyek AI Azure	Termasuk pembuatan dan pembaruan penyebaran model.
Memutar kunci atau mengelola sumber daya	Pemilik Akun Azure AI	Hak istimewa tinggi; pertimbangkan peran kustom untuk hak istimewa paling sedikit.
Mengelola sumber daya, mengelola penyebaran, membangun agen	pemilik AI Azure	Peran layanan mandiri yang sangat istimewa untuk pengguna yang membutuhkan sarana kontrol dan bidang data access. Gabungkan dengan pembaca Azure Monitor jika diperlukan pengamatan.
Pengamatan, pelacakan, pemantauan	Pengguna AI Azure (minimum)	Tambahkan pembaca Azure Monitor di Application Insights.

Untuk memahami perincian peran bawaan dan tindakan kontrol dan bidang data, tinjau diagram berikut.

Petunjuk / Saran

Buat peran kustom jika peran bawaan memberikan izin berlebih untuk kasus penggunaan Anda.

Menyiapkan Microsoft Entra ID

Untuk panduan tingkat tinggi tentang menyiapkan autentikasi Entra ID di Foundry, lihat Konfigurasi autentikasi tanpa kunci.

Pastikan sumber daya Microsoft Foundry Anda memiliki subdomain kustom yang dikonfigurasi. Lihat subdomain kustom. Subdomain kustom diperlukan untuk autentikasi berbasis token.
Tetapkan peran bawaan atau kustom yang diperlukan untuk setiap prinsipal. Anda memerlukan peran Owner atau Pengguna Access Administrator pada cakupan target untuk menetapkan peran. Penetapan peran umum:
- Pengguna Azure AI: Untuk pengembang yang perlu membangun dan menguji dengan model yang sudah dideploy.
- Azure AI Project Manager: Untuk pemimpin tim yang perlu membuat proyek dan mengelola penyebaran.
- Pemilik Akun Azure AI: Untuk administrator yang memerlukan pengelolaan sumber daya sepenuhnya dan dapat menetapkan Pengguna AI Azure dengan ketentuan tertentu untuk akses data plane.
- Pemilik Azure AI: Untuk pengguna yang membutuhkan manajemen sumber daya penuh dan akses bidang data. Contoh perintah CLI untuk menetapkan peran Pengguna AI Azure:
```
az role assignment create \
  --assignee <principal-id> \
  --role "Azure AI User" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
```
Untuk memverifikasi penetapan peran, jalankan az role assignment list --assignee <principal-id> --scope <resource-scope> dan pastikan bahwa peran tersebut muncul dalam output.
(Opsional) Untuk perwakilan layanan, buat pendaftaran aplikasi, tambahkan rahasia atau sertifikat klien, dan catat ID penyewa, ID klien, dan rahasia atau sertifikat.
(Opsional) Untuk identitas terkelola, aktifkan identitas yang ditetapkan sistem pada layanan panggilan atau lampirkan identitas yang ditetapkan pengguna, lalu tetapkan peran ke identitas tersebut pada sumber daya Foundry.
Hapus autentikasi berbasis kunci setelah semua pemanggil menggunakan autentikasi token. Secara opsional nonaktifkan autentikasi lokal dalam templat penyebaran.

Reference: Menetapkan peran Azure | Kontrol akses berbasis peran untuk Foundry

Memecahkan masalah kesalahan autentikasi umum

Kesalahan	Penyebab	Resolusi
401 Tidak Sah	Token hilang atau kedaluwarsa; kunci API tidak valid	Verifikasi bahwa cakupan akuisisi token adalah `https://ai.azure.com/.default`. Regenerasi kunci API jika Anda menggunakan autentikasi berbasis kunci.
403 Dilarang	Penetapan peran RBAC tidak ditemukan	Tetapkan peran bawaan yang sesuai (misalnya, Azure Pengguna AI) di cakupan sumber daya atau proyek.
AADSTS700016	Aplikasi tidak ditemukan di penyewa	Verifikasi bahwa pendaftaran aplikasi ada di penyewa yang benar dan ID klien sudah benar.
Subdomain kustom diperlukan	Sumber daya menggunakan titik akhir regional alih-alih subdomain kustom	Konfigurasikan subdomain kustom pada sumber daya Foundry. Autentikasi berbasis token memerlukan subdomain kustom.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-08