Condividi tramite

Configurare l'autenticazione senza chiave con Microsoft Entra ID

  • Articolo

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

I modelli distribuiti nell'inferenza del modello di intelligenza artificiale di Azure nei servizi di intelligenza artificiale di Azure supportano l'autorizzazione senza chiave usando Microsoft Entra ID. L'autorizzazione senza chiave migliora la sicurezza, semplifica l'esperienza utente, riduce la complessità operativa e offre un supporto affidabile per la conformità per lo sviluppo moderno. È una scelta solida per le organizzazioni che adottano soluzioni di gestione delle identità sicure e scalabili.

Questo articolo illustra come configurare l'ID Entra di Microsoft per l'inferenza nel modello di intelligenza artificiale di Azure.

Comprendere i ruoli nel contesto della risorsa in Azure

Microsoft Entra ID usa l'idea di Controllo di accesso basata su ruoli (RBAC) per l'autorizzazione. I ruoli sono fondamentali per gestire l'accesso alle risorse cloud. Un ruolo è essenzialmente una raccolta di autorizzazioni che definiscono le azioni che possono essere eseguite su risorse di Azure specifiche. Assegnando ruoli a utenti, gruppi, entità servizio o identità gestite, note collettivamente come entità di sicurezza, è possibile controllare l'accesso all'interno dell'ambiente di Azure a risorse specifiche.

Quando si assegna un ruolo, si specifica l'entità di sicurezza, la definizione del ruolo e l'ambito. Questa combinazione è nota come assegnazione di ruolo. L'inferenza del modello di intelligenza artificiale di Azure è una funzionalità delle risorse di Servizi di intelligenza artificiale di Azure e quindi i ruoli assegnati a tale particolare risorsa controllano l'accesso per l'inferenza.

Si identificano due diversi tipi di accesso alle risorse:

  • Accesso all'amministrazione: azioni correlate all'amministrazione della risorsa. In genere modificano lo stato della risorsa e la relativa configurazione. In Azure queste operazioni sono operazioni del piano di controllo e possono essere eseguite usando il portale di Azure, l'interfaccia della riga di comando di Azure o l'infrastruttura come codice. Esempi di includono la creazione di una nuova distribuzione del modello, la modifica delle configurazioni di filtro del contenuto, la modifica della versione del modello gestito o la modifica dello SKU di una distribuzione.

  • Accesso per sviluppatori: le azioni correlate all'utilizzo delle risorse. Ad esempio, richiamare l'API di completamento della chat. Tuttavia, l'utente non può modificare lo stato della risorsa e la relativa configurazione.

In Azure le operazioni di amministrazione vengono sempre eseguite usando Microsoft Entra ID. I ruoli come Collaboratore servizi cognitivi consentono di eseguire tali operazioni. D'altra parte, le operazioni per sviluppatori possono essere eseguite usando chiavi di accesso o/e MICROSOFT Entra ID. I ruoli come l'utente di Servizi cognitivi consentono di eseguire tali operazioni.

Importante

L'accesso amministrativo a una risorsa non concede necessariamente agli sviluppatori l'accesso. L'accesso esplicito concedendo i ruoli è ancora obbligatorio. È analogo al funzionamento dei server di database. L'accesso amministratore al server di database non significa che sia possibile leggere i dati all'interno di un database.

Seguire questa procedura per configurare l'accesso degli sviluppatori all'inferenza del modello di intelligenza artificiale di Azure nella risorsa servizi di intelligenza artificiale di Azure.

Prerequisiti

Per completare questo articolo, devi avere quanto segue:

  • Una sottoscrizione di Azure. Se si usano i modelli GitHub, è possibile aggiornare l'esperienza e creare una sottoscrizione di Azure nel processo. Leggere Eseguire l'aggiornamento da modelli GitHub all'inferenza del modello di intelligenza artificiale di Azure se è il caso.

  • Una risorsa dei servizi di intelligenza artificiale di Azure. Per altre informazioni, vedere Creare una risorsa di Servizi di intelligenza artificiale di Azure.

  • Un account con Microsoft.Authorization/roleAssignments/write autorizzazioni e Microsoft.Authorization/roleAssignments/delete , ad esempio il controllo degli accessi in base al ruolo amministratore .

  • Per assegnare un ruolo, è necessario specificare tre elementi:

    • Entità di sicurezza: ad esempio l'account utente.
    • Definizione del ruolo: ruolo utente di Servizi cognitivi.
    • Ambito: risorsa di Servizi di intelligenza artificiale di Azure.

Configurare l'ID Microsoft Entra per l'inferenza

Seguire questa procedura per configurare Microsoft Entra ID per l'inferenza:

  1. Passare alla portale di Azure e individuare la risorsa di Servizi di intelligenza artificiale di Azure in uso. Se si usa Azure AI Foundry con progetti o hub, è possibile passarvi:

    1. Passare al portale di Azure AI Foundry.

    2. Nella pagina di destinazione selezionare Apri centro di gestione.

    3. Passare alla sezione Risorse connesse e selezionare la connessione alla risorsa di Servizi di intelligenza artificiale di Azure che si vuole configurare. Se non è elencato, selezionare Visualizza tutto per visualizzare l'elenco completo.

    4. Nella sezione Dettagli connessione, in Risorsa selezionare il nome della risorsa di Azure. Si apre una nuova pagina.

    5. Si è ora in portale di Azure in cui è possibile gestire tutti gli aspetti della risorsa stessa.

  2. Sulla barra di spostamento a sinistra selezionare Controllo di accesso (IAM).

    Suggerimento

    Usare l'opzione Visualizza l'accesso personale per verificare quali ruoli sono già assegnati all'utente.

  3. Selezionare Assegnazioni di ruolo e quindi Aggiungi> assegnazione di ruolo.

  4. In Ruoli della funzione processo digitare Utente servizi cognitivi. L'elenco dei ruoli viene filtrato.

  5. Selezionare il ruolo e selezionare Avanti.

  6. In Membri selezionare l'utente o il gruppo a cui si vuole concedere l'accesso. È consigliabile usare i gruppi di sicurezza ogni volta che sono più facili da gestire e gestire.

  7. Selezionare Avanti e completare la procedura guidata.

  8. L'utente selezionato può ora usare Microsoft Entra ID per l'inferenza.

    Suggerimento

    Tenere presente che la propagazione delle assegnazioni di ruolo di Azure può richiedere fino a cinque minuti. Quando si lavora con i gruppi di sicurezza, l'aggiunta o la rimozione di utenti dal gruppo di sicurezza si propaga immediatamente.

Si noti che l'accesso basato su chiave è ancora possibile per gli utenti che dispongono già di chiavi disponibili. Se si desidera revocare le chiavi, nel portale di Azure, nel riquadro di spostamento a sinistra selezionare Chiavi di gestione>risorse ed endpoint>Rigenerare Key1 e Rigenera chiave2.

Usare l'ID Microsoft Entra nel codice

Dopo aver configurato Microsoft Entra ID nella risorsa, è necessario aggiornare il codice per usarlo quando si usa l'endpoint di inferenza. L'esempio seguente illustra come usare un modello di completamento della chat:

Installare il pacchetto azure-ai-inference usando la propria gestione pacchetti, come pip:

pip install azure-ai-inference

Quindi, è possibile usare il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client per utilizzare i completamenti della chat con Entra ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

Opzioni per le credenziali quando si usa Microsoft Entra ID

DefaultAzureCredential è una sequenza ordinata di meccanismi per l'autenticazione in Microsoft Entra ID. Ogni meccanismo di autenticazione è una classe derivata dalla TokenCredential classe ed è nota come credenziale. In fase di esecuzione, DefaultAzureCredential tenta di eseguire l'autenticazione usando la prima credenziale. Se tale credenziale non riesce ad acquisire un token di accesso, viene tentata la credenziale successiva nella sequenza e così via finché non viene ottenuto un token di accesso correttamente. In questo modo, l'app può usare credenziali diverse in ambienti diversi senza scrivere codice specifico dell'ambiente.

Quando il codice precedente viene eseguito nella workstation di sviluppo locale, cerca un'entità servizio dell'applicazione nelle variabili di ambiente o negli strumenti di sviluppo installati localmente, come Visual Studio, per un set di credenziali per sviluppatori. È possibile usare entrambi gli approcci per autenticare l'app nelle risorse di Azure durante lo sviluppo locale.

Dopo la distribuzione in Azure, è possibile anche usare lo stesso codice per autenticare l'app in altre risorse di Azure. DefaultAzureCredential può recuperare automaticamente le impostazioni dell'ambiente e le configurazioni dell'identità gestita per l'autenticazione automatica in altri servizi.

Procedure consigliate

  • Usare credenziali deterministiche negli ambienti di produzione: è consigliabile passare da DefaultAzureCredential a una delle soluzioni deterministiche seguenti negli ambienti di produzione:

    • Una specifica implementazione di TokenCredential, ad esempio ManagedIdentityCredential. Per le opzioni, vedere l'elenco Derivato.
    • Un'implementazione essenziale di ChainedTokenCredential ottimizzata per l'ambiente Azure in cui viene eseguita l'app. ChainedTokenCredential essenzialmente crea un elenco di elementi consentiti specifico di opzioni di credenziali accettabili, ad esempio ManagedIdentity per la produzione e VisualStudioCredential per lo sviluppo.

  • Configurare le identità gestite assegnate dal sistema o assegnate dall'utente alle risorse di Azure in cui il codice è in esecuzione, se possibile. Configurare l'accesso all'ID Entra di Microsoft a tali identità specifiche.

Risoluzione dei problemi

La tabella seguente contiene più scenari che consentono di risolvere i problemi di Microsoft Entra ID:

Errore/Scenario Causa principale Soluzione
Si sta usando un SDK. Problemi noti. Prima di eseguire ulteriori operazioni di risoluzione dei problemi, è consigliabile installare la versione più recente del software in uso per connettersi al servizio. I bug di autenticazione potrebbero essere stati corretti in una versione più recente del software in uso.
401 Principal does not have access to API/Operation La richiesta indica l'autenticazione nel modo corretto, tuttavia, l'entità utente non dispone delle autorizzazioni necessarie per usare l'endpoint di inferenza. Assicurarsi di disporre di:
1. Assegnato il ruolo Utente servizi cognitivi all'entità di sicurezza alla risorsa di Servizi di intelligenza artificiale di Azure.
2. Attendere almeno 5 minuti prima di effettuare la prima chiamata.
401 HTTP/1.1 401 PermissionDenied La richiesta indica l'autenticazione nel modo corretto, tuttavia, l'entità utente non dispone delle autorizzazioni necessarie per usare l'endpoint di inferenza. Assegnato il ruolo Utente servizi cognitivi all'entità di sicurezza nella risorsa di Servizi di intelligenza artificiale di Azure. I ruoli come Amministratore o Collaboratore non accedono in modo complessivo all'inferenza. Attendere almeno 5 minuti prima di effettuare la prima chiamata.
Si usano chiamate API REST e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Verificare che l'intestazione Authentication contenga un token valido con un ambito https://cognitiveservices.azure.com/.default.
Si sta usando AzureOpenAI la classe e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Assicurarsi di usare un modello OpenAI connesso all'endpoint https://<resource>.openai.azure.com. Non è possibile usare OpenAI una classe o un modello Models-as-a-Service. Se il modello non proviene da OpenAI, usare Azure AI Inference SDK.
Si usa Azure AI Inference SDK e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Assicurarsi di essere connessi all'endpoint https://<resource>.services.ai.azure.com/model e di aver indicato l'ambito corretto per Entra ID (https://cognitiveservices.azure.com/.default).
404 Not found L'URL dell'endpoint non è corretto in base all'SDK in uso oppure la distribuzione del modello non esiste. Assicurarsi di usare l'SDK corretto connesso all'endpoint corretto:
1. Se si usa l'SDK di inferenza di Intelligenza artificiale di Azure, assicurarsi che l'endpoint sia https://<resource>.services.ai.azure.com/model presente model="<model-deployment-name>" nei payload o che l'endpoint sia https://<resource>.openai.azure.com/deployments/<model-deployment-name>.
Se si usa la AzureOpenAI classe , verificare che l'endpoint sia https://<resource>.openai.azure.com.

Usare l'ID Microsoft Entra nel progetto

Anche quando la risorsa ha configurato l'ID Microsoft Entra, i progetti potrebbero comunque usare chiavi per utilizzare stime dalla risorsa. Quando si usa il playground di Azure AI Foundry, vengono usate le credenziali associate alla connessione del progetto.

Per modificare questo comportamento, è necessario aggiornare le connessioni dai progetti per usare Microsoft Entra ID. Seguire questa procedura:

  1. Passare al portale di Azure AI Foundry.

  2. Passare ai progetti o agli hub che usano la risorsa di Servizi di intelligenza artificiale di Azure tramite una connessione.

  3. Selezionare Centro gestione.

  4. Passare alla sezione Risorse connesse e selezionare la connessione alla risorsa di Servizi di intelligenza artificiale di Azure che si vuole configurare. Se non è elencato, selezionare Visualizza tutto per visualizzare l'elenco completo.

  5. Nella sezione Dettagli connessione, accanto a Dettagli di accesso, selezionare l'icona di modifica.

  6. In Autenticazione modificare il valore in Microsoft Entra ID.

  7. Selezionare Aggiorna.

  8. La connessione è configurata per l'uso con Microsoft Entra ID ora.

Disabilitare l'autenticazione basata su chiave nella risorsa

La disabilitazione dell'autenticazione basata su chiave è consigliabile quando è stato implementato Microsoft Entra ID e sono stati risolti completamente problemi di compatibilità o fallback in tutte le applicazioni che utilizzano il servizio.

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

I modelli distribuiti nell'inferenza del modello di intelligenza artificiale di Azure nei servizi di intelligenza artificiale di Azure supportano l'autorizzazione senza chiave usando Microsoft Entra ID. L'autorizzazione senza chiave migliora la sicurezza, semplifica l'esperienza utente, riduce la complessità operativa e offre un supporto affidabile per la conformità per lo sviluppo moderno. È una scelta solida per le organizzazioni che adottano soluzioni di gestione delle identità sicure e scalabili.

Questo articolo illustra come configurare l'ID Entra di Microsoft per l'inferenza nel modello di intelligenza artificiale di Azure.

Comprendere i ruoli nel contesto della risorsa in Azure

Microsoft Entra ID usa l'idea di Controllo di accesso basata su ruoli (RBAC) per l'autorizzazione. I ruoli sono fondamentali per gestire l'accesso alle risorse cloud. Un ruolo è essenzialmente una raccolta di autorizzazioni che definiscono le azioni che possono essere eseguite su risorse di Azure specifiche. Assegnando ruoli a utenti, gruppi, entità servizio o identità gestite, note collettivamente come entità di sicurezza, è possibile controllare l'accesso all'interno dell'ambiente di Azure a risorse specifiche.

Quando si assegna un ruolo, si specifica l'entità di sicurezza, la definizione del ruolo e l'ambito. Questa combinazione è nota come assegnazione di ruolo. L'inferenza del modello di intelligenza artificiale di Azure è una funzionalità delle risorse di Servizi di intelligenza artificiale di Azure e quindi i ruoli assegnati a tale particolare risorsa controllano l'accesso per l'inferenza.

Si identificano due diversi tipi di accesso alle risorse:

  • Accesso all'amministrazione: azioni correlate all'amministrazione della risorsa. In genere modificano lo stato della risorsa e la relativa configurazione. In Azure queste operazioni sono operazioni del piano di controllo e possono essere eseguite usando il portale di Azure, l'interfaccia della riga di comando di Azure o l'infrastruttura come codice. Esempi di includono la creazione di una nuova distribuzione del modello, la modifica delle configurazioni di filtro del contenuto, la modifica della versione del modello gestito o la modifica dello SKU di una distribuzione.

  • Accesso per sviluppatori: le azioni correlate all'utilizzo delle risorse. Ad esempio, richiamare l'API di completamento della chat. Tuttavia, l'utente non può modificare lo stato della risorsa e la relativa configurazione.

In Azure le operazioni di amministrazione vengono sempre eseguite usando Microsoft Entra ID. I ruoli come Collaboratore servizi cognitivi consentono di eseguire tali operazioni. D'altra parte, le operazioni per sviluppatori possono essere eseguite usando chiavi di accesso o/e MICROSOFT Entra ID. I ruoli come l'utente di Servizi cognitivi consentono di eseguire tali operazioni.

Importante

L'accesso amministrativo a una risorsa non concede necessariamente agli sviluppatori l'accesso. L'accesso esplicito concedendo i ruoli è ancora obbligatorio. È analogo al funzionamento dei server di database. L'accesso amministratore al server di database non significa che sia possibile leggere i dati all'interno di un database.

Seguire questa procedura per configurare l'accesso degli sviluppatori all'inferenza del modello di intelligenza artificiale di Azure nella risorsa servizi di intelligenza artificiale di Azure.

Prerequisiti

Per completare questo articolo, devi avere quanto segue:

  • Una sottoscrizione di Azure. Se si usano i modelli GitHub, è possibile aggiornare l'esperienza e creare una sottoscrizione di Azure nel processo. Leggere Eseguire l'aggiornamento da modelli GitHub all'inferenza del modello di intelligenza artificiale di Azure se è il caso.

  • Una risorsa dei servizi di intelligenza artificiale di Azure. Per altre informazioni, vedere Creare una risorsa di Servizi di intelligenza artificiale di Azure.

  • Un account con Microsoft.Authorization/roleAssignments/write autorizzazioni e Microsoft.Authorization/roleAssignments/delete , ad esempio il controllo degli accessi in base al ruolo amministratore .

  • Per assegnare un ruolo, è necessario specificare tre elementi:

    • Entità di sicurezza: ad esempio l'account utente.
    • Definizione del ruolo: ruolo utente di Servizi cognitivi.
    • Ambito: risorsa di Servizi di intelligenza artificiale di Azure.

  • Installare l'interfaccia della riga di comando di Azure.

  • Identificare le informazioni seguenti:

    • L'ID sottoscrizione di Azure.

    • Nome della risorsa di Servizi di intelligenza artificiale di Azure.

    • Gruppo di risorse in cui viene distribuita la risorsa di Servizi di intelligenza artificiale di Azure.

Configurare l'ID Microsoft Entra per l'inferenza

Seguire questa procedura per configurare Microsoft Entra ID per l'inferenza nella risorsa di Servizi di intelligenza artificiale di Azure:

  1. Accedere alla sottoscrizione di Azure:

    az login

  2. Se sono presenti più sottoscrizioni, selezionare la sottoscrizione in cui si trova la risorsa:

    az account set --subscription "<subscription-id>"

  3. Impostare le variabili di ambiente seguenti con il nome della risorsa di Servizi di intelligenza artificiale di Azure che si intende usare e il gruppo di risorse.

    ACCOUNT_NAME="<ai-services-resource-name>"
RESOURCE_GROUP="<resource-group>"

  4. Ottenere il nome completo della risorsa:

    RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")

  5. Ottenere l'ID oggetto dell'entità di sicurezza a cui assegnare le autorizzazioni. Nell'esempio seguente viene illustrato come ottenere l'ID oggetto associato a:

    L'account connesso:

    OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)

    Un gruppo di sicurezza:

    OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)

    Un'entità servizio:

    OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)

  6. Assegnare il ruolo utente di Servizi cognitivi all'entità servizio (con ambito alla risorsa). Assegnando un ruolo, si concede all'entità servizio l'accesso a questa risorsa.

    az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID

  7. L'utente selezionato può ora usare Microsoft Entra ID per l'inferenza.

    Suggerimento

    Tenere presente che la propagazione delle assegnazioni di ruolo di Azure può richiedere fino a cinque minuti. L'aggiunta o la rimozione di utenti da un gruppo di sicurezza si propagano immediatamente.

Usare l'ID Microsoft Entra nel codice

Dopo aver configurato l'ID Entra di Microsoft nella risorsa, è necessario aggiornare il codice per usarlo quando si usa l'endpoint di inferenza. L'esempio seguente illustra come usare un modello di completamento della chat:

Installare il pacchetto azure-ai-inference usando la propria gestione pacchetti, come pip:

pip install azure-ai-inference

Quindi, è possibile usare il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client per utilizzare i completamenti della chat con Entra ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

Opzioni per le credenziali quando si usa Microsoft Entra ID

DefaultAzureCredential è una sequenza ordinata di meccanismi per l'autenticazione in Microsoft Entra ID. Ogni meccanismo di autenticazione è una classe derivata dalla TokenCredential classe ed è nota come credenziale. In fase di esecuzione, DefaultAzureCredential tenta di eseguire l'autenticazione usando la prima credenziale. Se tale credenziale non riesce ad acquisire un token di accesso, viene tentata la credenziale successiva nella sequenza e così via finché non viene ottenuto un token di accesso correttamente. In questo modo, l'app può usare credenziali diverse in ambienti diversi senza scrivere codice specifico dell'ambiente.

Quando il codice precedente viene eseguito nella workstation di sviluppo locale, cerca un'entità servizio dell'applicazione nelle variabili di ambiente o negli strumenti di sviluppo installati localmente, come Visual Studio, per un set di credenziali per sviluppatori. È possibile usare entrambi gli approcci per autenticare l'app nelle risorse di Azure durante lo sviluppo locale.

Dopo la distribuzione in Azure, è possibile anche usare lo stesso codice per autenticare l'app in altre risorse di Azure. DefaultAzureCredential può recuperare automaticamente le impostazioni dell'ambiente e le configurazioni dell'identità gestita per l'autenticazione automatica in altri servizi.

Procedure consigliate

  • Usare credenziali deterministiche negli ambienti di produzione: è consigliabile passare da DefaultAzureCredential a una delle soluzioni deterministiche seguenti negli ambienti di produzione:

    • Una specifica implementazione di TokenCredential, ad esempio ManagedIdentityCredential. Per le opzioni, vedere l'elenco Derivato.
    • Un'implementazione essenziale di ChainedTokenCredential ottimizzata per l'ambiente Azure in cui viene eseguita l'app. ChainedTokenCredential essenzialmente crea un elenco di elementi consentiti specifico di opzioni di credenziali accettabili, ad esempio ManagedIdentity per la produzione e VisualStudioCredential per lo sviluppo.

  • Configurare le identità gestite assegnate dal sistema o assegnate dall'utente alle risorse di Azure in cui il codice è in esecuzione, se possibile. Configurare l'accesso all'ID Entra di Microsoft a tali identità specifiche.

Risoluzione dei problemi

La tabella seguente contiene più scenari che consentono di risolvere i problemi di Microsoft Entra ID:

Errore/Scenario Causa principale Soluzione
Si sta usando un SDK. Problemi noti. Prima di eseguire ulteriori operazioni di risoluzione dei problemi, è consigliabile installare la versione più recente del software in uso per connettersi al servizio. I bug di autenticazione potrebbero essere stati corretti in una versione più recente del software in uso.
401 Principal does not have access to API/Operation La richiesta indica l'autenticazione nel modo corretto, tuttavia, l'entità utente non dispone delle autorizzazioni necessarie per usare l'endpoint di inferenza. Assicurarsi di disporre di:
1. Assegnato il ruolo Utente servizi cognitivi all'entità di sicurezza alla risorsa di Servizi di intelligenza artificiale di Azure.
2. Attendere almeno 5 minuti prima di effettuare la prima chiamata.
401 HTTP/1.1 401 PermissionDenied La richiesta indica l'autenticazione nel modo corretto, tuttavia, l'entità utente non dispone delle autorizzazioni necessarie per usare l'endpoint di inferenza. Assegnato il ruolo Utente servizi cognitivi all'entità di sicurezza nella risorsa di Servizi di intelligenza artificiale di Azure. I ruoli come Amministratore o Collaboratore non accedono in modo complessivo all'inferenza. Attendere almeno 5 minuti prima di effettuare la prima chiamata.
Si usano chiamate API REST e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Verificare che l'intestazione Authentication contenga un token valido con un ambito https://cognitiveservices.azure.com/.default.
Si sta usando AzureOpenAI la classe e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Assicurarsi di usare un modello OpenAI connesso all'endpoint https://<resource>.openai.azure.com. Non è possibile usare OpenAI una classe o un modello Models-as-a-Service. Se il modello non proviene da OpenAI, usare Azure AI Inference SDK.
Si usa Azure AI Inference SDK e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Assicurarsi di essere connessi all'endpoint https://<resource>.services.ai.azure.com/model e di aver indicato l'ambito corretto per Entra ID (https://cognitiveservices.azure.com/.default).
404 Not found L'URL dell'endpoint non è corretto in base all'SDK in uso oppure la distribuzione del modello non esiste. Assicurarsi di usare l'SDK corretto connesso all'endpoint corretto:
1. Se si usa l'SDK di inferenza di Intelligenza artificiale di Azure, assicurarsi che l'endpoint sia https://<resource>.services.ai.azure.com/model presente model="<model-deployment-name>" nei payload o che l'endpoint sia https://<resource>.openai.azure.com/deployments/<model-deployment-name>.
Se si usa la AzureOpenAI classe , verificare che l'endpoint sia https://<resource>.openai.azure.com.

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

I modelli distribuiti nell'inferenza del modello di intelligenza artificiale di Azure nei servizi di intelligenza artificiale di Azure supportano l'autorizzazione senza chiave usando Microsoft Entra ID. L'autorizzazione senza chiave migliora la sicurezza, semplifica l'esperienza utente, riduce la complessità operativa e offre un supporto affidabile per la conformità per lo sviluppo moderno. È una scelta solida per le organizzazioni che adottano soluzioni di gestione delle identità sicure e scalabili.

Questo articolo illustra come configurare l'ID Entra di Microsoft per l'inferenza nel modello di intelligenza artificiale di Azure.

Comprendere i ruoli nel contesto della risorsa in Azure

Microsoft Entra ID usa l'idea di Controllo di accesso basata su ruoli (RBAC) per l'autorizzazione. I ruoli sono fondamentali per gestire l'accesso alle risorse cloud. Un ruolo è essenzialmente una raccolta di autorizzazioni che definiscono le azioni che possono essere eseguite su risorse di Azure specifiche. Assegnando ruoli a utenti, gruppi, entità servizio o identità gestite, note collettivamente come entità di sicurezza, è possibile controllare l'accesso all'interno dell'ambiente di Azure a risorse specifiche.

Quando si assegna un ruolo, si specifica l'entità di sicurezza, la definizione del ruolo e l'ambito. Questa combinazione è nota come assegnazione di ruolo. L'inferenza del modello di intelligenza artificiale di Azure è una funzionalità delle risorse di Servizi di intelligenza artificiale di Azure e quindi i ruoli assegnati a tale particolare risorsa controllano l'accesso per l'inferenza.

Si identificano due diversi tipi di accesso alle risorse:

  • Accesso all'amministrazione: azioni correlate all'amministrazione della risorsa. In genere modificano lo stato della risorsa e la relativa configurazione. In Azure queste operazioni sono operazioni del piano di controllo e possono essere eseguite usando il portale di Azure, l'interfaccia della riga di comando di Azure o l'infrastruttura come codice. Esempi di includono la creazione di una nuova distribuzione del modello, la modifica delle configurazioni di filtro del contenuto, la modifica della versione del modello gestito o la modifica dello SKU di una distribuzione.

  • Accesso per sviluppatori: le azioni correlate all'utilizzo delle risorse. Ad esempio, richiamare l'API di completamento della chat. Tuttavia, l'utente non può modificare lo stato della risorsa e la relativa configurazione.

In Azure le operazioni di amministrazione vengono sempre eseguite usando Microsoft Entra ID. I ruoli come Collaboratore servizi cognitivi consentono di eseguire tali operazioni. D'altra parte, le operazioni per sviluppatori possono essere eseguite usando chiavi di accesso o/e MICROSOFT Entra ID. I ruoli come l'utente di Servizi cognitivi consentono di eseguire tali operazioni.

Importante

L'accesso amministrativo a una risorsa non concede necessariamente agli sviluppatori l'accesso. L'accesso esplicito concedendo i ruoli è ancora obbligatorio. È analogo al funzionamento dei server di database. L'accesso amministratore al server di database non significa che sia possibile leggere i dati all'interno di un database.

Seguire questa procedura per configurare l'accesso degli sviluppatori all'inferenza del modello di intelligenza artificiale di Azure nella risorsa servizi di intelligenza artificiale di Azure.

Prerequisiti

Per completare questo articolo, devi avere quanto segue:

  • Una sottoscrizione di Azure. Se si usano i modelli GitHub, è possibile aggiornare l'esperienza e creare una sottoscrizione di Azure nel processo. Leggere Eseguire l'aggiornamento da modelli GitHub all'inferenza del modello di intelligenza artificiale di Azure se è il caso.

  • Una risorsa dei servizi di intelligenza artificiale di Azure. Per altre informazioni, vedere Creare una risorsa di Servizi di intelligenza artificiale di Azure.

  • Un account con Microsoft.Authorization/roleAssignments/write autorizzazioni e Microsoft.Authorization/roleAssignments/delete , ad esempio il controllo degli accessi in base al ruolo amministratore .

  • Per assegnare un ruolo, è necessario specificare tre elementi:

    • Entità di sicurezza: ad esempio l'account utente.
    • Definizione del ruolo: ruolo utente di Servizi cognitivi.
    • Ambito: risorsa di Servizi di intelligenza artificiale di Azure.

Informazioni sull'esercitazione

L'esempio in questo articolo è basato su esempi di codice contenuti nel repository Azure-Samples/azureai-model-inference-bicep . Per eseguire i comandi in locale senza dover copiare o incollare il contenuto del file, usare i comandi seguenti per clonare il repository e passare alla cartella per il linguaggio di codifica:

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

I file per questo esempio si trovano in:

cd azureai-model-inference-bicep/infra

Informazioni sulle risorse

L'esercitazione consente di creare:

  • Una risorsa di Servizi di intelligenza artificiale di Azure con accesso alla chiave disabilitata. Per semplicità, questo modello non distribuisce i modelli.
  • Assegnazione di ruolo per una determinata entità di sicurezza con il ruolo Utente di Servizi cognitivi.

Per creare tali risorse si usano gli asset seguenti:

  1. Usare il modello modules/ai-services-template.bicep per descrivere la risorsa di Servizi di intelligenza artificiale di Azure:

    modules/ai-services-template.bicep

    @description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

    Suggerimento

    Si noti che questo modello può accettare il parametro allowKeys che, quando false disabiliterà l'uso delle chiavi nella risorsa. Questa configurazione è facoltativa.

  2. Usare il modello modules/role-assignment-template.bicep per descrivere un'assegnazione di ruolo in Azure:

    modules/role-assignment-template.bicep

    @description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionID string

@description('Specifies the principal ID assigned to the role.')
param principalId string

@description('Specifies the resource ID of the resource to assign the role to.')
param scopeResourceId string = resourceGroup().id

var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
    principalId: principalId
  }
}

output name string = roleAssignment.name
output resourceId string = roleAssignment.id

Creare le risorse

Nella console seguire questa procedura:

  1. Definire la distribuzione principale:

    deploy-entra-id.bicep

    @description('Location to create the resources in')
param location string = resourceGroup().location

@description('Name of the resource group to create the resources in')
param resourceGroupName string = resourceGroup().name

@description('Name of the AI Services account to create')
param accountName string = 'azurei-models-dev'

@description('ID of the developers to assign the user role to')
param securityPrincipalId string

module aiServicesAccount 'modules/ai-services-template.bicep' = {
  name: 'aiServicesAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    accountName: accountName
    location: location
    allowKeys: false
  }
}

module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
  name: 'roleAssignmentDeveloperAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
    principalId: securityPrincipalId
  }
}

output endpoint string = aiServicesAccount.outputs.endpointUri

  2. Accedere ad Azure:

    az login

  3. Assicurarsi di essere nella sottoscrizione corretta:

    az account set --subscription "<subscription-id>"

  4. Eseguire la distribuzione:

    RESOURCE_GROUP="<resource-group-name>"
SECURITY_PRINCIPAL_ID="<your-security-principal-id>"

az deployment group create \
  --resource-group $RESOURCE_GROUP \
  --securityPrincipalId $SECURITY_PRINCIPAL_ID
  --template-file deploy-entra-id.bicep

  5. Il modello restituisce l'endpoint di inferenza del modello di intelligenza artificiale di Azure che è possibile usare per usare qualsiasi distribuzione del modello creata.

Usare l'ID Microsoft Entra nel codice

Dopo aver configurato Microsoft Entra ID nella risorsa, è necessario aggiornare il codice per usarlo quando si usa l'endpoint di inferenza. L'esempio seguente illustra come usare un modello di completamento della chat:

Installare il pacchetto azure-ai-inference usando la propria gestione pacchetti, come pip:

pip install azure-ai-inference

Quindi, è possibile usare il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client per utilizzare i completamenti della chat con Entra ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

Opzioni per le credenziali quando si usa Microsoft Entra ID

DefaultAzureCredential è una sequenza ordinata di meccanismi per l'autenticazione in Microsoft Entra ID. Ogni meccanismo di autenticazione è una classe derivata dalla TokenCredential classe ed è nota come credenziale. In fase di esecuzione, DefaultAzureCredential tenta di eseguire l'autenticazione usando la prima credenziale. Se tale credenziale non riesce ad acquisire un token di accesso, viene tentata la credenziale successiva nella sequenza e così via finché non viene ottenuto un token di accesso correttamente. In questo modo, l'app può usare credenziali diverse in ambienti diversi senza scrivere codice specifico dell'ambiente.

Quando il codice precedente viene eseguito nella workstation di sviluppo locale, cerca un'entità servizio dell'applicazione nelle variabili di ambiente o negli strumenti di sviluppo installati localmente, come Visual Studio, per un set di credenziali per sviluppatori. È possibile usare entrambi gli approcci per autenticare l'app nelle risorse di Azure durante lo sviluppo locale.

Dopo la distribuzione in Azure, è possibile anche usare lo stesso codice per autenticare l'app in altre risorse di Azure. DefaultAzureCredential può recuperare automaticamente le impostazioni dell'ambiente e le configurazioni dell'identità gestita per l'autenticazione automatica in altri servizi.

Procedure consigliate

  • Usare credenziali deterministiche negli ambienti di produzione: è consigliabile passare da DefaultAzureCredential a una delle soluzioni deterministiche seguenti negli ambienti di produzione:

    • Una specifica implementazione di TokenCredential, ad esempio ManagedIdentityCredential. Per le opzioni, vedere l'elenco Derivato.
    • Un'implementazione essenziale di ChainedTokenCredential ottimizzata per l'ambiente Azure in cui viene eseguita l'app. ChainedTokenCredential essenzialmente crea un elenco di elementi consentiti specifico di opzioni di credenziali accettabili, ad esempio ManagedIdentity per la produzione e VisualStudioCredential per lo sviluppo.

  • Configurare le identità gestite assegnate dal sistema o assegnate dall'utente alle risorse di Azure in cui il codice è in esecuzione, se possibile. Configurare l'accesso all'ID Entra di Microsoft a tali identità specifiche.

Risoluzione dei problemi

La tabella seguente contiene più scenari che consentono di risolvere i problemi di Microsoft Entra ID:

Errore/Scenario Causa principale Soluzione
Si sta usando un SDK. Problemi noti. Prima di eseguire ulteriori operazioni di risoluzione dei problemi, è consigliabile installare la versione più recente del software in uso per connettersi al servizio. I bug di autenticazione potrebbero essere stati corretti in una versione più recente del software in uso.
401 Principal does not have access to API/Operation La richiesta indica l'autenticazione nel modo corretto, tuttavia, l'entità utente non dispone delle autorizzazioni necessarie per usare l'endpoint di inferenza. Assicurarsi di disporre di:
1. Assegnato il ruolo Utente servizi cognitivi all'entità di sicurezza alla risorsa di Servizi di intelligenza artificiale di Azure.
2. Attendere almeno 5 minuti prima di effettuare la prima chiamata.
401 HTTP/1.1 401 PermissionDenied La richiesta indica l'autenticazione nel modo corretto, tuttavia, l'entità utente non dispone delle autorizzazioni necessarie per usare l'endpoint di inferenza. Assegnato il ruolo Utente servizi cognitivi all'entità di sicurezza nella risorsa di Servizi di intelligenza artificiale di Azure. I ruoli come Amministratore o Collaboratore non accedono in modo complessivo all'inferenza. Attendere almeno 5 minuti prima di effettuare la prima chiamata.
Si usano chiamate API REST e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Verificare che l'intestazione Authentication contenga un token valido con un ambito https://cognitiveservices.azure.com/.default.
Si sta usando AzureOpenAI la classe e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Assicurarsi di usare un modello OpenAI connesso all'endpoint https://<resource>.openai.azure.com. Non è possibile usare OpenAI una classe o un modello Models-as-a-Service. Se il modello non proviene da OpenAI, usare Azure AI Inference SDK.
Si usa Azure AI Inference SDK e si ottiene 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La richiesta non riesce a eseguire l'autenticazione con Entra ID. Assicurarsi di essere connessi all'endpoint https://<resource>.services.ai.azure.com/model e di aver indicato l'ambito corretto per Entra ID (https://cognitiveservices.azure.com/.default).
404 Not found L'URL dell'endpoint non è corretto in base all'SDK in uso oppure la distribuzione del modello non esiste. Assicurarsi di usare l'SDK corretto connesso all'endpoint corretto:
1. Se si usa l'SDK di inferenza di Intelligenza artificiale di Azure, assicurarsi che l'endpoint sia https://<resource>.services.ai.azure.com/model presente model="<model-deployment-name>" nei payload o che l'endpoint sia https://<resource>.openai.azure.com/deployments/<model-deployment-name>.
Se si usa la AzureOpenAI classe , verificare che l'endpoint sia https://<resource>.openai.azure.com.

Disabilitare l'autenticazione basata su chiave nella risorsa

La disabilitazione dell'autenticazione basata su chiave è consigliabile quando è stato implementato Microsoft Entra ID e sono stati risolti completamente problemi di compatibilità o fallback in tutte le applicazioni che utilizzano il servizio. È possibile ottenerlo modificando la proprietà disableLocalAuth:

modules/ai-services-template.bicep

@description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

Passaggi successivi