Az Azure AI-szolgáltatásokhoz érkező kérések hitelesítése

Az Azure AI-szolgáltatáshoz érkező minden kérésnek tartalmaznia kell egy hitelesítési fejlécet. Ez a fejléc egy erőforráskulcs vagy hitelesítési jogkivonat mentén halad át, amely egy szolgáltatás vagy szolgáltatáscsoport előfizetésének ellenőrzésére szolgál. Ebben a cikkben megismerheti a kérések hitelesítésének három módját, valamint az egyes kérelmekre vonatkozó követelményeket.

• Hitelesítés egyszolgáltatásos vagy többszolgáltatásos erőforráskulcs használatával
• Hitelesítés jogkivonattal
• Hitelesítés Microsoft Entra-azonosítóval

Előfeltételek

Mielőtt kérést intéz, szüksége lesz egy Azure-fiókra és egy Azure AI-szolgáltatás-előfizetésre. Ha már rendelkezik fiókkal, ugorjon a következő szakaszra. Ha nem rendelkezik fiókkal, egy útmutatónk segítségével percek alatt beállíthatja a beállításokat: Azure AI-szolgáltatási erőforrás létrehozása.

Nyissa meg az erőforrást az Azure Portalon. A Kulcsok > végpont szakasz az Erőforrás-kezelés szakaszban található. Másolja ki a végpontot és a hozzáférési kulcsot, mivel mindkettőre szüksége lesz az API-hívások hitelesítéséhez. A következők bármelyikét használhatja: KEY1 vagy KEY2. A két kulcs mindig lehetővé teszi a kulcsok biztonságos elforgatását és újragenerálását anélkül, hogy szolgáltatáskimaradást okoz.

Hitelesítési fejlécek

Tekintsük át gyorsan az Azure AI-szolgáltatásokhoz használható hitelesítési fejléceket.

Fejléc	Leírás
Ocp-Apim-Subscription-Key	Ez a fejléc egy adott szolgáltatáshoz vagy többszolgáltatásos erőforráskulcshoz tartozó erőforrás-kulccsal történő hitelesítéshez használható.
Ocp-Apim-Subscription-Region	Ez a fejléc csak akkor szükséges, ha többszolgáltatásos erőforráskulcsot használ az Azure AI Translator szolgáltatással. Ezzel a fejléccel adhatja meg az erőforrás-régiót.
Engedélyezés	Használja ezt a fejlécet, ha hozzáférési jogkivonatot használ. A jogkivonatok cseréjének lépéseit a következő szakaszokban találja. A megadott érték a következő formátumot követi: Bearer <TOKEN>.

Hitelesítés egyszolgáltatásos erőforráskulcs használatával

Az első lehetőség egy kérés hitelesítése egy adott szolgáltatás erőforráskulcsával, például az Azure AI Translatorrel. A kulcsok az Azure Portalon érhetők el minden létrehozott erőforráshoz. Nyissa meg az erőforrást az Azure Portalon. A Kulcsok > végpont szakasz az Erőforrás-kezelés szakaszban található. Másolja ki a végpontot és a hozzáférési kulcsot, mivel mindkettőre szüksége lesz az API-hívások hitelesítéséhez. A következők bármelyikét használhatja: KEY1 vagy KEY2. A két kulcs mindig lehetővé teszi a kulcsok biztonságos elforgatását és újragenerálását anélkül, hogy szolgáltatáskimaradást okoz.

Ha erőforráskulcsot szeretne használni egy kérés hitelesítéséhez, azt fejlécként Ocp-Apim-Subscription-Key kell továbbítani. Ez egy mintahívás az Azure AI Translator szolgáltatáshoz:

Ez egy mintahívás a Translator szolgáltatáshoz:

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

Hitelesítés többszolgáltatásos erőforráskulccsal

A kérések hitelesítéséhez többszolgáltatásos erőforráskulcsot használhat. A fő különbség az, hogy a többszolgáltatásos erőforráskulcs nincs egy adott szolgáltatáshoz kötve, hanem egyetlen kulcs használható több Azure AI-szolgáltatás kéréseinek hitelesítéséhez. Az Azure AI-szolgáltatások díjszabásában tájékozódhat a regionális elérhetőségről, a támogatott funkciókról és a díjszabásról.

Az erőforráskulcsot minden kérés fejlécként Ocp-Apim-Subscription-Key adja meg.

Támogatott régiók

Ha az Azure AI-szolgáltatások többszolgáltatásos erőforráskulcsát használja a kéréshez api.cognitive.microsoft.com, a régiót fel kell vennie az URL-címre. Például: westus.api.cognitive.microsoft.com

Ha többszolgáltatásos erőforráskulcsot használ az Azure AI Translatorrel, meg kell adnia a fejlécet tartalmazó erőforrás-régiótOcp-Apim-Subscription-Region.

A többszolgáltatásos erőforrás-hitelesítés ezekben a régiókban támogatott:

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

Mintakérések

Ez egy mintahívás az Azure AI Translator szolgáltatáshoz:

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

Hitelesítés hozzáférési jogkivonattal

Egyes Azure AI-szolgáltatások elfogadnak és bizonyos esetekben hozzáférési jogkivonatot igényelnek. Jelenleg ezek a szolgáltatások támogatják a hozzáférési jogkivonatokat:

• Szövegfordítási API
• Speech Services: Speech to text API
• Speech Services: Text to speech API

Figyelmeztetés

A hozzáférési jogkivonatokat támogató szolgáltatások idővel változhatnak. A hitelesítési módszer használata előtt ellenőrizze a szolgáltatás API-referenciáit.

Az egyetlen szolgáltatás és a többszolgáltatásos erőforráskulcsok is kicserélhetők hitelesítési jogkivonatokra. A hitelesítési jogkivonatok 10 percig érvényesek. JSON Web Token (JWT) formátumban vannak tárolva, és programozott módon kérdezhetők le a JWT-kódtárak használatával.

A hozzáférési jogkivonatok fejlécként szerepelnek a Authorization kérésekben. A megadott jogkivonat értékét meg kell előznie Bearer, például: Bearer YOUR_AUTH_TOKEN.

Mintakérések

Ezzel az URL-címvel erőforráskulcsot cserélhet egy hozzáférési jogkivonatra: 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"

Ezek a többszolgáltatásos régiók támogatják a tokencserét:

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

Miután beszerezte a hozzáférési jogkivonatot, minden kérésben át kell adnia azt Authorization fejlécként. Ez egy mintahívás az Azure AI Translator szolgáltatáshoz:

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

Hitelesítés Microsoft Entra ID-vel

Fontos

A Microsoft Entra-hitelesítést mindig az Azure-erőforrás egyéni altartománynevével együtt kell használni. A regionális végpontok nem támogatják a Microsoft Entra-hitelesítést.

Az előző szakaszokban bemutattuk, hogyan hitelesíthető az Azure AI-szolgáltatásokon egy vagy többszolgáltatásos előfizetési kulccsal. Bár ezek a kulcsok gyors és egyszerű utat biztosítanak a fejlesztés megkezdéséhez, az azure-beli szerepköralapú hozzáférés-vezérlést (Azure RBAC) igénylő összetettebb forgatókönyvekben hiányozhatnak. Tekintsük át, hogy mi szükséges a Microsoft Entra-azonosítóval történő hitelesítéshez.

A következő szakaszokban az Azure Cloud Shell-környezetet vagy az Azure CLI-t fogja használni egy altartomány létrehozásához, szerepkörök hozzárendeléséhez és egy tulajdonosi jogkivonat beszerzéséhez az Azure AI-szolgáltatások meghívásához. Ha elakad, az egyes szakaszokban hivatkozásokat talál az Azure Cloud Shell/Azure CLI egyes parancsaihoz elérhető összes lehetőséggel.

Fontos

Ha a szervezet a Microsoft Entra-azonosítón keresztül végez hitelesítést, tiltsa le a helyi hitelesítést (kulcsokkal történő hitelesítést), hogy a szervezet felhasználói mindig a Microsoft Entra-azonosítót használják.

Erőforrás létrehozása egyéni altartomány használatával

Az első lépés egy egyéni altartomány létrehozása. Ha olyan meglévő Azure AI-szolgáltatási erőforrást szeretne használni, amely nem rendelkezik egyéni altartománynévvel, kövesse az Azure AI-szolgáltatások egyéni altartományainak utasításait az egyéni altartományok engedélyezéséhez az erőforráshoz.

1. Először nyissa meg az Azure Cloud Shellt. Ezután válasszon ki egy előfizetést:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Ezután hozzon létre egy Azure AI-szolgáltatási erőforrást egy egyéni altartománysal. Az altartomány nevének globálisan egyedinek kell lennie, és nem tartalmazhat speciális karaktereket, például: ".", "!", ",".

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

3. Ha sikeres, a végpontnak az erőforrásra egyedi altartománynevet kell megjelenítenie.

Szerepkör hozzárendelése szolgáltatásnévhez

Most, hogy egyéni altartomány van társítva az erőforráshoz, szerepkört kell hozzárendelnie egy szolgáltatásnévhez.

Feljegyzés

Ne feledje, hogy az Azure-szerepkör-hozzárendelések propagálása akár öt percet is igénybe vehet.

1. Először regisztráljunk egy Microsoft Entra-alkalmazást.

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

   A következő lépésben szüksége lesz az ApplicationId azonosítóra .

2. Ezután létre kell hoznia egy szolgáltatásnevet a Microsoft Entra-alkalmazáshoz.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Feljegyzés

   Ha regisztrál egy alkalmazást az Azure Portalon, ez a lépés befejeződik.

3. Az utolsó lépés a "Cognitive Services-felhasználó" szerepkör hozzárendelése a szolgáltatásnévhez (az erőforrás hatóköre). Szerepkör hozzárendelésével szolgáltatásnév-hozzáférést biztosít ehhez az erőforráshoz. Ugyanahhoz a szolgáltatásnévhez több erőforráshoz is hozzáférést adhat az előfizetésében.

   Feljegyzés

   A rendszer a szolgáltatásnév ObjectId azonosítóját használja, nem az alkalmazás ObjectId azonosítóját. A ACCOUNT_ID a létrehozott Azure AI-szolgáltatásfiók Azure-erőforrás-azonosítója lesz. Az Azure-erőforrás-azonosítót az erőforrás "tulajdonságai" között találja az Azure Portalon.

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

Mintakérelem

Ebben a példában egy jelszóval hitelesíti a szolgáltatásnevet. A megadott jogkivonat ezután a Computer Vision API meghívására szolgál.

1. A TenantId lekérése:

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

2. Jogkivonat lekérése:

   $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
   

   Feljegyzés

   Amikor jelszavakat használ egy szkriptben, a legbiztonságosabb megoldás a PowerShell Titkos kódok kezelése modul használata, és integrálható egy olyan megoldással, mint az Azure Key Vault.

3. Hívja meg a Computer Vision API-t:

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

Másik lehetőségként a szolgáltatásnév hitelesítése tanúsítványsal is lehetséges. A szolgáltatásnév mellett a felhasználónevét is támogatja egy másik Microsoft Entra-alkalmazáson keresztül delegált engedélyek. Ebben az esetben jelszavak vagy tanúsítványok helyett a rendszer kétfaktoros hitelesítést kér a felhasználóktól a jogkivonat beszerzésekor.

Felügyelt identitásokhoz való hozzáférés engedélyezése

Az Azure AI-szolgáltatások támogatják a Microsoft Entra-hitelesítést az Azure-erőforrások felügyelt identitásaival. Az Azure-erőforrások felügyelt identitásai a Microsoft Entra hitelesítő adataival engedélyezhetik az Azure AI-szolgáltatások erőforrásaihoz való hozzáférést az Azure-beli virtuális gépeken (virtuális gépeken), függvényalkalmazásokban, virtuálisgép-méretezési csoportokban és egyéb szolgáltatásokban futó alkalmazásokból. Ha felügyelt identitásokat használ az Azure-erőforrásokhoz a Microsoft Entra-hitelesítéssel együtt, elkerülheti a hitelesítő adatok tárolását a felhőben futó alkalmazásokkal.

Felügyelt identitások engedélyezése virtuális gépen

Mielőtt felügyelt identitásokat használhat az Azure-erőforrásokhoz az Azure AI-szolgáltatások erőforrásaihoz való hozzáférés engedélyezéséhez a virtuális gépről, engedélyeznie kell a felügyelt identitásokat a virtuális gépen lévő Azure-erőforrásokhoz. Ha tudni szeretné, hogyan engedélyezheti a felügyelt identitásokat az Azure-erőforrásokhoz, tekintse meg a következőt:

• Azure Portalra
• Azure PowerShell
• Azure CLI
• Azure Resource Manager-sablon
• Azure Resource Manager-ügyfélkódtárak

A felügyelt identitásokról további információt az Azure-erőforrások felügyelt identitásai című témakörben talál.

Hitelesítő adatok biztonságos elérése az Azure Key Vault használatával

Az Azure Key Vault használatával biztonságosan fejleszthet Azure AI-szolgáltatási alkalmazásokat. A Key Vault lehetővé teszi a hitelesítési hitelesítő adatok felhőben való tárolását, és csökkenti annak esélyét, hogy a titkos kulcsok véletlenül kiszivárogjanak, mert nem fogja tárolni a biztonsági adatokat az alkalmazásban.

A hitelesítés a Microsoft Entra-azonosítón keresztül történik. Az engedélyezés azure-beli szerepköralapú hozzáférés-vezérléssel (Azure RBAC) vagy Key Vault hozzáférési szabályzattal végezhető el. Az Azure RBAC a tárolók kezelésére és a tárolóban tárolt adatok elérésére egyaránt használható, míg a Key Vault hozzáférési szabályzata csak a tárolóban tárolt adatok elérésének megkísérlésekor használható.

Lásd még

• Mik azok az Azure AI-szolgáltatások?
• Az Azure AI-szolgáltatások díjszabása
• Egyéni altartományok