Ověřování požadavků na nástroje Foundry

Každý požadavek na Foundry Tools musí obsahovat hlavičku ověřování. Tato hlavička předává klíč prostředku nebo ověřovací token, který slouží k ověření předplatného pro službu nebo skupinu služeb. V tomto článku se dozvíte o třech způsobech ověření žádosti a požadavků pro každý z nich.

• Ověřte se pomocí klíče prostředku jednoslužbové služby nebo Foundry multi-service.
• Ověřte se pomocí tokenu.
• Ověřte se pomocí ID Microsoft Entra.

Požadavky

Před provedením požadavku potřebujete předplatné Azure a prostředek Foundry. Pokud potřebujete prostředek Foundry, přečtěte si průvodce vytvořením prostředku Foundry .

Hlavičky ověřování

Pojďme se rychle podívat na hlavičky ověřování, které jsou k dispozici pro použití s Nástroji Foundry.

Hlavička	Popis
Ocp-Apim-Subscription-Key	Tuto hlavičku použijte k ověření pomocí klíče prostředku pro konkrétní službu nebo klíče prostředku Foundry.
Ocp-Apim-Subscription-Region	Tato hlavička se vyžaduje jenom při použití klíče prostředku Foundry s Azure Translatorem. Pomocí této hlavičky zadejte oblast prostředků.
Autorizace	Tuto hlavičku použijte, pokud používáte přístupový token. Kroky k provedení výměny tokenů jsou podrobně popsané v následujících částech. Hodnota zadaná v tomto formátu: Bearer <TOKEN>.

Ověřování pomocí klíče prostředku s jednou službou

První možností je ověřit požadavek pomocí klíče zdroje pro konkrétní službu, jako je Azure Translator. Klíče jsou k dispozici na webu Azure Portal pro každý prostředek, který jste vytvořili. Na webu Azure Portal přejděte ke svému prostředku. Oddíl Klíče a koncový bod najdete v části Správa prostředků. Zkopírujte koncový bod a přístupový klíč, protože budete potřebovat obojí pro ověřování volání rozhraní API. Použít můžete předponu KEY1 nebo KEY2. Vždy mít dva klíče vám umožní bezpečně otáčet a znovu vygenerovat klíče, aniž by to způsobilo přerušení služeb.

Pokud chcete k ověření požadavku použít klíč prostředku, musíte ho předat jako hlavičku Ocp-Apim-Subscription-Key . Toto je ukázkové volání služby Azure Translator:

Toto je ukázkové volání služby Translator:

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

Ověřte se pomocí klíče k prostředku Foundry

Pomocí klíče prostředku Foundry můžete ověřovat požadavky pro více nástrojů Foundry. Přihlašovací údaje pro ověřování nejsou svázané s konkrétní službou. Informace o regionální dostupnosti, podporovaných funkcích a cenách najdete pod tématem Ceny Foundry Tools.

Klíč prostředku je k dispozici v každém požadavku jako hlavička Ocp-Apim-Subscription-Key .

Podporované oblasti

Při použití klíče prostředku Foundry k provedení požadavku na api.cognitive.microsoft.com, musíte zahrnout oblast do adresy URL. Například: westus.api.cognitive.microsoft.com.

Při použití klíče prostředku Foundry s Azure Translatorem je nutné zadat oblast prostředků s hlavičkou Ocp-Apim-Subscription-Region .

Ověřování prostředků Foundry se podporuje v těchto oblastech:

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

Ukázkové požadavky

Toto je ukázkové volání služby Azure Translator:

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

Ověřování pomocí přístupového tokenu

Některé nástroje Foundry přijímají přístupový token a v některých případech vyžadují přístupový token. V současné době tyto služby podporují přístupové tokeny:

• rozhraní API pro překlad textu
• Řeči: Rozhraní API pro převod řeči na text
• Řeči: Rozhraní API pro převod textu na řeč

Upozorňující

Služby, které podporují přístupové tokeny, se můžou v průběhu času měnit, proto před použitím této metody ověřování zkontrolujte referenční informace k rozhraní API pro službu.

Klíče prostředků služby Foundry a AI je možné vyměnit za ověřovací tokeny. Ověřovací tokeny jsou platné 10 minut. Jsou uložené ve formátu JSON Web Token (JWT) a dají se dotazovat programově pomocí knihoven JWT.

Přístupové tokeny jsou součástí požadavku jako hlavička Authorization . Zadaná hodnota tokenu musí předcházet Bearernapříklad: Bearer YOUR_AUTH_TOKEN.

Ukázkové požadavky

Tuto adresu URL použijte k výměně klíče prostředku pro přístupový token: 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"

Tyto oblasti podporují výměnu tokenů pro prostředky Foundry:

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

Po získání přístupového tokenu ho budete muset předat v každém požadavku jako hlavičku Authorization . Toto je ukázkové volání služby Azure Translator:

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

Ověřování pomocí Microsoft Entra ID

Důležité

Ověřování Microsoft Entra musí být vždy použito společně s vlastním názvem subdomény vašeho prostředku Azure. Regionální koncové body nepodporují ověřování Microsoft Entra.

V předchozích částech jsme vám ukázali, jak se ověřovat pomocí klíčů rozhraní API. I když tyto klíče poskytují rychlou a snadnou cestu k zahájení vývoje, jsou krátké ve scénářích, které vyžadují řízení přístupu na základě role v Azure (Azure RBAC). Pojďme se podívat, co je potřeba k bezpečnějšímu ověření pomocí ID Microsoft Entra.

V následujících částech použijete prostředí Azure Cloud Shell nebo Azure CLI k vytvoření subdomény, přiřazení rolí a získání nosný token pro volání Foundry Tools. Pokud se zaseknete, v každé části se zobrazí odkazy se všemi dostupnými možnostmi pro každý příkaz v Azure Cloud Shellu nebo Azure CLI.

Důležité

Pokud vaše organizace provádí ověřování prostřednictvím Microsoft Entra ID, měli byste zakázat místní ověřování (ověřování pomocí klíčů), aby uživatelé v organizaci měli vždy používat Microsoft Entra ID.

Vytvoření prostředku s vlastní subdoménou

Prvním krokem je vytvoření vlastní subdomény. Pokud chcete použít existující prostředek Foundry, který nemá vlastní název subdomény, postupujte podle pokynů v Foundry Tools custom subdomains k umožnění vlastní subdomény pro váš prostředek.

1. Začněte otevřením Azure Cloud Shellu. Pak vyberte předplatné:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Dále vytvořte prostředek Foundry s vlastní subdoménou. Název subdomény musí být globálně jedinečný a nesmí obsahovat speciální znaky, například: ".", "!", ",".

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

3. V případě úspěchu by měl koncový bod zobrazit název subdomény jedinečný pro váš prostředek.

Přiřazení role instančnímu objektu

Teď, když máte vlastní subdoménu přidruženou k vašemu prostředku, budete muset přiřadit roli instančnímu objektu.

Poznámka:

Mějte na paměti, že rozšíření přiřazení rolí Azure může trvat až pět minut.

1. Nejprve zaregistrujeme aplikaci Microsoft Entra.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   V dalším kroku budete potřebovat ID aplikace.

2. Dále musíte vytvořit instanční objekt pro aplikaci Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Poznámka:

   Pokud zaregistrujete aplikaci na webu Azure Portal, dokončí se tento krok za vás.

3. Posledním krokem je přiřazení role Uživatel služeb Cognitive Services k instančnímu objektu (vymezenému prostředku). Přiřazením role udělujete instančnímu objektu přístup k tomuto prostředku. Stejnému instančnímu objektu můžete udělit přístup k více prostředkům ve vašem předplatném.

   Poznámka:

   ObjectId instančního objektu se používá, nikoli ObjectId pro aplikaci. ACCOUNT_ID bude ID prostředku Azure pro prostředek Foundry, který jste vytvořili. ID prostředku Azure najdete ve vlastnostech prostředku na webu Azure Portal.

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

Ukázkový požadavek

V této ukázce se k ověření instančního objektu používá heslo. Poskytnutý token se pak použije k volání rozhraní API služby Azure Vision.

1. Získejte ID tenanta:

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

2. Získání tokenu:

   $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
   

   Poznámka:

   Kdykoli ve skriptu používáte hesla, nejbezpečnější možností je použít modul Pro správu tajných kódů PowerShellu a integrovat je s řešením, jako je Azure Key Vault.

3. Volání rozhraní API služby Azure Vision:

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

Případně se instanční objekt dá ověřit pomocí certifikátu. Kromě instančního objektu se instanční objekt podporuje také tím, že má oprávnění delegovaná prostřednictvím jiné aplikace Microsoft Entra. V takovém případě se uživatelům místo hesel nebo certifikátů při získávání tokenu zobrazí výzva k dvoufaktorovému ověřování.

Autorizace přístupu ke spravovaným identitám

Nástroje Foundry podporují ověřování prostřednictvím Microsoft Entra pomocí spravovaných identit pro prostředky Azure. Spravované identity pro prostředky Azure můžou autorizovat přístup k prostředkům Foundry pomocí přihlašovacích údajů Microsoft Entra z aplikací spuštěných ve virtuálních počítačích Azure, aplikací funkcí, škálovacích sad virtuálních počítačů a dalších služeb. Pomocí spravovaných identit pro prostředky Azure společně s ověřováním Microsoft Entra se můžete vyhnout ukládání přihlašovacích údajů s aplikacemi, které běží v cloudu.

Povolení spravovaných identit na virtuálním počítači

Abyste mohli používat spravované identity pro prostředky Azure k autorizaci přístupu k prostředkům Foundry z vašeho virtuálního počítače, musíte na virtuálním počítači povolit spravované identity pro prostředky Azure. Informace o povolení spravovaných identit pro prostředky Azure najdete tady:

• Azure Portal
• Azure PowerShell
• Azure CLI
• Šablona Azure Resource Manageru
• Klientské knihovny Azure Resource Manageru

Další informace o spravovaných identitách najdete v tématu Spravované identity pro prostředky Azure.

Použití služby Azure Key Vault k bezpečnému přístupu k přihlašovacím údajům

Azure Key Vault můžete použít k bezpečnému vývoji aplikací Microsoft Foundry. Key Vault umožňuje ukládat přihlašovací údaje pro ověřování v cloudu a snižuje riziko náhodného úniku tajných kódů, protože v aplikaci neukládáte bezpečnostní údaje.

Ověřování se provádí prostřednictvím MICROSOFT Entra ID. Autorizace se může provádět prostřednictvím řízení přístupu na základě role (Azure RBAC) nebo zásad přístupu ke službě Key Vault. Azure RBAC se dá použít pro správu trezorů i přístupových dat uložených v trezoru, zatímco zásady přístupu trezoru klíčů se dají použít jenom při pokusu o přístup k datům uloženým v trezoru.

Související obsah

• Co jsou Nástroje Foundry?
• Ceny slévárenských nástrojů
• Vlastní subdomény