Autenticazione e autorizzazione in Microsoft Foundry (versione classica)

Visualizzazione attuale:Versione del portale Foundry (versione classica) - Passa alla versione per il nuovo portale 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 basato sui ruoli in modo dettagliato. 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

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

Piano di controllo e piano dati

Le operazioni di Azure sono suddivise 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 nella sottoscrizione e il piano dati per sfruttare le funzionalità esposte dall'istanza di un tipo di risorsa. Per altre informazioni sul piano di controllo e sul piano dati, vedere Azure piano di controllo 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 di host di funzionalità per Project
• 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 fine

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 Microsoft Entra ID (chiavi senza chiave) e chiavi API basate su token.

Microsoft Entra ID

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

Usare Microsoft Entra ID 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, verifica per singola identità, durata dei token controllabile, gestione 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 Microsoft Entra ID usando la libreria azure-identity ed 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 a Microsoft Entra ID.

Tipi di identità

Azure le risorse e le applicazioni eseguono l'autenticazione usando tipi di identità diversi, ognuno progettato per scenari specifici. Le entità utente rappresentano utenti umani, le entità servizio rappresentano applicazioni o processi automatizzati, e le identità gestite offrono un modo sicuro e senza utilizzo di credenziali per consentire alle risorse di Azure l'accesso 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:

   • Azure Utente di intelligenza artificiale: 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 di Azure AI: per gli amministratori che necessitano della gestione completa delle risorse e possono assegnare in modo condizionale Utente di Azure AI per l'accesso al piano dati.
   • Proprietario di Azure AI: per gli utenti che necessitano sia dell'accesso completo alla gestione delle risorse sia dell'accesso 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 tenant, l'ID 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: Assegna ruoli di Azure | Controllo dell'accesso 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
• Azure ruoli predefiniti (intelligenza artificiale e Machine Learning)
• Authentication vs autorizzazione (Microsoft Entra ID)
• Nozioni fondamentali sulle identità