Condividi tramite

Autenticare le richieste agli strumenti Foundry

Ogni richiesta a Foundry Tools 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

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

Intestazioni di autenticazione

È opportuno esaminare rapidamente le intestazioni di autenticazione disponibili per l'uso con Foundry Tools.

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 Fonderia.
Ocp-Apim-Subscription-Region Questa intestazione è necessaria solo quando utilizzi una chiave di risorsa Fonderia con Traduttore di Azure. 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 di risorsa per un servizio specifico, ad esempio Azure Translator. 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. È possibile usare 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 Azure Translator:

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 Foundry

È possibile usare una chiave di risorsa Foundry per autenticare le richieste per più Strumenti Foundry. Le credenziali di autenticazione non sono associate a un servizio specifico. Per informazioni sulla disponibilità a livello di area, sulle funzionalità supportate e sui prezzi, vedere Prezzi degli strumenti Foundry .

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

Aree supportate

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

L'autenticazione delle risorse 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 Azure Translator:

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

  • API Traduzione testuale
  • Voce: API di conversione della voce in testo scritto
  • 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 dei servizi di IA e Fonderia possono essere scambiate per 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 regioni supportano lo scambio di token per le risorse 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 Azure Translator:

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 Microsoft Entra ID

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 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 autenticazione per chiamare gli strumenti Foundry. 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 Foundry esistente che non ha un nome di sottodominio personalizzato, seguire le istruzioni riportate in Foundry Tools sottodomini personalizzati 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 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.

Note

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

  1. 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 l’ApplicationId nel passaggio successivo.

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

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Note

    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.

    Note

    Viene usato l'ObjectId dell'entità servizio e non l'ObjectId per l'applicazione. Il ACCOUNT_ID sarà l'ID risorsa di Azure della risorsa Foundry creata. È 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"

Richiesta di esempio

In questo esempio viene usata una password per autenticare l'entità servizio. Il token fornito viene quindi usato per chiamare l'API Visione 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

    Note

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

Gli strumenti Foundry 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 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 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 Microsoft 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.

Contenuti correlati

  • Last updated on