Usa l'identità gestita a livello di database con database SQL di Azure (anteprima)

Si applica a:Database SQL di Azure

L'identità gestita a livello di database conferisce a un singolo database in database SQL di Azure una propria identità gestita assegnata dall'utente (UAMI). Un database con un’identità gestita si autentica su Archiviazione di Azure come se stesso, invece che come server logico che lo ospita.

Senza un'identità a livello di database, ogni database su un server logico condivide l'identità gestita di quel server, quindi tutti raggiungono lo stesso storage. Un'identità a livello di database restringe l'accesso a un singolo database, così puoi concedere a ogni database solo lo spazio di archiviazione di cui ha bisogno.

Si seleziona l'identità in una credenziale con ambito di database, la stessa credenziale che le query di virtualizzazione dei dati usano per leggere file Parquet, CSV e Delta da Archiviazione BLOB di Azure o Azure Data Lake Storage (ADLS) Gen2. Scegli tra due valori di identità delle credenziali:

Prerequisites

• Un database SQL di Azure su un server logico. Tutti i livelli di servizio e tutte le regioni Azure supportano questa funzione.
• Un'identità gestita assegnata dall'utente nella stessa sottoscrizione. Per contesto, vedi Managed identities in Microsoft Entra for Azure SQL.
• Permesso di assegnare ruoli all'account di archiviazione target, come Proprietario o Amministratore Accesso Utente.
• Un account di Archiviazione BLOB di Azure o di ADLS Gen2 che contiene i file che vuoi interrogare.

Scegli stesso tenant o tra tenant

Entrambi i walkthrough creano una credenziale con ambito di database e interrogano dati esterni. Differiscono nel modo in cui l'identità arriva all'account di archiviazione.

• Se il database e l'account di archiviazione sono nello stesso tenant, segui Usare un'identità a livello di database nello stesso tenant.
• Se l'account di archiviazione è in un altro tenant, segui Usa un'identità client federata tra i tenant.

Usa un'identità a livello di database nello stesso tenant

Passaggio 1: Creare un'identità gestita assegnata dall'utente

Crea l'identità e annota sia il suo ID Risorsa che il suo ID Oggetto (principale). Serve l'ID della Risorsa per assegnare l'identità al database. Serve l'ID Oggetto (principale) solo per la guida cross-tenant, dove identifica il soggetto della credenziale di identità federata.

az identity create \
    --name <identity-name> \
    --resource-group <resource-group> \
    --location <region>

Per altri metodi, vedi Gestisci le identità gestite assegnate dall'utente.

Passo 2: Assegna l'identità al database

Assegna l'UAMI al database, non al server logico. Questa assegnazione utilizza lo stesso meccanismo della crittografia trasparente dei dati a livello di database (TDE) con chiavi gestite dal cliente, descritto in Chiavi gestite dal cliente a livello di database. Per l'insieme completo di metodi di assegnazione, vedi Get o imposta un'identità gestita per un database.

Per assegnare l'identità nel portale Azure:

1. Vai al tuo database SQL.
2. In Sicurezza selezionare Identità.
3. Sotto User-Assigned Managed Identity, seleziona Aggiungi.
4. Seleziona l'identità che hai creato, poi seleziona Aggiungi.
5. Selezionare Salva.

Per assegnare l'identità con la interfaccia della riga di comando di Azure, usa az sql db update:

az sql db update \
    --resource-group <resource-group> \
    --server <server-name> \
    --name <database-name> \
    --assign-identity \
    --user-assigned-identity-id <identity-resource-id>

Per assegnarlo con PowerShell, usa Set-AzSqlDatabase:

Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId>

L'identità ID risorsa appare come /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>. Trovalo sotto Proprietà sull'identità gestita nel portale Azure.

Passo 3: Concedere all'identità l'accesso allo storage

Dai all'identità gestita accesso in lettura all'account di archiviazione:

1. Accedi all'account di archiviazione.
2. Seleziona Controllo di accesso (IAM).
3. Seleziona Aggiungi>Aggiungi assegnazione di ruolo.
4. Seleziona il ruolo Storage Blob Data Reader, poi seleziona Next.
5. In Assegna accesso a, selezionare Identità gestita.
6. Seleziona Seleziona membri, scegli la tua identità gestita assegnata dall'utente e quindi seleziona Seleziona.
7. Selezionare Verifica e assegna.

Per un accesso più dettagliato su ADLS Gen2, impostare liste di controllo degli accessi (ACL) su directory specifiche invece di assegnare un ruolo a livello di account. Per ulteriori informazioni, consulta le liste di controllo degli accessi in Azure Data Lake Storage.

Passo 4: Crea la credenziale con ambito database

Connettiti al tuo database utenti, non master, e crea la credenziale:

CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';

Questa credenziale non necessita di chiave segreta né di chiave maestra del database. Il motore risolve l'identità assegnata al database al momento della query.

L'equivalente a livello di server utilizza un valore identità diverso. Confrontare:

-- Server-level identity: every database on the logical server shares this access
CREATE DATABASE SCOPED CREDENTIAL MyServerIdentityCred
WITH IDENTITY = 'MANAGED IDENTITY';

-- Database-level identity: only this database has this access
CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';

Per la sintassi completa, vedi CREATE DATABASE SCOPED CREDENTIAL.

Passo 5: Crea la fonte dati esterna

Crea una fonte di dati esterna che punti al tuo container e allega la credenziale. Usa il prefisso che corrisponde al tipo di archiviazione:

CREATE EXTERNAL DATA SOURCE MyExternalStorage
WITH (
    LOCATION = 'abs://<container>@<storage-account>.blob.core.windows.net',
    CREDENTIAL = MyDBIdentityCred
);

Passo 6: Interroga i dati

Interroga i file ad hoc con OPENROWSET:

SELECT TOP 100 *
FROM OPENROWSET(
    BULK 'sales/2026/*.parquet',
    DATA_SOURCE = 'MyExternalStorage',
    FORMAT = 'parquet'
) AS externalData;

Oppure definisci una tabella esterna per query ripetute:

CREATE EXTERNAL FILE FORMAT ParquetFormat
WITH (FORMAT_TYPE = PARQUET);

CREATE EXTERNAL TABLE dbo.Sales
(
    OrderId int,
    OrderDate date,
    Amount decimal(10, 2)
)
WITH (
    LOCATION = 'sales/2026/',
    DATA_SOURCE = MyExternalStorage,
    FILE_FORMAT = ParquetFormat
);

SELECT TOP 100 * FROM dbo.Sales;

Usa un'identità cliente federata tra i tenant

Usa questo percorso quando il tuo database è in un tenant e l'account storage in un altro. Una registrazione di un'applicazione multitenant veicola il rapporto di trust tra di essi: l'UAMI del database è oggetto di una credenziale di identità federata su quell'applicazione, e il tenant di storage concede al principale di servizio dell'applicazione l'accesso ai dati.

Il pattern corrisponde a chiavi gestite dal cliente cross-tenant per la crittografia trasparente dei dati, quindi la configurazione risulterà familiare se già usi questa funzione.

Passo 1: Registra un'applicazione multi-tenant

Nel tenant che contiene il database, registra un'applicazione multitenant in Microsoft Entra ID e annota il suo Application (client) ID.

Per altre informazioni, vedere Registrare un'applicazione con Microsoft Identity Platform.

Passo 2: Aggiungi una credenziale di identità federata

Aggiungi una credenziale di identità federata a quell'applicazione in modo che consideri attendibile l'identità gestita assegnata dall'utente del database. L'applicazione e l'identità gestita devono appartenere allo stesso tenant Microsoft Entra.

1. Nella registrazione dell'app, seleziona Certificati e segreti>Credenziali federate>Aggiungi credenziali.
2. Per lo scenario di credenziali federate, seleziona Identità gestita.
3. Seleziona l'identità gestita che hai creato nel Passo 1 della guida dello stesso tenant.
4. Verifica che l'Emittente automatico identifichi il tuo tenant. Per il cloud pubblico Azure, l'emittente è https://login.microsoftonline.com/<tenant-id>/v2.0.
5. Assicurati che Audience sia api://AzureADTokenExchange, il valore per il cloud pubblico Azure.
6. Inserisci un nome univoco per la credenziale e poi salvala.

L'oggetto della credenziale è l'ID oggetto (principale) dell'identità gestita, non il suo ID client. Se configuri manualmente le credenziali, copia esattamente l'ID dell'oggetto (principale), perché il soggetto distingue tra maiuscole e minuscole. Microsoft Entra ID accetta valori errati di emittente, soggetto o destinatario quando salvi la credenziale, ma lo scambio di token fallisce successivamente.

Per maggiori informazioni, vedi Configura un'applicazione per fidarsi di un'identità gestita.

Passo 3: Acconsentire all'applicazione e concedere l'accesso allo storage

Nel tenant che detiene l'account di archiviazione:

1. Un amministratore acconsente all'applicazione multi-tenant, che crea un'entità servizio in quel tenant.
2. Assegna il ruolo Storage Blob Data Reader a quel principale di servizio sull'account storage. Segui il Passo 3: Concedi all'identità l'accesso allo storage, ma per Assegna accesso a, seleziona Utente, gruppo o principale di servizio, e poi seleziona il principale di servizio dell'applicazione.

Passo 4: Imposta l'ID client federato nel database

Nel tenant che contiene il database, assegnare l'identità gestita assegnata dall'utente al database e impostare l'ID Application (client) dal Passo 1 come Federated Client ID:

1. Vai al tuo database SQL.
2. In Sicurezza selezionare Identità.
3. Sotto User-Assigned Managed Identity, verifica che l'identità del Passaggio 1 della guida dello stesso tenant sia elencata. Se non lo è, seleziona Aggiungi, seleziona l'identità e poi Aggiungi.
4. Sotto identità client federata, seleziona l'applicazione e poi seleziona Salva.

Per impostarlo con la interfaccia della riga di comando di Azure:

az sql db update \
    --resource-group <resource-group> \
    --server <server-name> \
    --name <database-name> \
    --assign-identity \
    --user-assigned-identity-id <identity-resource-id> \
    --federated-client-id <application-client-id>

Per impostarlo con PowerShell:

Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId> -FederatedClientId <ApplicationClientId>

Passo 5: Crea la credenziale e la query

CREATE DATABASE SCOPED CREDENTIAL MyCrossTenantCred
WITH IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY';

CREATE EXTERNAL DATA SOURCE PartnerStorage
WITH (
    LOCATION = 'adls://<container>@<storage-account>.dfs.core.windows.net',
    CREDENTIAL = MyCrossTenantCred
);

Poi crea una tabella esterna o esegui OPENROWSET su PartnerStorage esattamente come nel Passo 6: interroga i dati.

Confronta le identità a livello di server e a livello di database

Entrambi i tipi di credenziali possono coesistere sullo stesso server logico e all'interno dei suoi database. Scegli la credenziale che meglio si adatta alle tue esigenze di sicurezza.

Geo-replicazione e failover

Assegni l'identità a un database, così ogni replica ha la propria identità assegnata. Configura la geo-secondaria allo stesso modo della primaria prima di fare il failover:

• Assegnare al database secondario la stessa identità gestita assegnata dall’utente usata dal database primario.
• Concedi a quell'identità lo stesso accesso allo storage descritto nel Passo 3: Concedere all'identità l'accesso allo storage.
• Per l'accesso tra tenant, imposta la stessa identità client federata sul database secondario.

Quando configuri entrambe le repliche in questo modo, le query che utilizzano una credenziale con ambito di database continuano a funzionare anche dopo un failover. Il requisito corrisponde a chiavi gestite dal cliente a livello di database, che richiedono anch'esse l'identità presente su ogni replica.

La stessa configurazione si applica sia alla geo-replicazione attiva che ai gruppi di failover.

Limitazioni

• Solo database SQL di Azure Istanza gestita di SQL di Azure, SQL Server e Azure Synapse Analytics non supportano queste identità di credenziali.
• Solo autenticazione in uscita. Questa funzione non cambia il modo in cui utenti e applicazioni si autenticano al database.
• Non supportato nel master database. Crea la credenziale in un database degli utenti.
• Solo identità gestite assegnate dall'utente. Un'identità gestita assegnata dal sistema è limitata all'ambito del server logico, quindi non può agire come identità a livello di database.
• Un'identità gestita assegnata dall'utente per ogni database.
• Questa anteprima copre solo la virtualizzazione dei dati: CREATE EXTERNAL TABLE e OPENROWSET con DATA_SOURCE. Altre funzionalità in uscita, come sp_invoke_external_rest_endpoint, non rientrano nell'ambito.

Troubleshoot

Creare una credenziale con ambito di database non conferma che l'identità del database possa ottenere un token o accedere allo storage. Gli errori appaiono più avanti, quando crei una fonte dati esterna o esegui una query che utilizza la credenziale.

L'identità del database non è configurata (errore 15858)

Puoi creare una credenziale IDENTITY = 'DATABASE MANAGED IDENTITY' prima di assegnare un'identità gestita assegnata dall'utente al database. Se una query utilizza poi la credenziale e il database non dispone di un'identità con cui ottenere un token, la query ha esito negativo con l'errore 15858:

Cannot obtain a Microsoft Entra ID token to access storage. Error message: 'Azure SQL Server or Database identity is not configured. Please follow the steps in "Assign a Microsoft Entra managed identity to your Azure SQL" (https://aka.ms/SQLDBMSI)'.

Assegnare un'identità gestita assegnata dall'utente al database, come descritto nel Passaggio 2, dargli accesso all'account di archiviazione e poi riprovare la query. Assegnare un'identità solo al server logico non configura un'identità a livello di database. Se l'assegnazione del database è configurata e l'errore persiste, contatta il supporto tecnico Microsoft per indagare sul provisioning dell'identità del database.

Non si può trovare o fare riferimento alla credenziale (errore 46516)

Quando crei una fonte di dati esterna, database SQL di Azure verifica che la credenziale esista nel database corrente e che tu abbia l'autorizzazione a farvi riferimento. Se uno dei due controlli fallisce, ricevi l'errore 46516:

The specified credential cannot be found or the user does not have permission to perform this action.

Crea la credenziale nel database che contiene la fonte dei dati esterna, controlla il nome della credenziale e assicurati di avere il permesso di fare riferimento alla credenziale.

Fallimento dell'acquisizione del token (errore 15858)

Quando il database non riesce a ottenere un token Microsoft Entra e il fornitore di token restituisce una motivazione, l'errore 15858 include quella motivazione:

Cannot obtain a Microsoft Entra ID token to access storage. Error message: '<details>'.

Usa il messaggio di errore annidato per scoprire perché la richiesta del token è fallita. Per l'accesso cross-tenant, verifica l'applicazione, il consenso amministrativo nel tenant di archiviazione e la credenziale di identità federata, come descritto in Configura un'applicazione per considerare attendibile un'identità gestita.

Per leggere i dati esterni, l'identità ha anche bisogno di un ruolo dei dati di archiviazione. Per l'accesso allo stesso tenant, concedere Storage Blob Data Reader sul container o sull'account storage all'identità gestita assegnata dall'utente del database. Per l'accesso cross-tenat, concedelo all'entità servizio dell'applicazione nel tenant di archiviazione. Per altre informazioni, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

Il file non esiste o non può essere consultato (errore 4860)

Quando manca un file o non può essere letto, ricevi l'errore 4860:

Cannot bulk load. The file "<path>" does not exist or you don't have file access rights. See https://go.microsoft.com/fwlink/?LinkId=2374938 for more information.

Controlla che il file esista nella posizione configurata. Poi verifica che l'identità utilizzata dalla richiesta possa accedervi, tramite un ruolo di storage data o, per ADLS Gen2, liste di controllo accessi (ACL) sul percorso.

L'accesso alla rete è bloccato (errori 42121 e 16539)

Quando il server logico è associato a un perimetro di sicurezza di rete che non consente il traffico in uscita verso l'account di archiviazione, si ottiene l'errore 42121:

The operation could not be completed because attempts to connect were denied by the configured Network Security Perimeter.

Aggiungi una regola di accesso in uscita per il nome host dell'account di archiviazione al profilo perimetrale, oppure associa l'account di archiviazione allo stesso perimetro. Per ulteriori informazioni, consulta il perimetro di sicurezza di rete per database SQL di Azure.

Quando la rete in uscita è limitata sul server logico e l'account di archiviazione non è nelle regole del firewall in uscita del server, si riceve l'errore 16539:

Operation failed since the external data source '<external-data-source>' has underlying storage account that is not in the list of Outbound Firewall Rules on the server. Please add this storage account to the list of Outbound Firewall Rules on your server and retry the operation.

Aggiungi una regola firewall in uscita per il nome esatto dell'host di archiviazione nella posizione della sorgente dati esterna. Per ulteriori informazioni, consulta Regole firewall in uscita per database SQL di Azure e Azure Synapse Analytics.

La configurazione cross-tenant manca o è errata (errori 16561 e 16562)

Una query cross-tenant può fallire con uno di questi errori, oppure con l'errore 4860:

External table '<table-name>' is not accessible because content of directory cannot be listed.

External table '<table-name>' is not accessible because location does not exist or it is used by another process.

Questi errori significano che la query non è riuscita a raggiungere i file. L'identità potrebbe non avere il ruolo di archiviazione richiesto, l'accesso alla rete potrebbe essere bloccato, la posizione di archiviazione potrebbe non risolversi, oppure il token potrebbe essere per il tenant sbagliato. Per correggerlo:

• Concedi il ruolo dati di archiviazione appropriato.
• Consentire l'accesso di rete all'account di archiviazione.
• Includi il contenitore nella posizione della fonte dati esterna.
• Usa DATABASE FEDERATED CLIENT IDENTITY, e imposta l'ID del Client Federato nel database, come descritto nel Passo 4.
• Conferma che l'oggetto della credenziale di identità federata corrisponda esattamente all'ID Oggetto (principale) dell'identità gestita.

Le query falliscono dopo un failover

Se le query falliscono con errori di token o autorizzazione dopo un failover, il nuovo primary potrebbe non avere la stessa identità gestita assegnata dall'utente usata dal primary originale. Oppure quell'identità potrebbe non avere un ruolo assegnato sull'account storage. Assegnare la stessa identità a entrambe le repliche e concedere loro accesso allo storage, come descritto in Geo-replicazione e failover.

Domande frequenti

Le credenziali a livello di server e a livello di database possono coesistere sullo stesso server?

Sì, sullo stesso server logico e nello stesso database. Il valore di IDENTITY di ogni credenziale decide quale identità utilizza una query: MANAGED IDENTITY utilizza l'identità del server e DATABASE MANAGED IDENTITY quella del database.

Posso usare un'identità gestita assegnata al sistema?

No. Un'identità gestita assegnata dal sistema appartiene al server logico, quindi non puoi limitarne l'ambito a un solo database. Usa un'identità gestita assegnata dall'utente.

Quali livelli di servizio e regioni supportano questa anteprima?

Tutti i livelli di servizio database SQL di Azure, in tutte le regioni Azure.

Ho bisogno di una chiave master del database?

No. Né DATABASE MANAGED IDENTITY né DATABASE FEDERATED CLIENT IDENTITY accettano un segreto, quindi non è richiesta la chiave maestra.

Questa funzione funziona con sp_invoke_external_rest_endpoint?

Non disponibile in questa anteprima. L'anteprima riguarda la virtualizzazione dei dati.

Contenuti correlati

• Virtualizzazione dei dati con database SQL di Azure
• Identità gestite in Microsoft Entra per Azure SQL
• Chiavi a livello di database gestite dal cliente
• Chiavi gestite dal cliente tra tenant
• CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL) - Crea credenziali con ambito di database (Transact-SQL)
• CREARE TABELLA ESTERNA (Transact-SQL)