Autenticazione e autorizzazione in Microsoft Foundry

L'autenticazione e l'autorizzazione in Microsoft Foundry controllano il modo in cui le entità dimostrano l'identità e ottengono l'autorizzazione per eseguire operazioni. Foundry divide le operazioni in piano di controllo (gestione delle risorse) e piano dati (utilizzo di runtime), ognuna con la propria superficie di autenticazione e controllo degli accessi in base al ruolo.

Foundry supporta due metodi di autenticazione: Microsoft Entra ID e chiavi API. Microsoft Entra ID abilita l'accesso condizionale, le identità gestite e il controllo degli accessi in base al ruolo granulare. Le chiavi API rimangono disponibili per la creazione rapida di prototipi, ma mancano la tracciabilità per utente. Questo articolo confronta questi metodi, esegue il mapping delle identità ai ruoli e descrive gli scenari di privilegi minimi comuni.

Prerequisiti

• Una sottoscrizione di Azure. Se non ne hai uno, crea un account gratuito.
• Una risorsa Microsoft Foundry con un sottodominio personalizzato configurato.
• Comprensione dei concetti di Azure RBAC.
• Per assegnare i ruoli, è necessario il ruolo Proprietario o Amministratore accesso utenti nell'ambito appropriato.
• (Facoltativo) interfaccia della riga di comando di Azure o Azure SDK per Python installati per l'autenticazione programmatica.
• (Facoltativo) Pacchetti Python per esempi di codice: pip install azure-identity requests

Piano di controllo e piano dati

Le operazioni di Azure si suddividono in due categorie: piano di controllo e piano dati. Azure separa la gestione delle risorse (piano di controllo) dal runtime operativo (piano dati). Pertanto, si utilizza il piano di controllo per gestire le risorse della sottoscrizione e il piano dati per sfruttare le funzionalità messe a disposizione dall'istanza di un tipo di risorsa. Per altre informazioni sul piano di controllo e sul piano dati, vedere Piano di controllo di Azure e piano dati. In Foundry esiste una chiara distinzione tra le operazioni del piano di controllo e le operazioni del piano dati. La tabella seguente illustra la differenza tra i due, l'ambito in Foundry, le operazioni tipiche di un utente, gli strumenti e le funzionalità di esempio e la superficie di autorizzazione per usarli.

Per tutti gli esempi di Bicep, Terraform e SDK, vedere il repository foundry-samples su GitHub per Foundry.

Gli elenchi e i diagrammi seguenti illustrano in dettaglio la separazione tra il piano di controllo e le azioni del piano dati. Le azioni del piano di controllo all'interno di Foundry includono:

• Creazione di risorse della foundry
• Creazione del progetto Foundry
• Creazione dell'host di funzionalità dell'account
• Creazione dell'host funzionalità progetto
• Distribuzione del modello
• Creazione della connessione di account e progetto

Le azioni del piano dati all'interno di Foundry includono:

• Creazione di agenti
• Esecuzione di una valutazione
• Traccia e monitoraggio
• Ottimizzazione

Il diagramma seguente mostra la visualizzazione del piano di controllo rispetto alla separazione del piano dati in Foundry insieme alle assegnazioni di controllo degli accessi in base al ruolo e all'accesso che un utente potrebbe avere nel piano di controllo o nel piano dati o in entrambi. Come illustrato nel diagramma, le "azioni RBAC" sono associate al livello di controllo mentre le "dataActions RBAC" sono associate al livello dati.

Diagramma che illustra la separazione delle operazioni del piano di controllo e del piano dati con le superfici RBAC associate.

Metodi di autenticazione

Foundry supporta l'ID Microsoft Entra (basato su token, senza chiave) e le chiavi API.

Microsoft Entra ID

Microsoft Entra ID usa token di tipo bearer OAuth 2.0 con ambito https://ai.azure.com/.default.

Usare l'ID Microsoft Entra per:

• Carichi di lavoro di produzione.
• Accesso condizionale, autenticazione a più fattori (MFA) e accesso Just-In-Time.
• RBAC con privilegi minimi e integrazione delle identità gestite.

Vantaggi: assegnazioni di ruolo con granularità fine, controllo per entità di sicurezza, durata dei token controllabili, igiene automatica dei segreti e identità gestite per i servizi.

Limitazioni: maggiore complessità di configurazione iniziale. Richiede la comprensione del controllo degli accessi in base al ruolo. Per altre informazioni sul controllo degli accessi in base al ruolo in Foundry, vedere Controllo degli accessi in base al ruolo per Microsoft Foundry.

Chiavi API

Le chiavi API sono segreti statici associati a una risorsa Foundry.

Utilizzare le chiavi API per:

• Prototipazione rapida.
• Ambienti di test isolati in cui la rotazione a segreto singolo è accettabile.

Vantaggi: semplice, indipendente dal linguaggio e non richiede l'acquisizione di token.

Limitazioni: non è possibile esprimere l'identità utente, è difficile definire un ambito granulare ed è più difficile da controllare. In genere non accettato dai carichi di lavoro di produzione aziendali e non consigliato da Microsoft.

Per altre informazioni sull'abilitazione dell'autenticazione senza chiave, vedere Configurare l'autenticazione senza chiave con Microsoft Entra ID.

Eseguire l'autenticazione con Microsoft Entra ID (Python)

L'esempio seguente illustra come eseguire l'autenticazione con l'ID Entra di Microsoft usando la azure-identity libreria e effettuare una richiesta a un endpoint Foundry:

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Cognitive Services scope
token = credential.get_token("https://ai.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Output previsto: una risposta JSON che elenca le distribuzioni del modello o un errore di autenticazione se mancano le credenziali o l'assegnazione di ruolo non è configurata.

Riferimento: DefaultAzureCredential | azure-identity library

Eseguire l'autenticazione con una chiave API (Python)

L'esempio seguente illustra come eseguire l'autenticazione usando una chiave API. Usare questo approccio solo per la creazione rapida di prototipi; Microsoft Entra ID è consigliato per la produzione.

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Output previsto: risposta JSON che elenca le distribuzioni del modello o un errore 401 se la chiave API non è valida.

Riferimento: Ruotare le chiavi di accesso all'API

Matrice di supporto delle funzionalità

Fare riferimento alla matrice seguente per comprendere quali funzionalità in Foundry supportano la chiave API rispetto all'ID Microsoft Entra.

Tipi di identità

Le risorse e le applicazioni di Azure eseguono l'autenticazione usando tipi di identità diversi, ognuno progettato per scenari specifici. Le entità utente rappresentano utenti umani, entità servizio rappresentano applicazioni o processi automatizzati e le identità gestite offrono un modo sicuro e senza credenziali per consentire alle risorse di Azure di accedere ad altri servizi. La comprensione di queste distinzioni consente di scegliere l'identità appropriata per gli accessi interattivi, la comunicazione da app a app o l'automazione del carico di lavoro.

Azure supporta i tipi di identità seguenti.

Panoramica dei ruoli predefiniti

In Foundry usare i ruoli predefiniti per separare le azioni consentite per un utente. La maggior parte delle aziende desidera una separazione tra le azioni del piano di controllo e quelle del piano dati per i ruoli integrati. Altri prevedono un ruolo combinato del piano di controllo e dati per ridurre al minimo il numero di assegnazioni di ruolo necessarie. Nella tabella seguente sono elencati gli scenari e i ruoli predefiniti di Foundry che si adattano meglio a ciascuno scenario.

Per comprendere la suddivisione dei ruoli predefiniti e delle azioni del controllo e del piano dati, esaminare il diagramma seguente.

Configurare Microsoft Entra ID

Per indicazioni generali sulla configurazione dell'autenticazione entra ID in Foundry, vedere Configurare l'autenticazione senza chiave.

1. Verificare che la risorsa Microsoft Foundry abbia un sottodominio personalizzato configurato. Vedere Sottodomini personalizzati. Per l'autenticazione basata su token è necessario un sottodominio personalizzato.

2. Assegna il ruolo predefinito o personalizzato necessario a ciascun principale. Per assegnare ruoli, è necessario il ruolo Proprietario o Amministratore dell'accesso utente nell'ambito di destinazione. Assegnazioni di ruolo comuni:

   • Utente di Intelligenza artificiale di Azure: per gli sviluppatori che devono compilare e testare modelli pre-distribuiti.
   • Azure AI Project Manager: per i responsabili del team che devono creare progetti e gestire le distribuzioni.
   • Proprietario dell'account Azure AI: per gli amministratori che necessitano di una gestione completa delle risorse e possono assegnare condizionalmente l'utente Azure AI per l'accesso al piano dati.
   • Proprietario dell'intelligenza artificiale di Azure: per gli utenti che necessitano sia dell'accesso completo alla gestione delle risorse che al piano dati. Comando CLI di esempio per assegnare il ruolo Azure AI User:

   az role assignment create \
     --assignee <principal-id> \
     --role "Azure AI User" \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
   

   Per verificare l'assegnazione di ruolo, eseguire az role assignment list --assignee <principal-id> --scope <resource-scope> e verificare che il ruolo venga visualizzato nell'output.

3. (Facoltativo) Per un principale del servizio, creare una registrazione dell'app, aggiungere un segreto client o un certificato e annotare l'ID del tenant, l'ID del client e il segreto o il certificato.

4. (Facoltativo) Per un'identità gestita, abilitare l'identità assegnata dal sistema nel servizio chiamante o associare un'identità assegnata dall'utente, quindi assegnare un ruolo alla risorsa Foundry.

5. Rimuovere l'autenticazione basata su chiave dopo che tutti i chiamanti usano l'autenticazione token. Facoltativamente, disabilitare l'autenticazione locale nei modelli di distribuzione.

Riferimento: Assegnare ruoli di Azure | Controllo degli accessi basato sui ruoli per Foundry

Risolvere gli errori di autenticazione comuni

Contenuto correlato

• Controllo degli accessi in base al ruolo per Foundry
• Configurare l'autenticazione senza chiave con Microsoft Entra ID
• Ruotare le chiavi di accesso all'API
• Ruoli predefiniti di Azure (intelligenza artificiale e Machine Learning)
• Autenticazione e autorizzazione (MICROSOFT Entra ID)
• Nozioni fondamentali sulle identità