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. Foundry, her biri kendi kimlik doğrulama ve rol tabanlı erişim denetimi (RBAC) yüzeyine sahip kontrol düzlemi (kaynak yönetimi) ve veri düzlemi (çalışma zamanı kullanımı) işlemlerine ayırır.

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 kaba taneli erişim sağlar.

Önkoşullar

• Azure aboneliği. Hesabınız yoksa ücretsiz bir hesap oluşturun.
• Özel alt alan adı yapılandırılmış bir Microsoft Foundry kaynağı.
• Azure RBAC kavramlarını anlama.
• Rolleri atamak için uygun kapsamda Sahip rolüne veya Kullanıcı Erişimi Yöneticisi rolüne sahip olmanız gerekir.
• (İsteğe bağlı) Programlı kimlik doğrulama için Azure CLI veya Python için Azure SDK yüklendi.
• (İsteğe bağlı) Kod örnekleri için Python paketleri: pip install azure-identity requests

Kontrol düzlemi ve veri düzlemi

Azure işlemleri iki kategoriye ayrılır: denetim 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. Denetim düzlemi ve veri düzlemi hakkında daha fazla bilgi edinmek için bkz. Azure denetim 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	Foundry'de Kapsam	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ını çalıştırma ve kullanma, temsilci etkileşimleri, değerlendirme işleri ve içerik güvenliği çağrıları	Sohbet tamamlamaları, gömme oluşturma, ince ayar işlerini 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 Bkz. Foundry için GitHub'daki foundry-samples deposu .

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 denetim düzlemi işlemleri şunlardır:

• Dökümhane kaynağı oluşturma
• Dökümhane projesi oluşturma
• Hesap Özellik Sunucusu 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
• İz Takibi ve İzleme
• Fine-tuning

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.

Kimlik doğrulama yöntemleri

Foundry, Microsoft Entra Id (belirteç tabanlı, anahtarsız) ve API anahtarlarını destekler.

Microsoft Entra Kimliği

Microsoft Entra ID, belirtilen kapsamı https://cognitiveservices.azure.com/.default olan 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ı, kişi başına denetim, kontrol edilebilir belirteç ömürleri, otomatik gizli bilgi hijyeni ve hizmetlere yönelik yönetilen kimlikler.

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

API anahtarları

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

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

• Hızlı prototip oluşturma.
• Tek gizli dizi döndürmenin kabul edilebilir olduğu yalıtılmış test ortamları.

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

Sınırlamalar: Kullanıcı kimliğini ifade edemez, kapsamı ayrıntılı bir şekilde belirlemek zordur ve denetlemesi daha zordur. 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 (Python) ile kimlik doğrulaması

Aşağıdaki örnekte, azure-identity kitaplığını kullanarak Microsoft Entra ID ile kimlik doğrulaması yapma ve bir Foundry uç noktasına istekte bulunma gösterilmektedir.

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://cognitiveservices.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())

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 library

API anahtarıyla kimlik doğrulama (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>.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())

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'deki hangi özelliklerin API anahtarı yerine Microsoft Entra ID tarafından desteklendiğini anlamak için aşağıdaki matrise başvurun.

Yetenek veya özellik	API anahtarı	Microsoft Entra Kimliği	Notlar
Temel model çıkarımı (sohbet, eklemeler)	Evet	Evet	Tamamen destekleniyor.
hassas ayarlama işlemleri	Evet	Evet	Entra Id, sorumlu başına denetim ekler.
Ajana hizmeti	Hayı	Evet	Yönetilen kimlik aracı erişimi için Entra Id kullanın.
Evaluations	Hayı	Evet	Entra Id kullanın.
İçerik güvenliği analiz çağrıları	Evet	Evet	Yüksek riskli işlemleri sınırlamak için RBAC kullanın.
Toplu analiz işleri (İçerik Anlama)	Evet	Evet	Ölçek için Entra Kimliği tavsiye edilir.
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ı	Evet	Anahtarlar her kaynak için tümü veya hiçbir şeyi ifade etmez.
Yönetilen kimlik (sistem veya kullanıcı atamalı)	Hayı	Evet	Parolasız kimlik doğrulamayı etkinleştirir.
İstek başına kullanıcı atfı	Hayı	Evet	Token, kiracı ve nesne kimliklerini içerir.
İptal (anında)	Döndürme tuşu	Rolü kaldırma veya sorumluyu devre dışı bırakma	Kısa süreli belirteç ömrü geçerlidir.
Otomasyon işlem hatlarında destek	Evet (gizli)	Evet (hizmet sorumlusu veya yönetilen kimlik)	Entra ID gizli anahtar dönüşümünü azaltır.
Asistanlar API	Evet	Evet	Entra Kimliğinin kullanılması önerilir.
Toplu çıkarım	Evet	Evet

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ü	Description
Kullanıcı sorumlusu	Microsoft Entra Id'de tek tek kullanıcı
Service principal (uygulama kaydı)	İstemci gizli anahtarı veya sertifika kullanan uygulama kimliği
Yönetilen kimlik (sistem atamalı)	Platform tarafından otomatik olarak yönetilen Azure kaynakla ilişkilendirilmiş 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.

Scenario	Tipik yerleşik roller	Notlar
Önceden dağıtılmış modeller kullanarak aracı oluşturma	Azure AI Kullanıcısı	Yalnızca veri düzlemi kullanımı; yönetimsel yazma işlemleri yok.
Dağıtımları yönetme veya modellerde ince ayar yapma	Azure AI Proje Yöneticisi	Model dağıtımı oluşturma ve güncelleştirme içerir.
Anahtarları döndürme veya kaynağı yönetme	Azure AI Hesabı Sahibi	Yüksek ayrıcalık; en az ayrıcalık için özel rolü göz önünde bulundurun.
Kaynağı yönetme, dağıtımları yönetme, aracı oluşturma	Azure AI 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 Okuyucusu ile birleştirin.
Gözlemlenebilirlik, iz sürme, izleme	Azure AI Kullanıcısı (minimum)	Application Insights'a Azure İzleyici Okuyucusu ekleme.

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

Tavsiye

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

Microsoft Entra Kimliğini 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ızda özel bir alt etki alanı ayarlandığından emin olun. Bkz. Özel alt etki alanları. 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ı:

   • Azure AI Kullanıcısı: Geliştiricilerin önceden dağıtılmış modellerle oluşturma ve test yapması için.
   • Azure AI Proje Yöneticisi: Proje oluşturması ve dağıtımları yönetmesi gereken ekip liderleri için.
   • Azure AI Hesabı Sahibi: Tam kaynak yönetimine ihtiyaç duyan ve veri düzlemi erişimi için Azure AI Kullanıcısını koşullu olarak atayabilen yöneticiler için.
   • Azure AI Sahibi: Hem tam kaynak yönetimi hem de veri düzlemi erişimine ihtiyaç duyan kullanıcılar için. Azure AI Kullanıcı rolünü atamak için örnek CLI komutu:

   az role assignment create \
     --assignee <principal-id> \
     --role "Azure AI User" \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
   

   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.

3. (İsteğe bağlı) Hizmet ilkesi için bir uygulama kaydı oluşturun, bir istemci gizli anahtarı veya sertifikası ekleyin ve kiracı kimliği, istemci kimliği ve gizli anahtar veya sertifikayı not edin.

4. (İ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.

5. Tüm arayanlar belirteç kimlik doğrulaması kullanmaya başladıktan sonra anahtar tabanlı kimlik doğrulamayı kaldırın. İsteğe bağlı olarak dağıtım şablonlarında yerel kimlik doğrulamayı devre dışı bırakın.

Referans: Azure rolleri atama | Foundry için rol tabanlı erişim denetimi

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

Hata	Nedeni	Çözüm
401 Yetkisiz	Belirteç eksik veya süresi dolmuş; geçersiz API anahtarı	Belirteç alma kapsamının https://cognitiveservices.azure.com/.default olduğunu doğrulayın. Anahtar tabanlı kimlik doğrulaması kullanıyorsanız API anahtarını yeniden oluşturun.
403 Yasak	Bir RBAC rol ataması eksik	Kaynak veya proje kapsamında uygun yerleşik rolü (örneğin Azure AI Kullanıcısı) atayın.
AADSTS700016	Kiracı hesabında uygulama bulunamadı	Uygulama kaydının doğru kiracıda mevcut olduğunu ve istemci kimliğinin doğru olduğunu doğrulayın.
Özelleştirilmiş alt etki alanı 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

• Foundry için rol tabanlı erişim denetimi
• Microsoft Entra ID ile anahtarsız kimlik doğrulamayı yapılandırma
• API erişim anahtarlarını döndürme
• Azure yerleşik rolleri (AI + makine öğrenmesi)
• Kimlik doğrulaması ve yetkilendirme (Microsoft Entra Id)
• Kimlik temelleri