Toegang tot Azure-bestandsshares met behulp van Microsoft Entra ID met Azure Files OAuth via REST

2025-04-03

Met Azure Files OAuth via REST kunt u voor gebruikers en toepassingen lees- en schrijftoegang op beheerdersniveau krijgen tot Azure-bestandsshares door het OAuth-verificatieprotocol te gebruiken, waarbij Microsoft Entra ID wordt ingezet voor toegang op basis van de REST API. Gebruikers, groepen, services van derden, zoals Azure Portal en services van derden en toepassingen die gebruikmaken van REST-interfaces, kunnen nu OAuth-verificatie en -autorisatie gebruiken met een Microsoft Entra-account voor toegang tot gegevens in Azure-bestandsshares. PowerShell-cmdlets en Azure CLI-opdrachten die REST API's aanroepen, kunnen ook OAuth gebruiken voor toegang tot Azure-bestandsshares. U moet de REST API aanroepen met behulp van een expliciete header om uw intentie aan te geven voor het gebruik van de extra bevoegdheid. Dit geldt ook voor toegang tot Azure PowerShell en Azure CLI.

Belangrijk

In dit artikel wordt uitgelegd hoe u toegang op beheerdersniveau tot Azure-bestandsshares kunt inschakelen voor specifieke gebruiksscenario's van klanten. Als u op zoek bent naar een meer algemeen artikel over verificatie op basis van identiteiten voor eindgebruikers, raadpleegt u Overzicht van verificatie op basis van identiteiten van Azure Files voor SMB-toegang.

Van toepassing op:

Beheermodel	Betaalmodel	Medianiveau	Redundantie
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	Lokaal (LRS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	Zone (ZRS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	Aardrijkskunde (GRS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	GeoZone (GZRS)
Microsoft.Opslag	Geconfigureerd v1	SSD (van hoge kwaliteit)	Lokaal (LRS)
Microsoft.Opslag	Geconfigureerd v1	SSD (van hoge kwaliteit)	Zone (ZRS)
Microsoft.Opslag	Betaal naar verbruik	HDD (standaard)	Lokaal (LRS)
Microsoft.Opslag	Betaal naar verbruik	HDD (standaard)	Zone (ZRS)
Microsoft.Opslag	Betaal naar verbruik	HDD (standaard)	Aardrijkskunde (GRS)
Microsoft.Opslag	Betaal naar verbruik	HDD (standaard)	GeoZone (GZRS)

Beperkingen

Het autoriseren van bestandsgegevensbewerkingen met Microsoft Entra-id wordt alleen ondersteund voor REST API-versies 2022-11-02 en hoger.

Azure Files OAuth via REST-ondersteuning voor AZURE Files REST-gegevensvlak-API's die FileService- en FileShare-resources beheren, is beschikbaar met REST API-versies 2024-11-04 en hoger.

Zie Versiebeheer voor Azure Storage.

Gebruiksvoorbeelden van klanten

OAuth-verificatie en -autorisatie met Azure Files via de REST API-interface kunnen in de volgende scenario's profiteren van klanten.

Integratie van toepassingen en services

Met OAuth-verificatie en -autorisatie kunnen ontwikkelaars toepassingen bouwen die toegang hebben tot Azure Storage REST API's met behulp van gebruikers- of toepassingsidentiteiten van Microsoft Entra ID.

Klanten en partners kunnen ook eigen services en services van derden inschakelen om de benodigde toegang veilig en transparant te configureren op het opslagaccount van een klant.

DevOps-hulpprogramma's zoals Azure Portal, PowerShell en CLI, AzCopy en Storage Explorer kunnen gegevens beheren met behulp van de identiteit van de gebruiker, waardoor opslagtoegangssleutels niet meer hoeven te worden beheerd of gedistribueerd.

Beheerde identiteiten

Klanten met toepassingen en beheerde identiteiten waarvoor toegang tot bestandssharegegevens is vereist voor back-up-, herstel- of controledoeleinden, kunnen profiteren van OAuth-verificatie en -autorisatie. Het afdwingen van machtigingen op bestand- en mapniveau voor elke identiteit voegt complexiteit toe en is mogelijk niet compatibel met bepaalde werkbelastingen. Klanten willen bijvoorbeeld een back-upoplossingsservice autoriseren voor toegang tot Azure-bestandsshares met alleen-lezentoegang tot alle bestanden, zonder rekening te houden met bestandsspecifieke machtigingen.

Vervanging van opslagaccountsleutel

Microsoft Entra ID biedt superieure beveiliging en gebruiksgemak ten opzichte van toegang tot gedeelde sleutels. U kunt toegang tot de sleutel van het opslagaccount vervangen door OAuth-verificatie en -autorisatie voor toegang tot Azure-bestandsshares met lees-alles/schrijfrechten. Deze aanpak biedt ook betere controle en tracering van specifieke gebruikerstoegang.

Bevoegde toegangsrechten en machtigingen voor gegevensbewerkingen

Als u de Azure Files OAuth wilt gebruiken via REST, zijn er aanvullende machtigingen die moeten worden opgenomen in de RBAC-rol die is toegewezen aan de gebruiker, groep of service-principal. Er worden twee nieuwe gegevensacties geïntroduceerd als onderdeel van deze functie:

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

Gebruikers, groepen of service-principals die de REST API aanroepen met OAuth, moeten de readFileBackupSemantics of writeFileBackupSemantics actie hebben toegewezen aan de rol die toegang tot gegevens toestaat. Dit is een vereiste voor het gebruik van deze functie. Zie Machtigingen voor het aanroepen van gegevensbewerkingen voor meer informatie over de machtigingen die nodig zijn om specifieke bestandsservicebewerkingen aan te roepen.

Deze functie biedt twee nieuwe ingebouwde rollen die deze nieuwe acties bevatten.

Rol	Acties op gegevens
Lezer met bevoegdheid voor opslagbestandsgegevens	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Inzender met bevoegdheid voor opslagbestandsgegevens	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/fileShares/files/write` `Microsoft.Storage/storageAccounts/fileServices/fileShares/files/delete` `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` `Microsoft.Storage/storageAccounts/fileServices/fileshares/files/modifypermissions/action`

Deze nieuwe rollen zijn vergelijkbaar met de bestaande ingebouwde rollen SMB-sharelezer voor opslagbestandsgegevens en verhoogde SMB-share-bijdrager voor opslagbestandsgegevens, maar er zijn enkele verschillen.

De nieuwe rollen bevatten de aanvullende gegevensacties die vereist zijn voor OAuth-toegang.
Wanneer de gebruiker, groep of service-principal waaraan de rollen Storage File Data Privileged Reader of Storage File Data Privileged Contributor zijn toegewezen, de FilesREST-gegevens-API oproept via OAuth, zullen de gebruiker, de groep, of de service-principal:
- Lezer met bevoegdheden voor opslagbestandsgegevens: Volledige leestoegang voor alle gegevens in de shares voor alle geconfigureerde opslagaccounts, ongeacht de NTFS-machtigingen op bestand/mapniveau die zijn ingesteld.
- Inzender met bevoegdheden voor opslagbestandsgegevens: Volledige lees-, schrijf-, wijzigings-ACL's, verwijder toegang tot alle gegevens in de shares voor alle geconfigureerde opslagaccounts, ongeacht de NTFS-machtigingen op bestand/mapniveau die zijn ingesteld.
Met deze speciale machtigingen en rollen zal het systeem machtigingen op bestand-/mapniveau overslaan en toegang tot gegevens van gedeelde bestanden toestaan.

Met de nieuwe rollen en gegevensacties biedt deze functie bevoegdheden voor het opslagaccount die alle machtigingen voor bestanden en mappen onder alle bestandsshares in het opslagaccount vervangen. De nieuwe rollen bevatten echter alleen machtigingen voor toegang tot gegevensservices. Ze bevatten geen machtigingen voor toegang tot het beheer van bestandsdelingsdiensten (acties op bestandsdeling). Als u deze functie wilt gebruiken, moet u beschikken over machtigingen voor toegang:

het opslagaccount
beheerservices voor bestandsshares
gegevensservices (de gegevens in de bestandsshare)

Er zijn veel ingebouwde rollen die toegang bieden tot beheerservices. U kunt ook aangepaste rollen maken met de juiste machtigingen. Zie Azure RBAC voor meer informatie over op rollen gebaseerd toegangsbeheer. Zie Roldefinities begrijpen voor meer informatie over hoe ingebouwde rollen worden gedefinieerd.

Houd er rekening mee dat voor het resourcetype bestandsshare het bijbehorende RBAC-bereik shares in het besturingsvlak (beheerbewerkingen) wordt gebruikt, maar fileshares in het gegevensvlak (gegevensbewerkingen). Als u probeert een resource-id voor bestandsshares te gebruiken die shares bevat binnen de RBAC-bereik of tekenreeksen voor gegevensacties, zal het niet werken. U moet fileshares gebruiken binnen het bereik van RBAC-toewijzingen, bijvoorbeeld:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>/fileServices/default/fileshares/<share-name>

Belangrijk

Alle wildcard-gebruikssituaties die zijn gedefinieerd voor het pad Microsoft.Storage/storageAccounts/fileServices/* of hoger niveau, nemen automatisch de aanvullende toegang en machtigingen over die via deze nieuwe gegevensactie worden verleend. Om onbedoelde of overprivilegieerde toegang tot Azure Files te voorkomen, hebben we aanvullende controles geïmplementeerd waarvoor gebruikers en toepassingen expliciet hun intentie moeten aangeven om de extra bevoegdheid te gebruiken. Bovendien raden we klanten ten zeerste aan om hun RBAC-roltoewijzingen van gebruikers te controleren en gebruik van jokertekens te vervangen door expliciete machtigingen om het juiste beheer van gegevenstoegang te garanderen.

Toegang tot bestandsgegevens in toepassingscode autoriseren

De Azure Identity-clientbibliotheek vereenvoudigt het proces van het ophalen van een OAuth 2.0-toegangstoken voor autorisatie met Microsoft Entra-id via de Azure SDK. De nieuwste versies van de Azure Storage-clientbibliotheken voor .NET, Java, Python, JavaScript en Go kunnen worden geïntegreerd met de Azure Identity-bibliotheken voor elk van deze talen om een eenvoudig en veilig middel te bieden voor het verkrijgen van een toegangstoken voor autorisatie van aanvragen van de Azure-bestandsservice.

Een voordeel van de Azure Identity-clientbibliotheek is dat u dezelfde code kunt gebruiken om het toegangstoken te verkrijgen, ongeacht of uw toepassing wordt uitgevoerd in de ontwikkelomgeving of in Azure. De Azure Identity-clientbibliotheek retourneert een toegangstoken voor een beveiligingsprincipaal. Wanneer uw code wordt uitgevoerd in Azure, kan de beveiligingsprincipaal een beheerde identiteit zijn voor Azure-resources, een service-principal of een gebruiker of groep. In de ontwikkelomgeving biedt de clientbibliotheek een toegangstoken voor een gebruiker of een service-principal voor testdoeleinden.

Het toegangstoken dat wordt geretourneerd door de Azure Identity-clientbibliotheek, wordt ingekapseld in een tokenreferentie. Vervolgens kunt u de tokenreferentie gebruiken om een serviceclientobject op te halen voor gebruik bij het uitvoeren van geautoriseerde bewerkingen voor de Azure Files-service.

In het volgende codevoorbeeld ziet u hoe u een clientobject autoriseert met behulp van Microsoft Entra ID en bewerkingen uitvoert op map- en bestandsniveau. In dit voorbeeld wordt ervan uitgegaan dat de bestandsshare al bestaat.

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

namespace FilesOAuthSample
{
    internal class Program
    {
        static async Task Main(string[] args)
        {
            string tenantId = "";
            string appId = "";
            string appSecret = "";
            string entraEndpoint = "";
            string accountUri = "https://<storage-account-name>.file.core.windows.net/";
            string shareName = "test-share";
            string directoryName = "test-directory";
            string fileName = "test-file";  

            TokenCredential tokenCredential = new ClientSecretCredential(
                tenantId,
                appId,
                appSecret,
                new TokenCredentialOptions()
                {
                    AuthorityHost = new Uri(entraEndpoint)
                });

            // Set client options
            ShareClientOptions clientOptions = new ShareClientOptions();
            clientOptions.AllowTrailingDot = true;
            clientOptions.AllowSourceTrailingDot = true;

            // x-ms-file-intent=backup will automatically be applied to all APIs
            // where it is required in derived clients
            clientOptions.ShareTokenIntent = ShareTokenIntent.Backup;

            ShareServiceClient shareServiceClient = new ShareServiceClient(
                new Uri(accountUri),
                tokenCredential,
                clientOptions);

            ShareClient shareClient = shareServiceClient.GetShareClient(shareName);
            ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient(directoryName);
            await directoryClient.CreateAsync();

            ShareFileClient fileClient = directoryClient.GetFileClient(fileName);
            await fileClient.CreateAsync(maxSize: 1024);
            await fileClient.GetPropertiesAsync();
        }
    }
}

Toegang autoriseren met behulp van fileREST-gegevensvlak-API

U kunt ook toegang tot bestandsgegevens autoriseren met behulp van Azure Portal, Azure PowerShell of Azure CLI.

Azure Portal kan uw Microsoft Entra-account of de toegangssleutel voor het opslagaccount gebruiken om toegang te krijgen tot bestandsgegevens in een Azure-opslagaccount. Welk autorisatieschema de Azure-portal gebruikt, is afhankelijk van de Azure-rollen die aan u zijn toegewezen.

Wanneer u probeert toegang te krijgen tot bestandsgegevens, controleert Azure Portal eerst of u een Azure-rol hebt toegewezen met Microsoft.Storage/storageAccounts/listkeys/action. Als u met deze actie een rol hebt toegewezen, gebruikt Azure Portal de accountsleutel voor toegang tot bestandsgegevens via autorisatie van gedeelde sleutels. Als u met deze actie geen rol hebt toegewezen, probeert Azure Portal toegang te krijgen tot gegevens met behulp van uw Microsoft Entra-account.

Als u toegang wilt krijgen tot bestandsgegevens vanuit Azure Portal met uw Microsoft Entra-account, hebt u machtigingen nodig voor toegang tot bestandsgegevens en hebt u ook machtigingen nodig om door de resources van het opslagaccount in Azure Portal te navigeren. De ingebouwde rollen van Azure verlenen toegang tot bestandsbronnen, maar ze verlenen geen machtigingen voor opslagaccountbronnen. Daarom moet voor toegang tot de portal ook een ARM-rol (Azure Resource Manager) worden toegewezen, zoals de rol Lezer , die is afgestemd op het niveau van het opslagaccount of hoger. De rol Lezer verleent de meest beperkende machtigingen, maar elke ARM-rol die toegang verleent tot opslagaccountbeheerresources is acceptabel.

Azure Portal laat zien welk autorisatieschema wordt gebruikt wanneer u naar een container navigeert. Zie Kiezen hoe u toegang tot bestandsgegevens in Azure Portal autoriseert voor meer informatie over gegevenstoegang in de portal.

Azure biedt extensies voor PowerShell waarmee u zich kunt aanmelden en PowerShell-cmdlets kunt aanroepen met behulp van Microsoft Entra-referenties. Wanneer u zich aanmeldt bij PowerShell met Microsoft Entra-referenties, wordt er een OAuth 2.0-toegangstoken geretourneerd. PowerShell gebruikt dat token automatisch om volgende gegevensbewerkingen te autoriseren voor bestandsopslag. Voor ondersteunde bewerkingen hoeft u geen accountsleutel of SAS-token meer door te geven met de opdracht.

U kunt machtigingen toekennen aan bestanden voor een Microsoft Entra-beveiligingsprincipaal via Azure RBAC.

Ondersteunde bewerkingen

De extensies ondersteunen alleen bewerkingen op bestandsgegevens. Welke bewerkingen u kunt aanroepen, is afhankelijk van de machtigingen die zijn verleend aan de Microsoft Entra-beveiligingsprincipaal waarmee u zich hebt aangemeld bij PowerShell.

De opslagcontext met OAuth werkt alleen als deze wordt aangeroepen met de -EnableFileBackupRequestIntent parameter. Hiermee geeft u de expliciete intentie op voor het gebruik van de aanvullende machtigingen die deze functie biedt.

De opslagcontext met OAuth werkt alleen voor bewerkingen op bestanden en mappen en machtigingen ophalen/instellen voor Azure-bestandsshares. Voor alle andere bewerkingen op het opslagaccount en bestandsshares moet u de sleutel of het SAS-token van het opslagaccount gebruiken.

Vereiste voorwaarden

U hebt een Azure-resourcegroep en een opslagaccount in die resourcegroep nodig. Aan het opslagaccount moet een geschikte rol worden toegewezen waarmee expliciete machtigingen worden verleend voor het uitvoeren van gegevensbewerkingen op bestandsshares. Zorg ervoor dat u beschikt over de vereiste rollen en machtigingen voor toegang tot zowel de beheerservices als gegevensservices. Zie Machtigingen voor het aanroepen van gegevensbewerkingen voor meer informatie over de machtigingen die nodig zijn om specifieke bestandsservicebewerkingen aan te roepen.

Az.Storage-module installeren

Deze functie is beschikbaar in de nieuwste Az.Storage-module. Installeer de module met behulp van deze opdracht:

Install-Module Az.Storage -Repository PsGallery

Toegang tot bestandsgegevens autoriseren

Volg deze stappen om toegang tot bestandsgegevens te autoriseren.

Meld u aan bij uw Azure-account met behulp van de Connect-AzAccount cmdlet.
Haal de context van het opslagaccount op met behulp van de sleutel van het opslagaccount door de Get-AzStorageAccount cmdlet (beheerservice) aan te roepen. Vervang <ResourceGroupName> en <StorageAccountName> door uw eigen waarden.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Maak een bestandsshare door aan te roepen New-AzStorageShare. Omdat u de context van het opslagaccount uit stap 2 gebruikt, wordt de bestandsshare gemaakt met behulp van uw opslagaccountsleutel.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Haal de context van het opslagaccount op met behulp van OAuth voor het uitvoeren van gegevensbewerkingen op de bestandsshare (gegevensservice). Vervang door <StorageAccountName> de naam van uw opslagaccount.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Als u de context van het opslagaccount met OAuth wilt ophalen, moet u de -EnableFileBackupRequestIntent parameter expliciet doorgeven aan de New-AzStorageContext cmdlet. Als u de intentieparameter niet doorgeeft, mislukken volgende aanvragen voor bestandssharegegevensbewerkingen met behulp van de context.
Maak een testmap en bestand in de bestandsshare met behulp van New-AzStorageDirectory en Set-AzStorageFileContent cmdlets. Vergeet niet een lokaal bronbestandspad op te geven.
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
Omdat de cmdlets worden aangeroepen met behulp van de context van het opslagaccount uit stap 4, worden het bestand en de map gemaakt met behulp van Microsoft Entra-referenties.

De belangrijkste Azure CLI-opdrachten die worden verzonden als onderdeel van CLI ondersteunen Bestanden OAuth via REST-interface en u kunt ze gebruiken om bestandsgegevensbewerkingen te verifiëren en te autoriseren met behulp van Microsoft Entra-referenties.

Ondersteunde bewerkingen

De opdrachten ondersteunen alleen bewerkingen op bestandsgegevens. Welke bewerkingen u kunt aanroepen, is afhankelijk van de machtigingen die zijn verleend aan de Microsoft Entra-beveiligingsprincipaal waarmee u zich hebt aangemeld bij Azure CLI.

OAuth-verificatie en -autorisatie werken alleen als de CLI-opdracht wordt aangeroepen met de --backup-intent optie of --enable-file-backup-request-intent optie. Hiermee geeft u de expliciete intentie op voor het gebruik van de aanvullende machtigingen die deze functie biedt.

Alle opdrachten onder az storage file en az storage directory opdrachtgroepen, en az storage share list-handle en az storage share close-handle ondersteunen OAuth-verificatie en -autorisatie. Voor alle andere bewerkingen op het opslagaccount en bestandsshares moet u de sleutel of het SAS-token van het opslagaccount gebruiken.

Vereiste voorwaarden

Installatie- en voorbeeldopdrachten

Als u dit nog niet hebt gedaan, installeert u de nieuwste versie van Azure CLI.

Toegang tot bestandsgegevens autoriseren

Meld u aan bij uw Azure-account.
```
az login
```
Maak een bestandsshare door aan te roepen az storage share create cli. Omdat u de verbindingsreeks gebruikt, wordt de bestandsshare gemaakt met behulp van de sleutel van uw opslagaccount.
```
az storage share create --name testshare1 --connection-string <connection-string>
```
Maak een testmap en upload een bestand naar de bestandsshare met behulp van az storage directory create en az storage file upload cli. Vergeet niet om de --auth modus op te geven als aanmelding en de --backup-intent parameter door te geven.
```
az storage directory create --name testdir1 --account-name filesoauthsa --share-name testshare1 --auth-mode login --backup-intent
az storage file upload  --account-name filesoauthsa --share-name testshare1 --auth-mode login --backup-intent --source <source file path>
```
Omdat de CLI-opdrachten worden aangeroepen met het authenticatietype als bij inloggen (--auth modeinloggen en --backup-intent parameter), worden het bestand en de map gemaakt met Microsoft Entra-referenties.

Raadpleeg de nieuwste CLI-documentatie voor ondersteunde opdrachten voor meer informatie:

az storage file
az storage directory
az storage share list-handle
az storage share close-handle (gebruik deze opdracht om een actieve bestandsserverkoppeling te sluiten)

Zie ook

Kiezen hoe u toegang tot bestandsgegevens wilt autoriseren in het Azure Portal

Feedback

Is deze pagina nuttig?