Condividi tramite

Autenticare le richieste ai servizi di intelligenza artificiale di Azure

Ogni richiesta ai servizi di intelligenza artificiale di Azure deve includere un'intestazione di autenticazione. Questa intestazione passa una chiave della risorsa o un token di autenticazione, che viene usato per convalidare la sottoscrizione per un servizio o un gruppo di servizi. Questo articolo descrive i tre modi di autenticare una richiesta e i requisiti per ciascun modo.

  • Eseguire l'autenticazione con una chiave di risorsa a servizio singolo o multiservizio di AI Foundry.
  • Eseguire l'autenticazione con un token.
  • Eseguire l'autenticazione con Microsoft Entra ID.

Prerequisiti

Prima di effettuare una richiesta, è necessaria una sottoscrizione di Azure e una risorsa di Ai Foundry. Se è necessaria una risorsa di AI Foundry, vedere la guida alla creazione di una risorsa di Ai Foundry .

Intestazioni di autenticazione

È opportuno esaminare rapidamente le intestazioni di autenticazione disponibili per l'uso con Servizi di Azure AI.

Intestazione Descrizione
Ocp-Apim-Subscription-Key Usare questa intestazione per eseguire l'autenticazione con una chiave di risorsa per un servizio specifico o una chiave di risorsa di AI Foundry.
Ocp-Apim-Subscription-Region Questa intestazione è richiesta solo quando si utilizza una chiave di risorsa di AI Foundry con il servizio Azure AI Translator. Usare questa intestazione per specificare l'area della risorsa.
Autorizzazione Usare questa intestazione se si usa un token di accesso. Le sezioni seguenti descrivono in dettaglio i passaggi per eseguire uno scambio di token. Il valore specificato segue questo formato: Bearer <TOKEN>.

Autenticazione con una chiave della risorsa a servizio singolo

La prima opzione consiste nell'autenticare una richiesta con una chiave della risorsa per un servizio specifico, ad esempio Traduttore per Azure AI. Le chiavi sono disponibili nel portale di Azure per ogni risorsa creata. Passare alla risorsa nel portale di Azure. La sezione Chiavi ed endpoint è disponibile nella sezione Gestione risorse. Copiare l'endpoint e la chiave di accesso in base alle esigenze per l'autenticazione delle chiamate API. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.

Per usare una chiave della risorsa per autenticare una richiesta, la chiave deve essere passata insieme all'intestazione Ocp-Apim-Subscription-Key. Questa è una chiamata di esempio al servizio Traduttore per Azure AI:

Questa è una chiamata di esempio al servizio Traduttore:

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

Eseguire l'autenticazione con una chiave di risorsa di AI Foundry

È possibile usare una chiave di risorsa di AI Foundry per autenticare le richieste per più servizi di intelligenza artificiale di Azure. Le credenziali di autenticazione non sono associate a un servizio specifico. Per informazioni sulla disponibilità regionale, le funzionalità supportate e i prezzi, vedere Prezzi di Servizi di Azure AI.

La chiave della risorsa viene specificata in ogni richiesta come intestazione Ocp-Apim-Subscription-Key.

Aree geografiche supportate

Quando si usa la chiave di risorsa di AI Foundry per effettuare una richiesta a api.cognitive.microsoft.com, è necessario includere l'area nell'URL. Ad esempio: westus.api.cognitive.microsoft.com.

Quando si usa una chiave di risorsa di AI Foundry con Azure AI Translator, è necessario specificare l'area della risorsa con l'intestazione Ocp-Apim-Subscription-Region .

L'autenticazione delle risorse di AI Foundry è supportata in queste aree:

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

Richieste di esempio

Questa è una chiamata di esempio al servizio Traduttore per Azure AI:

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

Eseguire l'autenticazione con un token di accesso

Alcuni Servizi di Azure AI accettano e, in alcuni casi richiedono, un token di accesso. Attualmente, questi servizi supportano i token di accesso:

  • API Traduzione testuale
  • Servizi Voce: API di riconoscimento vocale
  • Servizi Voce: API di sintesi vocale

Avviso

I servizi che supportano i token di accesso possono cambiare nel tempo, quindi controllare il riferimento API per un servizio prima di usare questo metodo di autenticazione.

Le chiavi delle risorse di AI Foundry e dei servizi di intelligenza artificiale possono essere scambiate con token di autenticazione. La validità di un token di autenticazione è di 10 minuti. Vengono archiviati in formato token JSON Web (JWT) e possono essere sottoposti a query a livello di codice usando le librerie JWT.

I token di accesso sono inclusi in una richiesta come intestazione Authorization. Il valore del token specificato deve essere preceduto da Bearer, ad esempio: Bearer YOUR_AUTH_TOKEN.

Richieste di esempio

Usare questo URL per scambiare una chiave della risorsa per un token di accesso: 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"

Queste aree supportano lo scambio di token per le risorse di AI Foundry:

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

Dopo aver ottenuto un token di accesso, sarà necessario passarlo in ogni richiesta come intestazione Authorization. Questa è una chiamata di esempio al servizio Traduttore per Azure AI:

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

Eseguire l'autenticazione con ID Microsoft Entra

Importante

L'autenticazione di Microsoft Entra deve essere sempre usata insieme al nome del sottodominio personalizzato della risorsa di Azure. Gli endpoint regionali non supportano l'autenticazione tramite Microsoft Entra.

Nelle sezioni precedenti è stato illustrato come eseguire l'autenticazione usando le chiavi API. Sebbene queste chiavi forniscano un percorso rapido e semplice per avviare lo sviluppo, non soddisfano gli scenari che richiedono il controllo degli accessi basato sui ruoli di Azure (Azure RBAC). Di seguito vengono esaminati i requisiti necessari per eseguire l'autenticazione in modo più sicuro usando l'ID Microsoft Entra.

Nelle sezioni seguenti verrà usato l'ambiente Azure Cloud Shell o l'interfaccia della riga di comando di Azure per creare un sottodominio, assegnare ruoli e ottenere un token di connessione per chiamare Servizi di Azure AI. In caso di difficoltà, in ogni sezione vengono forniti i collegamenti con tutte le opzioni disponibili per ogni comando in Azure Cloud Shell o nell’interfaccia della riga di comando di Azure.

Importante

Se l'organizzazione esegue l'autenticazione tramite Microsoft Entra ID, è necessario disabilitare l'autenticazione locale (autenticazione con chiavi) in modo che gli utenti dell'organizzazione debbano usare sempre Microsoft Entra ID.

Creare una risorsa con un sottodominio personalizzato

Il primo passaggio consiste nel creare un sottodominio personalizzato. Se si vuole usare una risorsa di AI Foundry esistente che non ha un nome di sottodominio personalizzato, seguire le istruzioni riportate in Sottodomini personalizzati dei servizi di intelligenza artificiale di Azure per abilitare il sottodominio personalizzato per la risorsa.

  1. Per iniziare, aprire Azure Cloud Shell. Quindi selezionare una sottoscrizione:

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. Creare quindi una risorsa di AI Foundry con un sottodominio personalizzato. Il nome del sottodominio deve essere univoco a livello globale e non può includere caratteri speciali, ad esempio : “.”, “!” e “,”.

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

  3. In caso di esito positivo, l’endpoint dovrebbe mostrare il nome del sottodominio univoco per la risorsa.

Assegnare un ruolo a un'entità servizio

Dopo aver associato un sottodominio personalizzato alla risorsa, è necessario assegnare un ruolo a un'entità servizio.

Nota

Tenere presente che la propagazione delle assegnazioni di ruolo di Azure può richiedere fino a cinque minuti.

  1. Come prima, registrare un'applicazione Microsoft Entra.

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

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

    Sarà necessario l’ApplicationId nel passaggio successivo.

  2. Successivamente, è necessario creare un'entità servizio per l'applicazione di Microsoft Entra.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Nota

    Se si registra un'applicazione nel portale di Azure, questo passaggio viene completato.

  3. L'ultimo passaggio consiste nell'assegnare il ruolo di "Utente di Servizi cognitivi" all'entità servizio, con ambito alla risorsa. Assegnando un ruolo, si concede all'entità servizio l'accesso a questa risorsa. È possibile concedere alla stessa entità servizio l'accesso a più risorse nella sottoscrizione.

    Nota

    Viene usato l'ObjectId dell'entità servizio e non l'ObjectId per l'applicazione. Il ACCOUNT_ID sarà l'ID della risorsa Azure AI Foundry che hai creato. È possibile trovare l'ID risorsa di Azure da "proprietà" della risorsa nel portale di Azure.

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

Esempio di richiesta

In questo esempio viene usata una password per autenticare l'entità servizio. Il token fornito viene quindi usato per chiamare l'API Visione artificiale di Azure.

  1. Ottenere il TenantId:

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

  2. Ottenere un 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

    Nota

    Ogni volta che si usano le password in uno script, l'opzione più sicura consiste nell'usare il modulo di gestione dei segreti di PowerShell integrandolo con una soluzione come Azure Key Vault.

  3. Chiamare l'API Visione artificiale di Azure:

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

In alternativa, l'entità servizio può essere autenticata con un certificato. Oltre all'entità servizio, l'entità utente è supportata anche dalla presenza di autorizzazioni delegate tramite un'altra applicazione di Microsoft Entra. In questo caso, invece di password o certificati, agli utenti verrà richiesta l'autenticazione a due fattori durante l'acquisizione del token.

Autorizzare l'accesso alle identità gestite

Servizi di Azure AI supporta l'autenticazione di Microsoft Entra con identità gestite per le risorse di Azure. Le identità gestite per le risorse di Azure possono autorizzare l'accesso alle risorse di AI Foundry usando le credenziali di Microsoft Entra dalle applicazioni in esecuzione in macchine virtuali di Azure, app per le funzioni, set di scalabilità di macchine virtuali e altri servizi. Usando le identità gestite per le risorse di Azure insieme all'autenticazione di Microsoft Entra, è possibile evitare di archiviare le credenziali con le applicazioni eseguite nel cloud.

Abilitare le identità gestite in una macchina virtuale

Prima di poter usare le identità gestite per le risorse di Azure per autorizzare l'accesso alle risorse di AI Foundry dalla macchina virtuale, è necessario abilitare le identità gestite per le risorse di Azure nella macchina virtuale. Per informazioni su come abilitare le identità gestite per le risorse di Azure, vedere:

Per altre informazioni sulle identità gestite, vedere Identità gestite per le risorse di Azure.

Usare Azure Key Vault per accedere in modo sicuro alle credenziali

È possibile usare Azure Key Vault per sviluppare in modo sicuro applicazioni Azure AI Foundry. Key Vault consente di archiviare le credenziali di autenticazione nel cloud e di ridurre le probabilità che i segreti vengano accidentalmente persi dal momento che non verranno archiviate informazioni di sicurezza nell'applicazione.

L'autenticazione viene eseguita tramite Microsoft Entra ID. L'autorizzazione può essere eseguita tramite il controllo degli accessi in base al ruolo di Azure o i criteri di accesso di Key Vault. Il controllo degli accessi in base al ruolo di Azure (RBAC) può essere usato sia per la gestione degli insieme di credenziali che per l'accesso ai dati archiviati in un insieme di credenziali, mentre i criteri di accesso di un insieme di credenziali delle chiavi possono essere usati solo quando si tenta di accedere ai dati archiviati in un insieme di credenziali.

Contenuto correlato