Microsoft Foundry'de kimlik doğrulaması ve yetkilendirme

Microsoft Foundry'de kimlik doğrulaması ve yetkilendirme, sorumluların kimlik doğrulamasını ve işlemleri gerçekleştirme iznini nasıl kazandığını denetler. Dökümhane, her biri kendi kimlik doğrulaması ve rol tabanlı erişim denetimi (RBAC) yüzeyine sahip denetim düzlemi (kaynak yönetimi) ve veri düzlemi (çalışma zamanı kullanımı) işlemlerine böler.

Dökümhane iki kimlik doğrulama yöntemini destekler: Microsoft Entra ID ve API anahtarları. Microsoft Entra ID koşullu erişimi, yönetilen kimlikleri ve ayrıntılı RBAC'yi etkinleştirir. HıZLı prototip oluşturma için API anahtarları kullanılabilir durumda kalır, ancak kullanıcı başına izlenebilirlik özelliği eksiktir. Bu makale bu yöntemleri karşılaştırır, kimlikleri rollerle eşler ve en yaygın en düşük ayrıcalık senaryolarını açıklar.

Önemli

Koşullu erişimi, yönetilen kimlikleri ve en az ayrıcalıklı RBAC'yi etkinleştirmek için üretim iş yükleri için Microsoft Entra ID kullanın. API anahtarları hızlı değerlendirme için uygundur ancak daha ayrıntılı erişim sağlar.

Önkoşullar

Kontrol düzlemi ve veri düzlemi

Azure işlemler iki kategoriye ayrılır: kontrol düzlemi ve veri düzlemi. Azure, kaynak yönetimini (denetim düzlemi) işletimsel çalışma zamanından (veri düzlemi) ayırır. Bu nedenle, aboneliğinizdeki kaynakları yönetmek için denetim düzlemini kullanırsınız ve veri düzlemini kullanarak kaynak türü örneğinizin sunduğu özellikleri kullanırsınız. Kontrol düzlemi ve veri düzlemi hakkında daha fazla bilgi edinmek için bkz. Azure kontrol düzlemi ve veri düzlemi. Foundry'de, denetim düzlemi işlemleri ile veri düzlemi işlemleri arasında net bir ayrım vardır. Aşağıdaki tabloda ikisi arasındaki fark, Foundry'deki kapsam, bir kullanıcının tipik işlemleri, örnek araçlar ve özellikler ve her birini kullanmak için yetkilendirme yüzeyi açıklanmaktadır.

Uçak Kapsam Foundry'de Tipik işlemler Örnek araçlar Yetkilendirme yüzeyi
Kontrol düzlemi Kaynak, proje, ağ, şifreleme ve bağlantıları ayarlama ve yapılandırma Kaynak oluşturma veya silme, rol atama, anahtarları döndürme, Özel Bağlantı ayarlama Azure portalı, Azure CLI, ARM şablonları, Bicep, Terraform Azure RBAC eylemleri
Veri düzlemi Model çıkarımı, ajan etkileşimleri, değerlendirme görevleri ve içerik güvenliği çağrılarını yürütme ve kullanma Sohbet tamamlamaları, yerleştirme oluşturma, ince ayar başlatma, aracı iletileri gönderme, çözümleyici ve sınıflandırıcı işlemleri SDK'lar, REST API'ler, Dökümhane portalı oyun alanı Azure RBAC veriEylemleri

Tüm Bicep, Terraform ve SDK örnekleri için, Foundry için GitHub üzerindeki foundry-samples deposuna bakın.

Aşağıdaki listeler ve diyagram, denetim düzlemi ile veri düzlemi eylemleri arasındaki ayrımı ayrıntılı olarak gösterir. Foundry içindeki kontrol düzlemi eylemleri şunlardır:

  • Dökümhane kaynağı oluşturma
  • Dökümhane projesi oluşturma
  • Hesap Özelliği Sunucu oluşturma
  • Proje Yetenek Sunucusu oluşturma
  • Model dağıtımı
  • Hesap ve proje bağlantısı oluşturma

Foundry içindeki veri düzlemi eylemleri şunlardır:

  • Ajanlar oluşturma
  • Değerlendirme yürütme
  • İzleme ve izleme
  • Ince ayar

Aşağıdaki diyagramda rol tabanlı erişim denetimi (RBAC) atamalarının yanı sıra Foundry'de denetim düzlemi görünümü ile veri düzlemi ayrımı görünümü ve kullanıcının denetim düzleminde veya veri düzleminde ya da her ikisinde hangi erişime sahip olabileceği gösterilmektedir. Diyagramda görüldüğü gibi, RBAC "eylemleri" denetim düzlemi ile ilişkilendirilirken, RBAC "dataActions" veri düzlemi ile ilişkilendirilir.

Denetim düzlemi ve veri düzlemi işlemlerinin ilişkili RBAC yüzeyleriyle ayrılmasını gösteren diyagram.

Kimlik doğrulama yöntemleri

Foundry, Microsoft Entra ID (token tabanlı, anahtarsız olarak) ve API anahtarlarını destekler.

Microsoft Entra ID

Microsoft Entra ID kapsamı https://ai.azure.com/.default olarak belirlenmiş OAuth 2.0 taşıyıcı belirteçleri kullanır.

aşağıdakiler için Microsoft Entra ID kullanın:

  • Üretim iş yükleri.
  • Koşullu erişim, çok faktörlü kimlik doğrulaması (MFA) ve tam zamanında erişim.
  • Minimum ayrıcalık RBAC ve yönetilen kimlik entegrasyonu.

Avantajlar: Ayrıntılı rol atamaları, sorumlu başına denetim, denetlenebilir belirteç ömrü, otomatik gizli dizi hijyeni ve hizmetler için yönetilen kimlikler.

Sınırlamalar: Daha yüksek ilk kurulum karmaşıklığı. Rol tabanlı erişim denetiminin (RBAC) anlaşılmasını gerektirir. Foundry'de RBAC hakkında daha fazla bilgi için bkz. Microsoft Foundry için Rol tabanlı erişim kontrolü.

API anahtarları

API anahtarları, bir Foundry kaynağı kapsamındaki statik gizli bilgilerdir.

Aşağıdakiler için API anahtarlarını kullanın:

  • Hızlı prototip oluşturma.
  • Gizli bilgilerin tek seferde döndürülmesinin kabul edilebilir olduğu yalıtılmış test ortamları.

Avantajlar: Dil bağımsızdır, basit ve belirteç alımı gerektirmez.

Sınırlamalar: Kullanıcı kimliğini ifade edememek, kapsamını ayrıntılı olarak belirlemek zor ve denetlemesi daha zor. Genellikle kurumsal üretim iş yükleri tarafından kabul edilmez ve Microsoft tarafından önerilmez.

Anahtarsız kimlik doğrulamasını etkinleştirme hakkında daha fazla bilgi için bkz. Microsoft Entra ID ile anahtarsız kimlik doğrulamasını yapılandırma.

Microsoft Entra ID ile kimlik doğrulaması (Python)

Aşağıdaki örnek, azure-identity kitaplığını kullanarak Microsoft Entra ID ile kimlik doğrulaması yapmayı ve Bir Foundry uç noktasına istekte bulunmayı gösterir:

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 Foundry scope (https://ai.azure.com/.default)
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>.services.ai.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())

Beklenen çıkış: Model dağıtımlarınızı listeleyen bir JSON yanıtı veya kimlik bilgileri eksikse veya rol ataması yapılandırılmadıysa bir kimlik doğrulama hatası.

Başvuru: DefaultAzureCredential | azure-identity kütüphanesi

API anahtarıyla kimlik doğrulaması (Python)

Aşağıdaki örnekte, API anahtarı kullanarak kimlik doğrulamasının nasıl yapılacağını gösterilmektedir. Yalnızca hızlı prototip oluşturma için bu yaklaşımı kullanın; üretim için Microsoft Entra ID önerilir.

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.services.ai.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())

Uyarı

API anahtarları kaynağa tam erişim sağlar ve kapsamı belirli kullanıcılara veya eylemlere göre ayarlanamaz. Anahtarları düzenli olarak döndürün ve kaynak denetimine kaydetmekten kaçının.

Beklenen çıkış: Model dağıtımlarınızı listeleyen bir JSON yanıtı veya API anahtarı geçersizse 401 hatası.

Başvuru: API erişim anahtarlarını döndürme

Özellik destek matrisi

Foundry desteği API anahtarı ile Microsoft Entra ID arasındaki özellikleri anlamak için aşağıdaki matrise başvurun.

Yetenek veya özellik API anahtarı Microsoft Entra ID Notlar
Temel model çıkarımı (sohbet, eklemeler) Evet Evet Tamamen desteklenmektedir.
hassas ayarlama işlemleri Evet Evet Entra ID sorumlu başına denetim ekler.
Aracılar hizmeti Hayır Evet Yönetilen kimlik aracı erişimi için Entra ID kullanın.
Değerlendirme Hayır Evet Entra ID kullanın.
İçerik güvenliği çağrıları analiz etme Evet Evet Yüksek riskli işlemleri sınırlamak için RBAC kullanın.
Toplu analiz görevleri (İçerik Anlama) Evet Evet Ölçeklendirme için Entra ID önerilir.
Portal oyun alanı kullanımı Evet Evet Playground, proje bağlantı modunu kullanır.
Özel Bağlantı ile ağ yalıtımı Evet Evet Entra ID koşullu erişim ekler.
Yerleşik ve özel rollerle en az ayrıcalık Hayır Evet Anahtarlar her kaynak için hepsi ya da hiçbir şeydir.
Yönetilen kimlik (sistem veya kullanıcı tarafından atanan) Hayır Evet Gizli bilgi gerektirmeyen kimlik doğrulamasını etkinleştirir.
İstek başına kullanıcı atfı Hayır Evet Belirteç, kiracı kimlikleri ve nesne kimliklerini içerir.
İptal (anında) Döndürme tuşu Rolü kaldırma veya sorumluyu devre dışı bırakma Kısa belirteç ömrü geçerlidir.
Otomasyon işlem hatlarında destek Evet (gizli) Evet (hizmet sorumlusu veya yönetilen kimlik) Entra ID gizli anahtar döndürmeyi azaltır.
Yardımcılar API'si Evet Evet Kullanım dışı; 26 Ağustos 2026'da kullanımdan kaldırılır. Foundry Agent Service kullanın.
Toplu tahmin yapma Evet Evet
Araç Kutusu Hayır Evet Yönetilen kimlik aracı erişimi için Entra ID kullanın.

Kimlik türleri

Azure kaynaklar ve uygulamalar, her biri belirli senaryolar için tasarlanmış farklı kimlik türleri kullanarak kimlik doğrulaması yapar. Kullanıcı sorumluları insan kullanıcıları, hizmet sorumluları uygulamaları veya otomatik işlemleri temsil eder ve yönetilen kimlikler Azure kaynaklarının diğer hizmetlere erişmesi için güvenli, kimlik bilgisi olmayan bir yol sağlar. Bu farkları anlamak etkileşimli oturum açma işlemleri, uygulamadan uygulamaya iletişim veya iş yükü otomasyonu için doğru kimliği seçmenize yardımcı olur.

Azure aşağıdaki kimlik türlerini destekler.

Kimlik türü Açıklama
Kullanıcı sorumlusu Microsoft Entra ID içinde bireysel kullanıcı
Hizmet sorumlusu (uygulama kaydı) İstemci sırrı veya sertifika kullanan uygulama kimliği
Yönetilen kimlik (sistem tarafından atanan) Azure tarafından otomatik olarak yönetilen kaynağa bağlı kimlik.
Yönetilen kimlik (kullanıcı tarafından atanan) Birden çok kaynağa bağlanan tek başına kimlik.

Yerleşik rollere genel bakış

Foundry'de, kullanıcının izin verilen eylemlerini ayırmak için yerleşik rolleri kullanın. Çoğu kuruluş, yerleşik rolleri için denetim ve veri düzlemi eylemlerinin ayrılmasını ister. Diğerleri, gerekli rol atamalarının sayısını en aza indirmek için birleştirilmiş bir veri ve denetim düzlemi rolü bekler. Aşağıdaki tabloda senaryolar ve her senaryoya en uygun yerleşik Foundry rolleri listelenmiştir.

Senaryo Tipik yerleşik roller Notlar
Önceden dağıtılmış modellerle ajanlar oluşturun Dökümhane Kullanıcısı Yalnızca veri düzlemi kullanımı; yönetim yazma işlemleri yapılmaz.
Dağıtımları yönetme veya modellerde ince ayar yapma Dökümhane Project Yöneticisi Model dağıtımı oluşturma ve güncelleştirme içerir.
Anahtarları döndürme veya kaynağı yönetme DökümHane Hesabı Sahibi Yüksek ayrıcalık; en az ayrıcalık ilkesine uygun özel bir rol düşünün.
Kaynağı yönetme, dağıtımları yönetme, aracı oluşturma Dökümhane Sahibi Hem kontrol düzlemi hem de veri düzlemi erişimine ihtiyaç duyan kullanıcılar için yüksek ayrıcalıklı self servis rolü. Gözlemlenebilirlik gerekiyorsa Azure İzleyici Okuyucu ile birleştirin.
Gözlemlenebilirlik, takip, izleme Dökümhane Kullanıcısı (en az) Application Insights'a Azure İzleyici Okuyucu ekleyin.

Önemli

Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.

Yerleşik rollerin dökümünü, denetim ve veri düzlemi eylemlerini anlamak için aşağıdaki diyagramı gözden geçirin.

Foundry'de düzlem eylemlerini ve veri düzlemi eylemlerini denetlemek için yerleşik rollerin diyagram eşlemesi.

Ipucu

Yerleşik bir rol, kullanım örneğiniz için fazla izinler verirse özel bir rol oluşturun.

Microsoft Entra ID ayarlama

Foundry'de Entra ID kimlik doğrulamasını ayarlama hakkında üst düzey yönergeler için bkz. Anahtarsız kimlik doğrulamasını yapılandırma.

  1. Microsoft Foundry kaynağınız için özel bir alt etki alanı yapılandırdığınızdan emin olun. Bakınız Özel alt alan adları. Belirteç tabanlı kimlik doğrulaması için özel bir alt etki alanı gereklidir.

  2. Her sorumluya gerekli yerleşik veya özel rolü atayın. Rolleri atamak için hedef kapsamda Sahip veya Kullanıcı Erişimi Yöneticisi rolüne sahip olmanız gerekir. Ortak rol atamaları:

    • Foundry Kullanıcısı: Önceden dağıtılmış modellerle oluşturup test etmesi gereken geliştiriciler için.
    • Foundry Project Manager: Proje oluşturması ve dağıtımları yönetmesi gereken ekip liderleri için.
    • Foundry Hesap Sahibi: Tam kaynak yönetimine ihtiyaç duyan ve veri düzlemi erişimi için gerektiğinde Foundry Kullanıcısı rolünü atayabilen yöneticiler için.
    • Dökümhane Sahibi: Hem tam kaynak yönetimi hem de veri düzlemi erişimine ihtiyaç duyan kullanıcılar için. Dökümhane Kullanıcısı rolünü atamak için örnek CLI komutu:
    az role assignment create \
  --assignee <principal-id> \
  --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>

Note

Foundry RBAC rolleri yakın zamanda yeniden adlandırıldığı için, yeniden adlandırma dağıtımı sırasında sorun yaşamamak için kodunuzda rol adı yerine rol tanımı kimliğini (GUID) kullanın:

  • Dökümhane Kullanıcısı: 53ca6127-db72-4b80-b1b0-d745d6d5456d
  • Dökümhane Sahibi: c883944f-8b7b-4483-af10-35834be79c4a
  • Döküm Hesabı Sahibi: e47c6f54-e4a2-4754-9501-8e0985b135e1
  • Döküm Proje Yöneticisi: eadc314b-1a2d-4efa-be10-5d325db5065e

Rol atamasını doğrulamak için komutunu çalıştırın az role assignment list --assignee <principal-id> --scope <resource-scope> ve rolün çıktıda göründüğünü onaylayın.

  1. (İsteğe bağlı) Hizmet sorumlusu için bir uygulama kaydı oluşturun, bir istemci gizli dizisi veya sertifikası ekleyin ve kiracı kimliğini, istemci kimliğini ve gizli diziyi veya sertifikayı not edin.
  2. (İsteğe bağlı) Yönetilen kimlik için, çağrı hizmetinde sistem tarafından atanan kimliği etkinleştirin veya kullanıcı tarafından atanan bir kimlik ekleyin, ardından Foundry kaynağında bu kimliğe bir rol atayın.
  3. Tüm arayanlar belirteç kimlik doğrulamasını kullandıktan sonra anahtar tabanlı kimlik doğrulamasını kaldırın. İsteğe bağlı olarak dağıtım şablonlarında yerel kimlik doğrulamayı devre dışı bırakın.

Reference: Azure rollerini atama | Foundry için Rol tabanlı erişim denetimi

Yaygın kimlik doğrulama hatalarını giderme

Hata Neden Çözünürlük
401 Yetkisiz Belirteç eksik veya süresi dolmuş; geçersiz API anahtarı Belirteç edinme kapsamının https://ai.azure.com/.default olduğunu doğrulayın. Anahtar tabanlı kimlik doğrulaması kullanıyorsanız API anahtarını yeniden oluşturun.
403 Yasak RBAC rol ataması eksik Kaynak ya da proje düzeyinde uygun yerleşik rolü (örneğin, Foundry User) atayın.
AADSTS700016 Uygulama kiracıda bulunamadı Uygulama kaydının doğru kiracıda mevcut olduğunu ve istemci kimliğinin doğru olduğunu doğrulayın.
Özel subdomain gerekiyor Kaynak, özel alt etki alanı yerine bölgesel uç nokta kullanıyor Dökümhane kaynağında özel bir alt alan adı yapılandırın. Jeton tabanlı kimlik doğrulaması için özel bir alt etki alanı gerekir.

İlgili içerik

  • Last updated on