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

  • Cikk

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: Hozzon létre egy többszolgáltatásos erőforrást.

A fiók létrehozása után lekérheti az erőforráskulcsot az Azure Portalról.

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 a Translator szolgáltatással. Ezzel a fejléccel adhatja meg az erőforrás-régiót.
Authorization 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 a Translatorrel. A kulcsok az Azure Portalon érhetők el minden létrehozott erőforráshoz. 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.

Ezek a mintakérések bemutatják a Ocp-Apim-Subscription-Key fejléc használatát. Ne feledje, hogy a minta használatakor érvényes erőforráskulcsot kell tartalmaznia.

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

Az alábbi videó egy Azure AI-szolgáltatáskulcs használatát mutatja be.

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.

Multi-service resource key demonstration for Azure AI services

Supported regions

Ha a többszolgáltatásos erőforráskulcsot használja a kéréshez api.cognitive.microsoft.com, a régiót meg kell adnia az URL-címben. For example: 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 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 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 '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

Megjegyzés:

A QnA Maker az Engedélyezési fejlécet is használja, de egy végpontkulcsot igényel. További információ: QnA Maker: Válasz kérése tudásbázis.

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 a 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.

Megjegyzé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>

    Megjegyzé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.

    Megjegyzé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érés

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

    Megjegyzé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 KeyVault.

  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:

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ó.

Kapcsolódó információk