Události
Ověřování požadavků na služby Azure AI
Každý požadavek na službu Azure AI 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 s jednou službou nebo více službami.
- Ověřte se pomocí tokenu.
- Ověřte se pomocí ID Microsoft Entra.
Před provedením požadavku potřebujete účet Azure a předplatné služeb Azure AI. Pokud už účet máte, přejděte k další části. Pokud účet nemáte, máme průvodce, který vás provede nastavením během několika minut: Vytvoření prostředku služeb Azure AI.
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. Délka klíče se může lišit v závislosti na verzi rozhraní API použité k vytvoření nebo opětovnému vygenerování klíče.
Pojďme se rychle podívat na hlavičky ověřování, které jsou k dispozici pro použití se službami Azure AI.
Hlavička | Popis |
---|---|
Ocp-Apim-Subscription-Key | Tato hlavička slouží k ověření pomocí klíče prostředku pro konkrétní službu nebo klíč prostředku s více službami. |
Ocp-Apim-Subscription-Region | Tato hlavička se vyžaduje jenom v případě, že se službou Azure AI Translator používá klíč prostředku s více službami. 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> . |
První možností je ověření požadavku pomocí klíče prostředku pro konkrétní službu, jako je Azure AI 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 AI 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
K ověření požadavků můžete použít klíč prostředku s více službami . Hlavní rozdíl spočívá v tom, že klíč prostředku s více službami není svázaný s konkrétní službou, ale k ověřování požadavků na více služeb Azure AI je možné použít jeden klíč. Informace o regionální dostupnosti, podporovaných funkcích a cenách najdete v cenách služeb Azure AI.
Klíč prostředku je k dispozici v každém požadavku jako hlavička Ocp-Apim-Subscription-Key
.
Při použití klíče prostředku služby Azure AI pro více služeb k provedení požadavku api.cognitive.microsoft.com
musíte do adresy URL zahrnout oblast. Například: westus.api.cognitive.microsoft.com
.
Při použití klíče prostředku s více službami s Azure AI Translator je nutné zadat oblast prostředků s hlavičkou Ocp-Apim-Subscription-Region
.
Ověřování prostředků s více službami je podporováno 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
Toto je ukázkové volání služby Azure AI 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
Některé služby Azure AI 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
- Speech Services: Rozhraní API pro převod řeči na text
- Speech Services: Rozhraní API pro převod textu na řeč
Upozornění
Služby, které podporují přístupové tokeny, se můžou v průběhu času měnit. Než použijete tuto metodu ověřování, zkontrolujte referenční informace k rozhraní API pro službu.
Pro ověřovací tokeny je možné vyměnit klíče prostředků s jednou službou i více službami. 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 Bearer
například: Bearer YOUR_AUTH_TOKEN
.
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 s více službami podporují výměnu tokenů:
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 AI 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
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 ve službách Azure AI pomocí klíče předplatného s jednou službou nebo více službami. I když tyto klíče poskytují rychlou a snadnou cestu k zahájení vývoje, spadají do složitějších scénářů, které vyžadují řízení přístupu na základě role v Azure (Azure RBAC). Pojďme se podívat, co je potřeba k 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í služeb Azure AI. 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.
Prvním krokem je vytvoření vlastní subdomény. Pokud chcete použít existující prostředek služeb Azure AI, který nemá vlastní název subdomény, postupujte podle pokynů ve vlastních subdoménách služeb Azure AI a povolte vlastní subdoménu pro váš prostředek.
Začněte otevřením Azure Cloud Shellu. Pak vyberte předplatné:
PowerShellSet-AzContext -SubscriptionName <SubscriptionName>
Dále vytvořte prostředek služeb Azure AI s vlastní subdoménou. Název subdomény musí být globálně jedinečný a nesmí obsahovat speciální znaky, například: ".", "!", ",".
PowerShell$account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
V případě úspěchu by měl koncový bod zobrazit název subdomény jedinečný pro váš prostředek.
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.
Nejprve zaregistrujeme aplikaci Microsoft Entra.
PowerShell$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.
Dále musíte vytvořit instanční objekt pro aplikaci Microsoft Entra.
PowerShellNew-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
Poznámka
Pokud zaregistrujete aplikaci na webu Azure Portal, dokončí se tento krok za vás.
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 účtu služeb Azure AI, který jste vytvořili. ID prostředku Azure najdete ve vlastnostech prostředku na webu Azure Portal.
Azure CLINew-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
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 Počítačové zpracování obrazu.
Získejte ID tenanta:
PowerShell$context=Get-AzContext $context.Tenant.Id
Získání tokenu:
PowerShell$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.
Volání rozhraní API Počítačové zpracování obrazu:
PowerShell$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í.
Služby Azure AI podporují ověřování Microsoft Entra se spravovanými identitami pro prostředky Azure. Spravované identity pro prostředky Azure můžou autorizovat přístup k prostředkům služeb Azure AI 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.
Abyste mohli používat spravované identity pro prostředky Azure k autorizaci přístupu k prostředkům služeb Azure AI z 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.
Azure Key Vault můžete použít k bezpečnému vývoji aplikací služeb Azure AI. 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.
Další materiály
Školení
Modul
Úvod k ověřování ve službě Azure OpenAI pomocí .NET s využitím spravované identity - Training
Postup implementace řízení přístupu na základě rolí a ověřování spravovaných identit do Azure OpenAI pomocí .NET
Certifikace
Microsoft Certified: Přidružení správce identit a přístupu - Certifications
Předveďte funkce Microsoft Entra ID pro modernizaci řešení identit, implementaci hybridních řešení a implementaci zásad správného řízení identit.