Autentisera begäranden till Azure AI-tjänster

  • Artikel

Varje begäran till en Azure AI-tjänst måste innehålla ett autentiseringshuvud. Det här huvudet skickar en resursnyckel eller en autentiseringstoken som används för att verifiera din prenumeration för en tjänst eller grupp med tjänster. I den här artikeln får du lära dig om tre sätt att autentisera en begäran och kraven för var och en.

Förutsättningar

Innan du gör en begäran behöver du ett Azure-konto och en Azure AI-tjänstprenumeration. Om du redan har ett konto går du vidare till nästa avsnitt. Om du inte har något konto har vi en guide som hjälper dig att konfigurera på några minuter: Skapa en Azure AI-tjänstresurs.

Gå till din resurs i Azure-portalen. Avsnittet Nycklar och slutpunkter finns i avsnittet Resurshantering . Kopiera slutpunkten och åtkomstnyckeln eftersom du behöver båda för att autentisera dina API-anrop. Du kan använda antingen KEY1 eller KEY2. Om du alltid har två nycklar kan du rotera och återskapa nycklar på ett säkert sätt utan att orsaka avbrott i tjänsten.

Autentiseringshuvuden

Nu ska vi snabbt granska de autentiseringshuvuden som är tillgängliga för användning med Azure AI-tjänster.

Header beskrivning
Ocp-Apim-Subscription-Key Använd det här huvudet för att autentisera med en resursnyckel för en specifik tjänst eller en resursnyckel för flera tjänster.
Ocp-Apim-Subscription-Region Det här huvudet krävs bara när du använder en resursnyckel för flera tjänster med Azure AI Translator-tjänsten. Använd det här huvudet för att ange resursregionen.
Auktorisering Använd den här rubriken om du använder en åtkomsttoken. Stegen för att utföra ett tokenutbyte beskrivs i följande avsnitt. Det angivna värdet följer det här formatet: Bearer <TOKEN>.

Autentisera med en resursnyckel med en enda tjänst

Det första alternativet är att autentisera en begäran med en resursnyckel för en specifik tjänst, till exempel Azure AI Translator. Nycklarna är tillgängliga i Azure-portalen för varje resurs som du har skapat. Gå till din resurs i Azure-portalen. Avsnittet Nycklar och slutpunkter finns i avsnittet Resurshantering . Kopiera slutpunkten och åtkomstnyckeln eftersom du behöver båda för att autentisera dina API-anrop. Du kan använda antingen KEY1 eller KEY2. Om du alltid har två nycklar kan du rotera och återskapa nycklar på ett säkert sätt utan att orsaka avbrott i tjänsten.

Om du vill använda en resursnyckel för att autentisera Ocp-Apim-Subscription-Key en begäran måste den skickas som rubrik. Det här är ett exempelanrop till Azure AI Translator-tjänsten:

Det här är ett exempelanrop till Translator-tjänsten:

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

Autentisera med en resursnyckel för flera tjänster

Du kan använda en resursnyckel för flera tjänster för att autentisera begäranden. Den största skillnaden är att resursnyckeln för flera tjänster inte är kopplad till en specifik tjänst, utan att en enda nyckel kan användas för att autentisera begäranden för flera Azure AI-tjänster. Se Priser för Azure AI-tjänster för information om regional tillgänglighet, funktioner som stöds och priser.

Resursnyckeln anges i varje begäran som Ocp-Apim-Subscription-Key rubrik.

Regioner som stöds

När du använder resursnyckeln för flera tjänster i Azure AI-tjänster för att göra en begäran till api.cognitive.microsoft.commåste du inkludera regionen i URL:en. Exempel: westus.api.cognitive.microsoft.com.

När du använder en resursnyckel för flera tjänster med Azure AI Translator måste du ange resursregionen med Ocp-Apim-Subscription-Region huvudet.

Resursautentisering med flera tjänster stöds i följande regioner:

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

Exempelbegäranden

Det här är ett exempelanrop till Azure AI Translator-tjänsten:

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

Autentisera med en åtkomsttoken

Vissa Azure AI-tjänster accepterar, och i vissa fall kräver, en åtkomsttoken. För närvarande stöder dessa tjänster åtkomsttoken:

  • API för textöversättning
  • Speech Services: API för tal till text
  • Speech Services: API för text till tal

Varning

De tjänster som stöder åtkomsttoken kan ändras över tid. Kontrollera API-referensen för en tjänst innan du använder den här autentiseringsmetoden.

Resursnycklar för både enskild tjänst och flera tjänster kan bytas ut mot autentiseringstoken. Autentiseringstoken är giltiga i 10 minuter. De lagras i JWT-format (JWT) och kan efterfrågas programmatiskt med hjälp av JWT-biblioteken.

Åtkomsttoken ingår i en begäran som Authorization rubrik. Det angivna tokenvärdet måste föregås av Bearer, till exempel: Bearer YOUR_AUTH_TOKEN.

Exempelbegäranden

Använd den här URL:en för att byta ut en resursnyckel mot en åtkomsttoken: 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"

Dessa regioner med flera tjänster stöder tokenutbyte:

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

När du har fått en åtkomsttoken måste du skicka den i varje begäran som Authorization rubrik. Det här är ett exempelanrop till Azure AI Translator-tjänsten:

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

Autentisera med Microsoft Entra ID

Viktigt!

Microsoft Entra-autentisering måste alltid användas tillsammans med det anpassade underdomännamnet för din Azure-resurs. Regionala slutpunkter stöder inte Microsoft Entra-autentisering.

I föregående avsnitt visade vi hur du autentiserar mot Azure AI-tjänster med en prenumerationsnyckel med en enda tjänst eller flera tjänster. Även om dessa nycklar ger en snabb och enkel väg för att börja utveckla, misslyckas de i mer komplexa scenarier som kräver rollbaserad åtkomstkontroll i Azure (Azure RBAC). Nu ska vi ta en titt på vad som krävs för att autentisera med hjälp av Microsoft Entra-ID.

I följande avsnitt använder du antingen Azure Cloud Shell-miljön eller Azure CLI för att skapa en underdomän, tilldela roller och hämta en ägartoken för att anropa Azure AI-tjänsterna. Om du fastnar finns länkar i varje avsnitt med alla tillgängliga alternativ för varje kommando i Azure Cloud Shell/Azure CLI.

Viktigt!

Om din organisation utför autentisering via Microsoft Entra-ID bör du inaktivera lokal autentisering (autentisering med nycklar) så att användare i organisationen alltid måste använda Microsoft Entra-ID.

Skapa en resurs med en anpassad underdomän

Det första steget är att skapa en anpassad underdomän. Om du vill använda en befintlig Azure AI-tjänstresurs som inte har ett anpassat underdomännamn följer du anvisningarna i anpassade underdomäner för Azure AI-tjänster för att aktivera anpassad underdomän för din resurs.

  1. Börja med att öppna Azure Cloud Shell. Välj sedan en prenumeration:

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. Skapa sedan en Azure AI-tjänstresurs med en anpassad underdomän. Underdomännamnet måste vara globalt unikt och får inte innehålla specialtecken, till exempel: ".", "!", ",".

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

  3. Om det lyckas bör slutpunkten visa underdomännamnet som är unikt för resursen.

Tilldela en roll till ett huvudnamn för tjänsten

Nu när du har en anpassad underdomän som är associerad med resursen måste du tilldela en roll till tjänstens huvudnamn.

Kommentar

Tänk på att Azure-rolltilldelningar kan ta upp till fem minuter att sprida.

  1. Först ska vi registrera ett Microsoft Entra-program.

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

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

    Du behöver ApplicationId i nästa steg.

  2. Därefter måste du skapa ett huvudnamn för tjänsten för Microsoft Entra-programmet.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Kommentar

    Om du registrerar ett program i Azure-portalen slutförs det här steget åt dig.

  3. Det sista steget är att tilldela rollen "Cognitive Services-användare" till tjänstens huvudnamn (omfångsbegränsat till resursen). Genom att tilldela en roll ger du tjänstens huvudnamn åtkomst till den här resursen. Du kan ge samma tjänsthuvudnamn åtkomst till flera resurser i din prenumeration.

    Kommentar

    ObjectId för tjänstens huvudnamn används, inte ObjectId för programmet. ACCOUNT_ID blir Azure-resurs-ID för det Azure AI-tjänstkonto som du skapade. Du hittar Azure-resurs-ID från "egenskaper" för resursen i Azure-portalen.

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

Exempelbegäran

I det här exemplet används ett lösenord för att autentisera tjänstens huvudnamn. Den angivna token används sedan för att anropa API:et visuellt innehåll.

  1. Hämta ditt TenantId:

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

  2. Hämta en token:

    $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

    Kommentar

    När du använder lösenord i ett skript är det säkraste alternativet att använda PowerShell Secrets Management-modulen och integrera med en lösning som Azure Key Vault.

  3. Anropa API:et visuellt innehåll:

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

Alternativt kan tjänstens huvudnamn autentiseras med ett certifikat. Förutom tjänstens huvudnamn stöds även användarens huvudnamn genom att ha behörigheter delegerade via ett annat Microsoft Entra-program. I det här fallet, i stället för lösenord eller certifikat, uppmanas användarna att använda tvåfaktorautentisering när de hämtar token.

Auktorisera åtkomst till hanterade identiteter

Azure AI-tjänster stöder Microsoft Entra-autentisering med hanterade identiteter för Azure-resurser. Hanterade identiteter för Azure-resurser kan auktorisera åtkomst till Azure AI-tjänstresurser med hjälp av Microsoft Entra-autentiseringsuppgifter från program som körs på virtuella Azure-datorer (VM), funktionsappar, vm-skalningsuppsättningar och andra tjänster. Genom att använda hanterade identiteter för Azure-resurser tillsammans med Microsoft Entra-autentisering kan du undvika att lagra autentiseringsuppgifter med dina program som körs i molnet.

Aktivera hanterade identiteter på en virtuell dator

Innan du kan använda hanterade identiteter för Azure-resurser för att auktorisera åtkomst till Azure AI-tjänstresurser från den virtuella datorn måste du aktivera hanterade identiteter för Azure-resurser på den virtuella datorn. Information om hur du aktiverar hanterade identiteter för Azure-resurser finns i:

Mer information om hanterade identiteter finns i Hanterade identiteter för Azure-resurser.

Använda Azure Key Vault för säker åtkomst till autentiseringsuppgifter

Du kan använda Azure Key Vault för att på ett säkert sätt utveckla Azure AI-tjänstprogram. Med Key Vault kan du lagra dina autentiseringsuppgifter i molnet och minskar risken för att hemligheter kan läcka ut av misstag, eftersom du inte lagrar säkerhetsinformation i ditt program.

Autentiseringen görs via Microsoft Entra-ID. Auktorisering kan göras via rollbaserad åtkomstkontroll i Azure (Azure RBAC) eller key vault-åtkomstprincip. Azure RBAC kan användas för både hantering av valv och åtkomst till data som lagras i ett valv, medan åtkomstprincip för nyckelvalv endast kan användas när du försöker komma åt data som lagras i ett valv.

Se även