Gebruik database-level managed identity met Azure SQL Database (preview)

Van toepassing op:Azure SQL Database

Database-level managed identity geeft een individuele database in Azure SQL Database een eigen door de gebruiker toegewezen managed identity (UAMI). Een database met een beheerde identiteit authenticeert zich bij Azure Storage als zichzelf, in plaats van als de logische server die deze host.

Zonder database-niveau identiteit deelt elke database op een logische server de beheerde identiteit van die server, zodat ze allemaal dezelfde opslag bereiken. Een database-niveau identiteit beperkt die toegang tot één database, zodat je elke database alleen de opslag kunt geven die het nodig heeft.

Je selecteert de identiteit in een database-scoped credential, hetzelfde credential dat datavirtualisatiequeries gebruiken om Parquet-, CSV- en Delta-bestanden uit Azure Blob Storage of Azure Data Lake Storage (ADLS) Gen2 te lezen. Kies tussen twee referentie-id-waarden van de aanmeldingsgegevens:

Prerequisites

• Een Azure SQL Database op een logische server. Alle serviceniveaus en alle Azure-regio's ondersteunen deze functie.
• Een door de gebruiker toegewezen beheerde identiteit in hetzelfde abonnement. Voor achtergrond, zie Managed Identities in Microsoft Entra for Azure SQL.
• Toestemming om rollen toe te wijzen aan het doelopslagaccount, zoals Eigenaar of Gebruikerstoegangsbeheerder.
• Een Azure Blob Storage- of ADLS Gen2-account met de bestanden die je wilt opvragen.

Kies voor dezelfde tenant of cross-tenant

Beide walkthroughs maken een databasescope-referentie en vragen externe gegevens op. Ze verschillen in hoe de identiteit het opslagaccount bereikt.

• Als de database en het opslagaccount in dezelfde tenant zitten, volg de stappen in Een identiteit op databaseniveau in dezelfde tenant gebruiken.
• Als het opslagaccount in een andere tenant zit, volg dan Gebruik een gefedereerde clientidentiteit tussen tenants.

Gebruik een identiteit op databaseniveau in dezelfde tenant

Stap 1: Een door de gebruiker toegewezen beheerde identiteit maken

Maak de identiteit aan en noteer zowel de Resource ID als de Object (principal) ID. Je hebt de Resource ID nodig om de identiteit aan de database toe te wijzen. Je hebt de Object (principal) ID alleen nodig voor de cross-tenant walkthrough, waar het onderwerp van de gefedereerde identiteitsreferentie wordt geïdentificeerd.

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

Voor andere methoden, zie Door de gebruiker toegewezen beheerde identiteiten beheren.

Stap 2: Wijs de identiteit toe aan de database

Wijs de UAMI toe aan de database, niet aan de logische server. Deze toewijzing gebruikt hetzelfde mechanisme als transparante gegevensversleuteling op databaseniveau (TDE) met klantbeheerde sleutels, beschreven in Klantbeheerde sleutels op databaseniveau. Voor de volledige set toewijzingsmethoden, zie Een beheerde identiteit voor een database ophalen of instellen.

Om de identiteit toe te wijzen in het Azure-portaal:

1. Ga naar je SQL-database.
2. Selecteer Identiteit onder Beveiliging.
3. Selecteer onder User-Assigned Managed Identity de optie Toevoegen.
4. Selecteer de identiteit die je hebt aangemaakt en selecteer vervolgens Toevoegen.
5. Klik op Opslaan.

Om de identiteit toe te wijzen met de Azure CLI, gebruik 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>

Om het toe te wijzen met PowerShell, gebruik Set-AzSqlDatabase:

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

De identiteit Resource ID ziet eruit als /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>. Vind het onder Eigenschappen bij de beheerde identiteit in het Azure-portaal.

Stap 3: Verleen de principal toegang tot opslag

Geef de beheerde identiteit leestoegang aan het opslagaccount:

1. Ga naar het opslagaccount.
2. Selecteer Toegangsbeheer (IAM).
3. Selecteer Toevoegen>Roltoewijzing toevoegen.
4. Selecteer de rol Storage Blob Data Reader en selecteer vervolgens Volgende.
5. Voor Toegang toewijzen aan, selecteer Beheerde identiteit.
6. Selecteer Select members, selecteer je door de gebruiker toegewezen beheerde identiteit en selecteer vervolgens Select.
7. Selecteer Beoordelen en toewijzen.

Voor fijnere toegang op ADLS Gen2, stel toegangscontrolelijsten (ACL's) in op specifieke mappen in plaats van een rol op accountniveau toe te wijzen. Voor meer informatie, zie Access control lists in Azure Data Lake Storage.

Stap 4: Maak de referentie met databereik】【。

Maak verbinding met je gebruikersdatabase, niet master, en maak het credential aan:

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

Deze referentie heeft geen geheim en geen databasesleutel nodig. De database-engine bepaalt tijdens het uitvoeren van de query de identiteit die aan de database is toegewezen.

Het serverniveau-equivalent gebruikt een andere identiteitswaarde. Vergelijken:

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

Voor de volledige syntaxis, zie CREATE DATABASE SCOPED CREDENTIAL.

Stap 5: Maak de externe databron aan

Maak een externe databron aan die naar je container verwijst en voeg de credential toe. Gebruik het voorvoegsel dat overeenkomt met je opslagtype:

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

Stap 6: Zoek de gegevens op

Doorzoek de bestanden ad hoc met OPENROWSET:

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

Of definieer een externe tabel voor herhaalde zoekopdrachten:

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;

Gebruik een gefedereerde clientidentiteit tenantoverstijgend

Gebruik dit pad wanneer je database in de ene tenant zit en het opslagaccount in een andere. Een multitenant-applicatieregistratie draagt het vertrouwen tussen hen: de UAMI van de database is het onderwerp van een federatieve identiteitsreferentie op die applicatie, en de opslagtenant verleent de serviceprincipal van de applicatie toegang tot de gegevens.

Het patroon komt overeen met cross-tenant klantbeheerde sleutels voor transparante data-encryptie, dus de opzet komt bekend uit als je die functie al gebruikt.

Stap 1: Registreer een multitenant-applicatie

Registreer in de tenant die de database beheert een multitenant-applicatie in Microsoft Entra ID en noteer de applicatie (client) ID.

Zie Een toepassing registreren bij het Microsoft-identiteitsplatform voor meer informatie.

Stap 2: Voeg een referentie voor federatieve identiteit toe

Voeg een gefedereerde identiteitsreferentie toe aan die applicatie zodat deze de door gebruikers toegewezen beheerde identiteit van de database vertrouwt. De applicatie en de beheerde identiteit moeten bij dezelfde Microsoft Entra-tenant horen.

1. Selecteer in de app-registratie Certificaten & geheimen>Gefedereerde referenties>Inloggegevens toevoegen.
2. Voor het scenario voor gefedereerde referenties, selecteer Managed Identity.
3. Selecteer de beheerde identiteit die je hebt aangemaakt in stap 1 van de walkthrough voor dezelfde tenant.
4. Controleer of de automatisch ingevulde Issuer je tenant identificeert. Voor de publieke Azure-cloud is https://login.microsoftonline.com/<tenant-id>/v2.0de uitgever .
5. Zorg ervoor dat Audienceapi://AzureADTokenExchange is, de waarde voor de openbare Azure-cloud.
6. Voer een unieke naam in voor het credential en sla het vervolgens op.

Het subject van de referentie is de Object (principal) ID van de beheerde identiteit, niet de client-ID. Als je het credential handmatig configureert, kopieer dan de Object (principal) ID exakt, omdat het subject hoofdlettergevoelig is. Microsoft Entra ID accepteert onjuiste waarden van de issuer, subject of audience wanneer je de referentie opslaat, maar de tokenuitwisseling faalt later.

Voor meer informatie, zie Configureer een applicatie om een beheerde identiteit te vertrouwen.

Stap 3: Geef toestemming voor de app en verleen opslagtoegang

In de tenant die het opslagaccount beheert:

1. Een beheerder geeft toestemming voor de multitenant-applicatie, die een serviceprincipal in die tenant aanmaakt.
2. Wijs de rol Storage Blob Data Reader toe aan die serviceprincipal op het opslagaccount. Volg stap 3: Verleen de identiteit toegang tot opslag, maar selecteer bij Toegang toewijzen aanGebruiker, groep of service-principal en selecteer vervolgens de service-principal van de toepassing.

Stap 4: Stel de gefedereerde client-ID in voor de database

Wijs in de tenant die de database beheert de door de gebruiker toegewezen beheerde identiteit toe aan de database, en stel de applicatie (client) ID uit stap 1 in als de Federated Client ID:

1. Ga naar je SQL-database.
2. Selecteer Identiteit onder Beveiliging.
3. Controleer onder User-Assigned Managed Identity of de identiteit uit stap 1 van de doorgang voor dezelfde huurder vermeld staat. Als dat niet zo is, selecteer dan Toevoegen, selecteer de identiteit en selecteer dan Toevoegen.
4. Selecteer onder Federated client identity de applicatie en selecteer vervolgens Opslaan.

Om het in te stellen met de Azure CLI:

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>

Om het in te stellen met PowerShell:

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

Stap 5: Maak de referentie aan en voer een query uit

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

Maak vervolgens een externe tabel aan of voer OPENROWSET uit op PartnerStorage precies zoals in Stap 6: Zoek de data op.

Vergelijk identiteiten op server- en databaseniveau

Beide soorten inloggegevens kunnen naast elkaar bestaan op dezelfde logische server en binnen de bijbehorende databases. Kies het inloggegeven dat het beste aansluit bij uw beveiligingsbehoeften.

Geo-replicatie en failover

Je wijst de identiteit toe aan een database, zodat elke replica zijn eigen toewijzing krijgt. Configureer de geo-secondary op dezelfde manier als de primaire voordat je failovert:

• Wijs dezelfde door de gebruiker toegewezen beheerde identiteit toe die de primaire gebruikt aan de secundaire database.
• Verleen die identiteit dezelfde toegang tot opslag als beschreven in Stap 3: Verleen de identiteit toegang tot opslag.
• Voor cross-tenant toegang stel je dezelfde Federated client identiteit in op de secundaire database.

Wanneer je beide replica's op deze manier configureert, blijven queries die een database-scope credential gebruiken werken na een failover. De eis komt overeen met database-niveau klantbeheerde sleutels, die ook vereisen dat de identiteit op elke replica is geconfigureerd.

Dezelfde configuratie geldt voor zowel actieve geo-replicatie als failover-groepen.

Limitations

• Alleen Azure SQL Database. Azure SQL Managed Instance, SQL Server en Azure Synapse Analytics ondersteunen deze credential-identiteiten niet.
• Alleen uitgaande authenticatie. Deze functie verandert niet hoe gebruikers en applicaties zich authenticeren bij de database.
• Niet ondersteund in de master database. Maak de inloggegevens aan in een gebruikersdatabase.
• Alleen door gebruikers toegewezen beheerde identiteiten. Een door het systeem toegewezen beheerde identiteit is beperkt tot de logische server, dus kan niet als database-niveau identiteit fungeren.
• Eén door de gebruiker toegewezen beheerde identiteit per database.
• Deze preview dekt alleen datavirtualisatie: CREATE EXTERNAL TABLE en OPENROWSET met DATA_SOURCE. Andere uitgaande functies, zoals sp_invoke_external_rest_endpoint, vallen niet binnen de scope.

Troubleshoot

Het aanmaken van een database-scoped credential bevestigt niet dat de database-identiteit een token kan krijgen of toegang kan krijgen tot opslag. Fouten verschijnen later, wanneer je een externe databron aanmaakt of een query uitvoert die de inloggegevens gebruikt.

Database-identiteit is niet geconfigureerd (fout 15858)

Je kunt een credential aanmaken IDENTITY = 'DATABASE MANAGED IDENTITY' voordat je een door de gebruiker toegewezen beheerde identiteit aan de database toewijst. Als een query vervolgens het credential gebruikt en de database geen identiteit heeft om er een token mee op te halen, faalt de query met fout 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)'.

Wijs een door de gebruiker toegewezen beheerde identiteit toe aan de database, zoals beschreven in Stap 2, geef deze toegang tot het opslagaccount en probeer vervolgens de query opnieuw. Het toewijzen van een identiteit alleen aan de logische server configureert geen database-niveau identiteit. Als de databasetoewijzing aanwezig is en de fout blijft bestaan, neem dan contact op met Microsoft Ondersteuning om database-identiteitsprovisioning te onderzoeken.

Credential kan niet worden gevonden of waarnaar niet worden verwezen (fout 46516)

Wanneer je een externe databron aanmaakt, controleert Azure SQL Database of de credential in de huidige database bestaat en dat je toestemming hebt om ernaar te verwijzen. Als een van de controles faalt, krijg je foutmelding 46516:

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

Maak de referentie aan in de database die de externe databron bevat, controleer de naam van de referentie en zorg dat je toestemming hebt om naar de referentie te verwijzen.

Tokenverwerving mislukt (fout 15858)

Wanneer de database geen Microsoft Entra-token kan krijgen en de tokenprovider een reden teruggeeft, bevat fout 15858 die reden:

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

Gebruik het geneste foutbericht om te achterhalen waarom het tokenverzoek is mislukt. Voor cross-tenant toegang controleer de applicatie, de admin-toestemming in de opslagtenant en het gefedereerde identiteitscredential, zoals beschreven in Configureer een applicatie om een beheerde identiteit te vertrouwen.

Om externe data te lezen, heeft de identiteit ook een gegevensrol voor opslag nodig. Voor toegang voor dezelfde tenant kunt u Storage Blob Data Reader op de container of opslagaccount toewijzen aan de door de gebruiker toegewezen beheerde identiteit van de database. Voor cross-tenanttoegang, wijs deze toe aan de service-principal van de applicatie in de opslagtenant. Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie.

Bestand bestaat niet of is niet toegankelijk (fout 4860)

Wanneer een bestand ontbreekt of niet gelezen kan worden, krijg je foutmelding 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.

Controleer of het bestand op de geconfigureerde locatie aanwezig is. Controleer vervolgens of de identiteit die het verzoek gebruikt er toegang toe heeft, via een opslaggegevensrol of, voor ADLS Gen2, toegangscontrolelijsten (ACL's) op het pad.

Netwerktoegang is geblokkeerd (fouten 42121 en 16539)

Wanneer de logische server gekoppeld is aan een netwerkbeveiligingsperimeter die geen uitgaand verkeer naar het opslagaccount toestaat, krijg je foutmelding 42121:

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

Voeg een uitgaande toegangsregel toe voor de hostnaam van het opslagaccount aan het perimeterprofiel, of koppel het storageaccount aan dezelfde perimeter. Voor meer informatie, zie Network security perimeter voor Azure SQL Database.

Wanneer uitgaande netwerken beperkt zijn op de logische server en het opslagaccount niet in de uitgaande firewallregels van de server staat, krijg je foutmelding 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.

Voeg een uitgaande firewallregel toe voor de exacte opslaghostnaam in de locatie van de externe databron. Voor meer informatie, zie Outbound firewall rules for Azure SQL Database en Azure Synapse Analytics.

Cross-tenant configuratie ontbreekt of is onjuist (fouten 16561 en 16562)

Een cross-tenant query kan falen met een van deze fouten, of met fout 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.

Deze fouten betekenen dat de query de bestanden niet kon bereiken. De identiteit heeft mogelijk niet de vereiste opslagrol, netwerktoegang kan geblokkeerd zijn, de opslaglocatie kan mogelijk niet worden gevonden, of het token kan voor de verkeerde tenant zijn. U kunt dit probleem als volgt oplossen:

• Ken de juiste rol voor opslaggegevens toe.
• Sta netwerktoegang toe tot het opslagaccount.
• Neem de container op in de locatie van de externe gegevensbron.
• Gebruik DATABASE FEDERATED CLIENT IDENTITY, en stel de Federated Client ID in voor de database, zoals beschreven in Stap 4.
• Bevestig dat het onderwerp van de referentie voor federatieve identiteit exact overeenkomt met de Object (principal) ID van de beheerde identiteit.

Queries falen na een failover

Als queries falen met token- of autorisatiefouten na een failover, kan het zijn dat de nieuwe primaire niet dezelfde door de gebruiker toegewezen beheerde identiteit heeft als de oorspronkelijke primaire identiteit. Of die identiteit heeft misschien geen roltoewijzing op het opslagaccount. Wijs dezelfde identiteit toe aan beide replica's en verleen deze opslagtoegang, zoals beschreven in Geo-replicatie en failover.

Veelgestelde vragen

Kunnen server- en database-niveau inloggegevens naast elkaar bestaan op dezelfde server?

Ja, op dezelfde logische server en in dezelfde database. De waarde van elk credential IDENTITY bepaalt welke identiteit een query gebruikt: MANAGED IDENTITY gebruikt de identiteit van de server en DATABASE MANAGED IDENTITY gebruikt de identiteit van de database.

Kan ik een door het systeem toegewezen beheerde identiteit gebruiken?

No. Een door het systeem toegewezen beheerde identiteit behoort tot de logische server, dus je kunt deze niet op één database afgrenzen. Gebruik een door de gebruiker toegewezen beheerde identiteit.

Welke serviceniveaus en regio's ondersteunen deze preview?

Alle Azure SQL Database service-niveaus, in alle Azure-regio's.

Heb ik een database-hoofdsleutel nodig?

No. Noch DATABASE MANAGED IDENTITY noch DATABASE FEDERATED CLIENT IDENTITY nemen een geheim, dus er is geen hoofdsleutel nodig.

Werkt deze functie met sp_invoke_external_rest_endpoint?

Niet in deze preview. De preview behandelt datavirtualisatie.

Verwante onderwerpen

• Datavirtualisering met Azure SQL Database
• beheerde identiteiten in Microsoft Entra voor Azure SQL
• klantbeheerde sleutels op databaseniveau
• Cross-tenant klantbeheerde sleutels
• nl-NL: CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
• CREËER EXTERNE TABEL (Transact-SQL)