Autenticare le richieste ai servizi di intelligenza artificiale di Azure

Ogni richiesta a un servizio di Azure AI 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.

• Autenticazione con una chiave della risorsa a servizio singolo o più servizi
• Eseguire l'autenticazione con un token
• Eseguire l'autenticazione con Microsoft Entra ID

Prerequisiti

Per poter effettuare una richiesta, è necessario disporre di un account Azure e di una sottoscrizione di Servizi di Azure AI. Se si dispone già di un account, passare direttamente alla sezione successiva. Se non si dispone dell'account, seguire le indicazioni per crearne uno in pochi minuti: Creare una risorsa dei servizi di Azure AI.

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.

Intestazioni di autenticazione

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

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

Autenticazione con una chiave della risorsa multi-servizio

È possibile usare una chiave della risorsa multi-servizio per autenticare le richieste. La differenza principale è che una chiave della risorsa multi-servizio non è associata a un servizio specifico. Una singola chiave può infatti essere usata per autenticare le richieste per più servizi di Azure AI. 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 della risorsa multi-servizio dei servizi di Azure AI 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 multiservizio con Traduttore per Azure AI, è necessario specificare l'area della risorsa con l'intestazione Ocp-Apim-Subscription-Region.

L'autenticazione della risorsa multiservizio è supportata nelle aree seguenti:

• 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

Entrambe le chiavi della risorsa per servizio singolo e multiservizio possono essere scambiate come 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 multiservizio supportano lo scambio del token:

• 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

Nelle sezioni precedenti è stato illustrato come eseguire l'autenticazione in Servizi di Azure AI usando una chiave di sottoscrizione a servizio singolo o multiservizio. Anche se queste chiavi forniscono un percorso rapido e semplice per avviare lo sviluppo, non rientrano in scenari più complessi che richiedono il controllo degli accessi in base al ruolo di Azure (RBAC). Di seguito viene illustrato cosa è necessario per eseguire l'autenticazione usando Microsoft Entra ID.

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.

Creare una risorsa con un sottodominio personalizzato

Il primo passaggio consiste nel creare un sottodominio personalizzato. Se si vuole usare una risorsa di Servizi di Azure AI esistente, che non dispone di un nome di sottodominio personalizzato, seguire le istruzioni riportate in sottodomini personalizzati di Servizi di Azure AI per abilitare il sottodominio personalizzato per la risorsa.

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

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Successivamente, creare una risorsa di Servizi di Azure AI 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.

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. ACCOUNT_ID sarà l'ID risorsa di Azure dell'account di Servizi di Azure AI 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.

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:

   $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 Servizi di Intelligenza Artificiale di Azure 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 su una macchina virtuale

Prima di poter usare le identità gestite per le risorse di Azure per autorizzare l'accesso alle risorse di Servizi di Azure AI 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:

• Azure portal
• Azure PowerShell
• Interfaccia della riga di comando di Azure
• Modello di Azure Resource Manager
• Librerie client di Azure Resource Manager

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 di Servizi di Azure AI. 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.

Vedi anche

• Che cosa sono i Servizi di Azure AI?
• Prezzi dei servizi di Azure AI
• Sottodomini personalizzati