Autenticare le richieste ai servizi di intelligenza artificiale di Azure

Articolo
10/24/2023

Ogni richiesta a un servizio di intelligenza artificiale di Azure deve includere un'intestazione di autenticazione. Questa intestazione passa lungo una chiave di risorsa o un token di autenticazione, 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
Eseguire l'autenticazione con un token
Eseguire l'autenticazione con Microsoft Entra ID

Prerequisiti

Prima di effettuare una richiesta, sono necessari un account Azure e una sottoscrizione dei servizi di intelligenza artificiale di Azure. Se si dispone già di un account, passare direttamente alla sezione successiva. Se non si ha un account, è disponibile una guida per configurare in pochi minuti: Creare una risorsa multiservizio.

È possibile ottenere la chiave della risorsa dal portale di Azure dopo aver creato l'account.

Intestazioni di autenticazione

Esaminiamo rapidamente le intestazioni di autenticazione disponibili per l'uso con i servizi di intelligenza artificiale di Azure.

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 multiservizio.
Ocp-Apim-Subscription-Region	Questa intestazione è necessaria solo quando si usa una chiave di risorsa multiservizio con il servizio Traduttore. 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>`.

Eseguire l'autenticazione con una chiave di risorsa a servizio singolo

La prima opzione consiste nell'autenticare una richiesta con una chiave di risorsa per un servizio specifico, ad esempio Traduttore. Le chiavi sono disponibili nel portale di Azure per ogni risorsa creata. Per usare una chiave di risorsa per autenticare una richiesta, è necessario passarla come Ocp-Apim-Subscription-Key intestazione.

Queste richieste di esempio illustrano come usare l'intestazione Ocp-Apim-Subscription-Key . Tenere presente che quando si usa questo esempio è necessario includere una chiave di risorsa valida.

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

Il video seguente illustra l'uso di una chiave dei servizi di intelligenza artificiale di Azure.

Eseguire l'autenticazione con una chiave di risorsa multiservizio

È possibile usare una chiave di risorsa multiservizio per autenticare le richieste. La differenza principale è che la chiave di risorsa multiservizio non è associata a un servizio specifico, ma una singola chiave può essere usata per autenticare le richieste per più servizi di intelligenza artificiale di Azure. Per informazioni sulla disponibilità a livello di area, sulle funzionalità supportate e sui prezzi, vedere Prezzi dei servizi di intelligenza artificiale di Azure.

La chiave di risorsa viene fornita in ogni richiesta come Ocp-Apim-Subscription-Key intestazione.

Aree geografiche supportate

Quando si usa la chiave di risorsa multiservizio 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 Azure AI Traduttore, è necessario specificare l'area della risorsa con l'intestazione Ocp-Apim-Subscription-Region .

L'autenticazione 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:

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 intelligenza artificiale di Azure accettano e in alcuni casi richiedono un token di accesso. Attualmente, questi servizi supportano i token di accesso:

API Traduzione testuale
Servizi Voce: API Riconoscimento vocale
Servizi voce: API Sintesi vocale

Nota

Anche QnA Maker usa l'intestazione di autorizzazione, ma richiede una chiave di endpoint. Per altre informazioni, vedere QnA Maker: Ottenere risposte dalla knowledge base.

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.

Sia le chiavi di risorsa a servizio singolo che le chiavi delle risorse multiservizio possono essere scambiate per i token di autenticazione. La validità di un token di autenticazione è di 10 minuti. Vengono archiviati in formato JWT (JSON Web Token) e possono essere sottoposti a query a livello di codice usando le librerie JWT.

I token di accesso sono inclusi in una richiesta come Authorization intestazione. 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 di 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 Authorization intestazione. 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 '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 di sottodominio personalizzato della risorsa di Azure. Gli endpoint a livello di area non supportano l'autenticazione di Microsoft Entra.

Nelle sezioni precedenti è stato illustrato come eseguire l'autenticazione nei servizi di intelligenza artificiale di Azure usando una chiave di sottoscrizione a servizio singolo o multiservizio. Sebbene queste chiavi forniscano 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. Di seguito viene illustrato cosa è necessario per eseguire l'autenticazione usando Microsoft Entra ID.

Nelle sezioni seguenti si userà 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 i servizi di intelligenza artificiale di Azure. Se ci si blocca, i collegamenti vengono forniti in ogni sezione con tutte le opzioni disponibili per ogni comando in Azure Cloud Shell/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 dei servizi di intelligenza artificiale di Azure 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.

Per iniziare, aprire Azure Cloud Shell. Selezionare quindi una sottoscrizione:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```
Creare quindi una risorsa dei servizi di intelligenza artificiale di Azure con un sottodominio personalizzato. Il nome del sottodominio deve essere univoco a livello globale e non può includere caratteri speciali, ad esempio : ".", "!", ",".
```
$account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
```
In caso di esito positivo, l'endpoint deve visualizzare 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.

Prima di tutto, 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 applicationId nel passaggio successivo.

Successivamente, è necessario creare un'entità servizio per l'applicazione Microsoft Entra.
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Nota

Se si registra un'applicazione nel portale di Azure, questo passaggio viene completato.
L'ultimo passaggio consiste nell'assegnare il ruolo "Utente 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

L'ObjectId dell'entità servizio viene usato, non l'ObjectId per l'applicazione. Il ACCOUNT_ID sarà l'ID risorsa di Azure dell'account dei servizi di intelligenza artificiale di Azure creato. È possibile trovare l'ID risorsa di Azure da "proprietà" della risorsa in 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.

Ottenere l'ID tenant:

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

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 e integrarsi con una soluzione come Azure KeyVault.

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

I servizi di intelligenza artificiale di Azure supportano 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 dei 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 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 dei servizi di intelligenza artificiale di Azure 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 intelligenza artificiale di Azure. Key Vault consente di archiviare le credenziali di autenticazione nel cloud e di ridurre le probabilità che i segreti vengano accidentalmente persi, perché 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 può essere usato sia per la gestione degli insiemi di credenziali che per l'accesso ai dati archiviati in un insieme di credenziali, mentre i criteri di accesso dell'insieme di credenziali delle chiavi possono essere usati solo quando si tenta di accedere ai dati archiviati in un insieme di credenziali.

Autenticare le richieste ai servizi di intelligenza artificiale di Azure

Prerequisiti

Intestazioni di autenticazione

Eseguire l'autenticazione con una chiave di risorsa a servizio singolo

Eseguire l'autenticazione con una chiave di risorsa multiservizio

Aree geografiche supportate

Richieste di esempio

Eseguire l'autenticazione con un token di accesso

Richieste di esempio

Eseguire l'autenticazione con ID Microsoft Entra

Creare una risorsa con un sottodominio personalizzato

Assegnare un ruolo a un'entità servizio

Esempio di richiesta

Autorizzare l'accesso alle identità gestite

Abilitare le identità gestite su una macchina virtuale

Usare Azure Key Vault per accedere in modo sicuro alle credenziali

Vedi anche

Risorse aggiuntive