Autentisera begäranden till Azure AI-tjänster

Varje anrop till Azure AI-tjänster måste innehålla en autentiseringsheader. 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.

• Autentisera med en resursnyckel med en enda tjänst eller AI Foundry-resursnyckel för flera tjänster .
• Autentisera med en token.
• Autentisera med Microsoft Entra-ID.

Förutsättningar

Innan du gör en begäran behöver du en Azure-prenumeration och en AI Foundry-resurs. Om du behöver en AI Foundry-resurs kan du läsa guiden skapa en AI Foundry-resurs .

Autentiseringshuvuden

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

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 Portal för varje resurs som du har skapat. Gå till resursen i Azure Portal. 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 AI Foundry-resursnyckel

Du kan använda en AI Foundry-resursnyckel för att autentisera begäranden för flera Azure AI-tjänster. Autentiseringsuppgifterna är inte kopplade till en specifik tjänst. 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 AI Foundry 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 AI Foundry-resursnyckel med Azure AI Translator måste du ange resursregionen med Ocp-Apim-Subscription-Region huvud.

AI Foundry-resursautentisering 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

Resursnycklar för AI Foundry och AI-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 stöder tokenutbyte för AI Foundry-resurser:

• 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

I föregående avsnitt visade vi hur du autentiserar med hjälp av API-nycklar. Även om dessa nycklar ger en snabb och enkel väg för att börja utveckla, misslyckas de i 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 på ett säkrare sätt 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.

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 AI Foundry-resurs 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 AI Foundry-resurs 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.

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 Portal 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. Den ACCOUNT_ID är Azure-resurs-ID:t för AI Foundry-resursen som du skapade. Du hittar Azure-resurs-ID:t 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 Azure AI Vision API.

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 för Azure AI Vision:

   $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 AI Foundry-resurser 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 (VM)

Innan du kan använda hanterade identiteter för Azure-resurser för att auktorisera åtkomst till AI Foundry-resurser 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:

• Azure Portal
• Azure PowerShell
• Azure CLI
• Azure Resource Manager-mall
• Azure Resource Manager-klientbibliotek

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 Foundry-program. 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.

Relaterat innehåll

• Vad är Azure AI-tjänster?
• Prissättning för Azure AI-tjänster
• Anpassade underdomäner