Condividi tramite

Autenticare le richieste ai servizi di intelligenza artificiale di Azure

  • Articolo

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.

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.

Intestazione Descrizione
Ocp-Apim-Subscription-Key Usare questa intestazione per eseguire l'autenticazione con una chiave della risorsa per un servizio specifico o una chiave della risorsa multiservizio.
Ocp-Apim-Subscription-Region Questa intestazione è necessaria solo quando si usa una chiave della risorsa multiservizio con il servizio Traduttore per Azure AI. 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

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

Avviso

I servizi che supportano i token di accesso possono cambiare nel tempo: controllare le informazioni di riferimento sulle API per un servizio prima di usare questo metodo di autenticazione.

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

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

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

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

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