Aracılığıyla paylaş

Foundry Araçlarına yönelik isteklerin kimliğini doğrulama

Foundry Araçlarına yönelik her istek bir kimlik doğrulama üst bilgisi içermelidir. Bu üst bilgi, bir hizmet veya hizmet grubu için aboneliğinizi doğrulamak için kullanılan bir kaynak anahtarı veya kimlik doğrulama belirteci ile birlikte geçer. Bu makalede, bir isteğin kimliğini doğrulamanın üç yolu ve her birinin gereksinimleri hakkında bilgi edineceksiniz.

Önkoşullar

İstekte bulunmadan önce bir Azure aboneliğine ve Bir Foundry kaynağına ihtiyacınız vardır. Bir Dökümhane kaynağına ihtiyacınız varsa Bkz. Dökümhane kaynağı oluşturma kılavuzu.

Kimlik doğrulama üst bilgileri

Şimdi Foundry Tools ile kullanılabilen kimlik doğrulama üstbilgilerini hızla gözden geçirelim.

Üst bilgi Açıklama
Ocp-Apim-Subscription-Key Belirli bir hizmet için bir kaynak anahtarıyla veya bir Foundry kaynak anahtarıyla kimlik doğrulaması yapmak için bu üst bilgiyi kullanın.
Ocp-Apim-Subscription-Region Bu üst bilgi yalnızca Azure Translator ile bir Foundry kaynak anahtarı kullanılırken gereklidir. Kaynak bölgesini belirtmek için bu üst bilgiyi kullanın.
Yetkilendirme Erişim belirteci kullanıyorsanız bu üst bilgiyi kullanın. Belirteç değişimi gerçekleştirme adımları aşağıdaki bölümlerde ayrıntılı olarak anlatılır. Sağlanan değer şu biçimdedir: Bearer <TOKEN>.

Tek hizmetli bir kaynak anahtarıyla kimlik doğrulaması yapma

İlk seçenek, Azure Translator gibi belirli bir hizmetin kaynak anahtarıyla isteğin kimliğini doğrulamaktır. Anahtarlar, oluşturduğunuz her kaynak için Azure portalında kullanılabilir. Azure portalında kaynağınıza gidin. Anahtarlar ve Uç Nokta bölümü Kaynak Yönetimi bölümünde bulunabilir. Api çağrılarınızın kimliğini doğrulamak için ihtiyacınız olacak şekilde uç noktanızı ve erişim anahtarınızı kopyalayın. KEY1 veya KEY2 kullanabilirsiniz. Her zaman iki anahtara sahip olmak, hizmet kesintisine neden olmadan anahtarları güvenli bir şekilde döndürmenize ve yeniden oluşturmanıza olanak tanır.

Bir isteğin kimliğini doğrulamak için kaynak anahtarı kullanmak için üst bilgi olarak Ocp-Apim-Subscription-Key geçirilmelidir. Bu, Azure Translator hizmetine örnek bir çağrıdır:

Bu, Translator hizmetine örnek bir çağrıdır:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Dökümhane kaynak anahtarı kullanarak kimlik doğrulaması yapın

Bir Dökümhane kaynak anahtarı, birden çok Döküm Aracı için isteklerin kimliğini doğrulamak amacıyla kullanılabilir. Kimlik doğrulama kimlik bilgileri belirli bir hizmete bağlı değildir. Bölgesel kullanılabilirlik, desteklenen özellikler ve fiyatlandırma hakkında bilgi için Foundry Tools fiyatlandırması sayfasına bkz.

Kaynak anahtarı her istekte üst bilgi olarak Ocp-Apim-Subscription-Key sağlanır.

Desteklenen bölgeler

Foundry kaynak anahtarını kullanarak api.cognitive.microsoft.com öğesine istekte bulunurken, URL'ye bölgeyi eklemeniz gerekir. Örneğin: westus.api.cognitive.microsoft.com.

Azure Translator ile bir Dökümhane kaynak anahtarı kullanırken, Ocp-Apim-Subscription-Region üst bilgisiyle kaynak bölgesini belirtmeniz gerekir.

Dökümhane kaynak kimlik doğrulaması şu bölgelerde desteklenir:

  • australiaeast
  • brazilsouth
  • canadacentral
  • centralindia
  • eastasia
  • eastus
  • japaneast
  • northeurope
  • southcentralus
  • southeastasia
  • uksouth
  • westcentralus
  • westeurope
  • westus
  • westus2
  • francecentral
  • koreacentral
  • northcentralus
  • southafricanorth
  • uaenorth
  • switzerlandnorth

Örnek istekler

Bu, Azure Translator hizmetine örnek bir çağrıdır:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Erişim belirteci ile kimlik doğrulaması

Bazı Döküm Araçları bir erişim belirtecini kabul eder ve bazı durumlarda gerektirir. Şu anda bu hizmetler erişim belirteçlerini desteklemektedir:

  • Metin Çevirisi API'si
  • Konuşmalar: Konuşmayı metin API'sine dönüştürme
  • Konuşmalar: Metin okuma API'si

Uyarı

Erişim belirteçlerini destekleyen hizmetler zaman içinde değişebilir, bu nedenle bu kimlik doğrulama yöntemini kullanmadan önce hizmetin API başvurusunu denetleyin.

Foundry ve AI hizmetleri kaynak anahtarları kimlik doğrulama jetonları için değiştirilebilir. Kimlik doğrulama belirteçleri 10 dakika boyunca geçerlidir. Bunlar JSON Web Belirteci (JWT) biçiminde depolanır ve JWT kitaplıkları kullanılarak program aracılığıyla sorgulanabilir.

Erişim belirteçleri bir isteğe üst bilgi olarak Authorization eklenir. Sağlanan belirteç değerinin Bearerönünde olmalıdır, örneğin: Bearer YOUR_AUTH_TOKEN.

Örnek istekler

Erişim belirteci için kaynak anahtarı değişimi yapmak için şu URL'yi kullanın: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Bu bölgeler, Foundry kaynakları için belirteç değişimini destekler:

  • australiaeast
  • brazilsouth
  • canadacentral
  • centralindia
  • eastasia
  • eastus
  • japaneast
  • northeurope
  • southcentralus
  • southeastasia
  • uksouth
  • westcentralus
  • westeurope
  • westus
  • westus2

Erişim belirtecini aldıktan sonra her istekte üst bilgi olarak Authorization geçirmeniz gerekir. Bu, Azure Translator hizmetine örnek bir çağrıdır:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Microsoft Entra ID ile kimlik doğrulaması

Önemli

Microsoft Entra kimlik doğrulamasının her zaman Azure kaynağınızın özel alt etki alanı adıyla birlikte kullanılması gerekir. Bölgesel uç noktalar Microsoft Entra kimlik doğrulamayı desteklemez.

Önceki bölümlerde API anahtarlarını kullanarak kimlik doğrulaması yapmayı gösterdik. Bu anahtarlar geliştirmeye başlamak için hızlı ve kolay bir yol sağlarken, Azure rol tabanlı erişim denetimi (Azure RBAC) gerektiren senaryolarda yetersiz kalır. Şimdi Microsoft Entra Id kullanarak daha güvenli bir şekilde kimlik doğrulaması yapmak için gerekenlere göz atalım.

Aşağıdaki bölümlerde, Bir alt etki alanı oluşturmak, roller atamak ve Foundry Araçları'nı çağırmak için taşıyıcı belirteç almak için Azure Cloud Shell ortamını veya Azure CLI'yi kullanacaksınız. Takılırsanız, her bölümde Azure Cloud Shell/Azure CLI'daki her komut için tüm kullanılabilir seçenekleri içeren bağlantılar sağlanır.

Önemli

Kuruluşunuz Microsoft Entra Id aracılığıyla kimlik doğrulaması yapıyorsa, kuruluştaki kullanıcıların her zaman Microsoft Entra Id kullanması için yerel kimlik doğrulamasını (anahtarlarla kimlik doğrulama) devre dışı bırakmanız gerekir.

Özel alt etki alanı ile kaynak oluşturma

İlk adım, özel bir alt etki alanı oluşturmaktır. Özel alt etki alanı adı olmayan mevcut bir Dökümhane kaynağını kullanmak istiyorsanız, kaynağınız için özel alt etki alanını etkinleştirmek için Döküm Araçları özel alt etki alanları bölümündeki yönergeleri izleyin.

  1. Azure Cloud Shell'i açarak başlayın. Ardından bir abonelik seçin:

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. Ardından, özel bir alt etki alanına sahip bir Foundry kaynağı oluşturun . Alt etki alanı adının genel olarak benzersiz olması gerekir ve ".", "!", "," gibi özel karakterler içeremez.

    $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>

  3. Başarılı olursa, Uç Nokta kaynağınıza özgü alt etki alanı adını göstermelidir.

Hizmet sorumlusuna rol atama

Artık kaynağınızla ilişkilendirilmiş özel bir alt etki alanınız olduğuna göre, hizmet sorumlusuna bir rol atamanız gerekir.

Not

Azure rol atamalarının yayılması beş dakika kadar sürebilir.

  1. İlk olarak bir Microsoft Entra uygulaması kaydedelim.

    $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force

$app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword

    Sonraki adımda ApplicationId'ye ihtiyacınız olacak.

  2. Ardından, Microsoft Entra uygulaması için bir hizmet sorumlusu oluşturmanız gerekir.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Not

    Bir uygulamayı Azure portalına kaydederseniz, bu adım sizin için tamamlanır.

  3. Son adım, hizmet sorumlusuna (kapsamı kaynak olarak belirlenmiş) "Bilişsel Hizmetler Kullanıcısı" rolünü atamaktır. Rol atayarak bu kaynağa hizmet sorumlusu erişimi verirsiniz. Aboneliğinizdeki birden çok kaynağa aynı hizmet sorumlusu erişimi vekleyebilirsiniz.

    Not

    Hizmet sorumlusunun ObjectId değeri, uygulamanın ObjectId değeri değil kullanılır. ACCOUNT_ID, oluşturduğunuz Dökümhane kaynağının Azure kaynak kimliği olacaktır. Azure portalında kaynağın "özellikleri" bölümünden Azure kaynak kimliğini bulabilirsiniz.

    New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"

Örnek isteği

Bu örnekte, hizmet sorumlusunun kimliğini doğrulamak için bir parola kullanılır. Sağlanan belirteç daha sonra Azure Görüntü İşleme API'sini çağırmak için kullanılır.

  1. TenantId değerini alın:

    $context=Get-AzContext
$context.Tenant.Id

  2. Belirteç alma:

    $tenantId = $context.Tenant.Id
$clientId = $app.ApplicationId
$clientSecret = "<YOUR_PASSWORD>"
$resourceUrl = "https://cognitiveservices.azure.com/"

$tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    resource      = $resourceUrl
}

$responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
$accessToken = $responseToken.access_token

    Not

    Betikte parola kullandığınızda en güvenli seçenek PowerShell Gizli Dizi Yönetimi modülünü kullanmak ve Azure Key Vault gibi bir çözümle tümleştirmektir.

  3. Azure Vision API'sini çağırma:

    $url = $account.Endpoint+"vision/v1.0/models"
$result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
$result | ConvertTo-Json

Alternatif olarak, hizmet sorumlusunun kimliği bir sertifikayla doğrulanabilir. Hizmet sorumlusuna ek olarak, kullanıcı sorumlusu başka bir Microsoft Entra uygulaması aracılığıyla temsilci olarak atanan izinlere sahip olarak da desteklenir. Bu durumda, parolalar veya sertifikalar yerine, belirteç alırken kullanıcılardan iki öğeli kimlik doğrulaması istenir.

Yönetilen kimliklere erişimi yetkilendirme

Foundry Tools, Azure kaynakları için yönetilen kimliklerle Microsoft Entra kimlik doğrulamasını destekler. Azure kaynakları için yönetilen kimlikler, Azure sanal makinelerinde (VM' ler), işlev uygulamalarında, sanal makine ölçek kümelerinde ve diğer hizmetlerde çalışan uygulamalardan Microsoft Entra kimlik bilgilerini kullanarak Foundry kaynaklarına erişim yetkisi verebilir. Azure kaynakları için yönetilen kimlikleri Microsoft Entra kimlik doğrulamasıyla birlikte kullanarak, kimlik bilgilerini bulutta çalışan uygulamalarınızla birlikte depolamaktan kaçınabilirsiniz.

Sanal Makinede (VM) yönetilen kimlikleri etkinleştirme

Vm'nizden Foundry kaynaklarına erişim yetkisi vermek üzere Azure kaynakları için yönetilen kimlikleri kullanabilmeniz için önce VM'de Azure kaynakları için yönetilen kimlikleri etkinleştirmeniz gerekir. Azure kaynakları için yönetilen kimlikleri etkinleştirmeyi öğrenmek için bkz:

Yönetilen kimlikler hakkında daha fazla bilgi için bkz . Azure kaynakları için yönetilen kimlikler.

Kimlik bilgilerine güvenli bir şekilde erişmek için Azure anahtar kasasını kullanma

Microsoft Foundry uygulamalarını güvenli bir şekilde geliştirmek için Azure Key Vault'u kullanabilirsiniz . Key Vault, kimlik doğrulama kimlik bilgilerinizi bulutta depolamanıza olanak tanır ve uygulamanızda güvenlik bilgilerini depolamayacağınız için gizli dizilerin yanlışlıkla sızdırılma olasılığını azaltır.

Kimlik doğrulaması Microsoft Entra Id aracılığıyla yapılır. Yetkilendirme, Azure rol tabanlı erişim denetimi (Azure RBAC) veya Key Vault erişim ilkesi aracılığıyla yapılabilir. Azure RBAC hem kasaların yönetimi hem de kasada depolanan erişim verileri için kullanılabilirken, anahtar kasası erişim ilkesi yalnızca kasada depolanan verilere erişmeye çalışırken kullanılabilir.

İlgili içerik

  • Last updated on