Zugreifen auf Azure-Dateifreigaben mithilfe von Microsoft Entra ID mit Azure Files OAuth über REST

Artikel
10/24/2023

Azure Files OAuth über REST ermöglicht Lese- und Schreibzugriff auf Azure-Dateifreigaben auf Administratorebene für Benutzer und Anwendungen über das OAuth-Authentifizierungsprotokoll. Dabei wird Microsoft Entra ID für den REST-API-basierten Zugriff verwendet. Benutzer, Gruppen, Dienste von Erstanbietern wie das Azure-Portal sowie Dienste und Anwendungen von Drittanbietern, die REST-Schnittstellen verwenden, können jetzt die OAuth-Authentifizierung und -Autorisierung mit einem Microsoft Entra-Konto verwenden, um auf Daten in Azure-Dateifreigaben zuzugreifen. PowerShell-Cmdlets und Azure CLI-Befehle, die REST-APIs aufrufen, können ebenfalls OAuth für den Zugriff auf Azure-Dateifreigaben verwenden.

Wichtig

Sie müssen die REST-API mit einer expliziten Kopfzeile aufrufen, um Ihre Absicht anzugeben, das zusätzliche Privileg zu verwenden. Dies gilt auch für den Azure PowerShell- und Azure CLI-Zugriff.

Einschränkungen

Azure Files OAuth über REST unterstützt nur die FileREST-Daten-APIs, die Vorgänge bei Dateien und Verzeichnissen unterstützen. OAuth wird auf FilesREST-Datenebenen-APIs, die FileService- und FileShare-Ressourcen verwalten, nicht unterstützt. Diese Verwaltungs-APIs werden mit dem Speicherkontoschlüssel oder dem SAS-Token aufgerufen und sind aus Legacy-Gründen über die Datenebene zugänglich. Es wird empfohlen, die APIs der Steuerungsebene (den Speicherressourcenanbieter – Microsoft.Storage) zu verwenden, die OAuth für alle Verwaltungsaktivitäten im Zusammenhang mit FileService- und FileShare-Ressourcen unterstützen.

Das Autorisieren von Dateidatenvorgängen mit Microsoft Entra ID wird nur für die REST-API-Versionen 2022-11-02 und höher unterstützt. Siehe Versionsverwaltung für Azure Storage-Dienste.

Kundenanwendungsfällen

Die OAuth-Authentifizierung und -Autorisierung mit Azure Files über die REST-API-Schnittstelle kann Kunden in den folgenden Szenarien zugute kommen.

Anwendungsentwicklung und Dienstintegration

Die OAuth-Authentifizierung und -Autorisierung ermöglicht es Entwicklern, Anwendungen zu erstellen, die auf Azure Storage REST APIs zugreifen und dabei Benutzer- oder Anwendungsidentitäten aus Microsoft Entra ID verwenden.

Kunden und Partner können auch Dienste von Erstanbietern und Drittanbietern aktivieren, um den erforderlichen Zugriff auf ein Kunden-Speicherkonto sicher und transparent zu konfigurieren.

DevOps-Tools wie Azure-Portal, PowerShell und CLI, AzCopy und Storage-Explorer können Daten mithilfe der Identität des Benutzers verwalten, sodass Speicherzugriffsschlüssel nicht mehr verwaltet oder verteilt werden müssen.

Verwaltete Identitäten

Kunden mit Anwendungen und verwalteten Identitäten, die zu Sicherungs-, Wiederherstellungs- oder Prüfzwecken Zugriff auf Dateifreigabedaten benötigen, können von der OAuth-Authentifizierung und -Autorisierung profitieren. Die Erzwingung von Berechtigungen auf Datei- und Verzeichnisebene für jede Identität erhöht die Komplexität und ist möglicherweise mit bestimmten Arbeitslasten nicht kompatibel. Kunden möchten beispielsweise einen Dienst für eine Sicherungslösung autorisieren, auf Azure-Dateifreigaben mit Lesezugriff auf alle Dateien zuzugreifen, ohne Rücksicht auf dateispezifische Berechtigungen.

Ersetzung des Speicherkontoschlüssels

Microsoft Entra ID bietet überlegene Sicherheit und Benutzerfreundlichkeit gegenüber dem gemeinsam verwendeten Schüssel. Sie können den Zugriff auf Speicherkontoschlüssel durch OAuth-Authentifizierung und -Autorisierung für den Zugriff auf Azure-Dateifreigaben mit Lese-/Schreibberechtigungen ersetzen. Dieser Ansatz bietet auch eine bessere Überwachung und Nachverfolgung bestimmter Benutzerzugriffe.

Privilegierter Zugriff und Zugriffsberechtigungen für Datenvorgänge

Um die Azure Files OAuth über REST-Funktion zu verwenden, müssen zusätzliche Berechtigungen in die RBAC-Rolle aufgenommen werden, die dem Benutzer, der Gruppe oder dem Dienstprinzipal zugewiesen ist. Im Rahmen dieses Features werden zwei neue Datenaktionen eingeführt:

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

Benutzern, Gruppen oder Dienstprinzipalen, die die REST-API mit OAuth aufrufen, muss entweder die Aktion readFileBackupSemantics oder writeFileBackupSemantics der Rolle zugewiesen sein, die den Datenzugriff ermöglicht. Dies ist eine Voraussetzung, um dieses Feature zu verwenden. Einzelheiten zu den Berechtigungen, die für spezifische Vorgänge des Dateidienstes erforderlich sind, finden Sie unter Berechtigungen für das Aufrufen von Datenvorgängen.

Dieses Feature stellt zwei neue integrierte Rollen bereit, die diese neuen Aktionen enthalten.

Rolle	Datenaktionen
Privilegierter Leser von Speicherdateidaten	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Privilegierter Mitwirkender für Speicherdateidaten	`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`

Diese neuen Rollen ähneln den bestehenden integrierten Rollen Speicherdateidaten-SMB-Freigabeleser und Mitwirkender mit erhöhten Rechten für Speicherdateidaten-SMB-Freigabe, es gibt jedoch einige Unterschiede:

Die neuen Rollen enthalten die zusätzlichen Datenaktionen, die für den OAuth-Zugriff erforderlich sind.
Wenn der Benutzer, die Gruppe oder der Dienstprinzipal, dem die Rollen Privilegierter Leser von Speicherdateidaten oder Privilegierter Mitwirkender für Speicherdateidaten zugewiesen sind, die FilesREST-Daten-API mithilfe von OAuth aufruft, verfügt der Benutzer, die Gruppe oder der Dienstprinzipal über Folgendes:
- Privilegierter Leser von Speicherdateidaten: Vollständiger Lesezugriff auf alle Daten in den Freigaben für alle konfigurierten Speicherkonten, unabhängig von den festgelegten NTFS-Berechtigungen auf Datei-/Verzeichnisebene.
- Privilegierter Leser von Speicherdateidaten: Vollständiger Zugriff auf alle Daten mit Lese-, Schreib-, ACL-Modifizierungs- und Löschrechten in den Freigaben für alle konfigurierten Speicherkonten, unabhängig von den festgelegten NTFS-Berechtigungen auf Datei-/Verzeichnisebene.
Mit diesen speziellen Berechtigungen und Rollen umgeht das System alle Berechtigungen auf Datei-/ Verzeichnisebene und lässt den Zugriff auf Dateifreigabedaten zu.

Mit den neuen Rollen und Datenaktionen bietet dieses Funktion speicherkontoweite Berechtigungen, die alle Berechtigungen für Dateien und Ordner unter allen Dateifreigaben im Speicherkonto ablösen. Die neuen Rollen enthalten jedoch nur Berechtigungen für den Zugriff auf Datendienste. Sie enthalten keine Berechtigungen für den Zugriff auf Dateifreigabeverwaltungsdienste (Aktionen für Dateifreigaben). Um dieses Feature zu verwenden, stellen Sie sicher, dass Sie über Zugriffsberechtigungen für die folgenden Bereiche verfügen:

das Speicherkonto
Dateifreigabeverwaltungsdienste
Data Services (die Daten in der Dateifreigabe)

Es gibt viele integrierte Rollen, die Zugriff auf Verwaltungsdienste ermöglichen. Sie können auch benutzerdefinierte Rollen mit den entsprechenden Berechtigungen erstellen. Weitere Informationen über rollenbasierte Zugriffssteuerung finden Sie unter Azure RBAC (Azure Role-Based Access Control). Weitere Informationen dazu, wie integrierte Rollen definiert sind, finden Sie unter Grundlegendes zu Rollendefinitionen.

Wichtig

Alle Anwendungsfälle mit Platzhaltern, die für den Pfad Microsoft.Storage/storageAccounts/fileServices/* oder einen höheren Geltungsbereich definiert sind, erben automatisch die zusätzlichen Zugriffsmöglichkeiten und Berechtigungen, die durch diese neue Datenaktion gewährt werden. Um unbeabsichtigten oder übermäßig privilegierten Zugriff auf Azure Files zu verhindern, haben wir zusätzliche Überprüfungen implementiert, bei denen Benutzer und Anwendungen explizit angeben müssen, dass sie das zusätzliche Privileg nutzen möchten. Darüber hinaus empfehlen wir unseren Kunden dringend, ihre RBAC-Rollenzuweisungen zu überprüfen und die Verwendung von Platzhaltern durch explizite Berechtigungen zu ersetzen, um eine ordnungsgemäße Verwaltung des Datenzugriffs sicherzustellen.

Autorisierung des Zugriffs auf Dateidaten im Anwendungscode

Die Azure Identity-Clientbibliothek vereinfacht das Abrufen eines OAuth 2.0-Zugriffstokens für die Autorisierung mit Microsoft Entra ID über das Azure SDK. Die neuesten Versionen der Azure Storage-Clientbibliotheken für .NET, Java, Python, JavaScript und Go sind in die Azure Identity-Bibliotheken für jede dieser Sprachen integriert und bieten so eine einfache, sichere Möglichkeit zum Abrufen eines Zugriffstokens für die Autorisierung von Anforderungen vom Azure-Dateidienst.

Ein Vorteil der Azure Identity-Clientbibliothek besteht darin, dass Sie das Zugriffstoken mit demselben Code abrufen können, um zu erfahren, ob Ihre Anwendung in der Entwicklungsumgebung oder in Azure ausgeführt wird. Die Azure Identity-Clientbibliothek gibt ein Zugriffstoken für einen Sicherheitsprinzipal zurück. Wenn Ihr Code in Azure ausgeführt wird, kann der Sicherheitsprinzipal eine verwaltete Identität für Azure-Ressourcen, ein Dienstprinzipal oder aber ein Benutzer oder eine Gruppe sein. In der Entwicklungsumgebung stellt die Clientbibliothek ein Zugriffstoken für einen Benutzer oder einen Dienstprinzipal zu Testzwecken zur Verfügung.

Das von der Azure Identity-Clientbibliothek zurückgegebene Zugriffstoken ist in Token-Anmeldeinformationen gekapselt. Sie können dann mithilfe der Token-Anmeldeinformationen ein Dienstclientobjekt abrufen, das zum Ausführen autorisierter Vorgänge für den Azure-Datendienst verwendet wird.

Hier finden Sie Beispielcode dazu:

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 aadEndpoint = "";
            string accountUri = "";
            string connectionString = "";
            string shareName = "test-share";
            string directoryName = "testDirectory";
            string fileName = "testFile"; 

            ShareClient sharedKeyShareClient = new ShareClient(connectionString, shareName); 
            await sharedKeyShareClient.CreateIfNotExistsAsync(); 

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

            ShareClientOptions clientOptions = new ShareClientOptions(ShareClientOptions.ServiceVersion.V2023_05_03);

            // Set Allow Trailing Dot and Source Allow Trailing Dot.
            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();
            await sharedKeyShareClient.DeleteIfExistsAsync();
        }
    }
}

Autorisieren des Zugriffs mithilfe der FileREST-Datenebenen-API

Sie können den Zugriff auf Dateidaten auch mithilfe der Azure-Portal oder Azure PowerShell autorisieren.

Im Azure-Portal können Sie über Ihr Microsoft Entra-Konto oder die Zugriffsschlüssel für das Speicherkonto auf Dateidaten in einem Azure-Speicherkonto zugreifen. Welches Autorisierungsschema im Azure-Portal verwendet wird, hängt von den Ihnen zugewiesenen Azure-Rollen ab.

Wenn Sie versuchen, auf Dateidaten zuzugreifen, wird im Azure-Portal zunächst überprüft, ob Ihnen eine Azure-Rolle mit Microsoft.Storage/storageAccounts/listkeys/action zugewiesen ist. Wenn Ihnen eine Rolle mit dieser Aktion zugewiesen wurde, wird im Azure-Portal der Kontoschlüssel für den Zugriff auf Dateidaten per Authentifizierung mit gemeinsam verwendetem Schlüssel verwendet. Wenn Ihnen keine Rolle mit dieser Aktion zugewiesen wurde, wird im Azure-Portal versucht, über Ihr Microsoft Entra-Konto auf die Daten zuzugreifen.

Für den Zugriff auf Dateidaten über das Azure-Portal mithilfe Ihres Microsoft Entra-Kontos benötigen Sie Berechtigungen für den Zugriff auf Dateidaten sowie das Navigieren durch die Ressourcen des Speicherkontos im Azure-Portal. Die integrierten Rollen, die von Azure bereitgestellt werden, gewähren Zugriff auf Dateiressourcen, aber nicht auf die Speicherkontoressourcen. Aus diesem Grund erfordert der Zugriff auf das Portal außerdem die Zuweisung einer Azure Resource Manager-Rolle (ARM) (z. B. Leser) mindestens auf Ebene des Speicherkontos. Die Rolle Leser erteilt die am stärksten eingeschränkten Berechtigungen. Eine andere ARM-Rolle, die den Zugriff auf Ressourcen zur Verwaltung von Speicherkonten gewährt, ist jedoch akzeptabel.

Wenn Sie zu einem Container navigieren, wird im Azure-Portal angegeben, welches Autorisierungsschema verwendet wird. Weitere Informationen zum Datenzugriff im Portal finden Sie unter Auswählen der Autorisierung des Zugriffs auf Dateidaten im Azure-Portal.

Azure bietet Erweiterungen für PowerShell, mit denen Sie sich mit Microsoft Entra-Anmeldeinformationen anmelden und PowerShell-Cmdlets aufrufen können. Wenn Sie sich mit Microsoft Entra-Anmeldeinformationen bei PowerShell anmelden, wird ein OAuth 2.0-Zugriffstoken zurückgegeben. PowerShell verwendet dieses Token automatisch, um nachfolgende Datenvorgänge für den Dateispeicher zu autorisieren. Für unterstützte Vorgänge müssen Sie mit dem Befehl keinen Kontoschlüssel und kein SAS-Token mehr übergeben.

Sie können einem Microsoft Entra-Sicherheitsprinzipal über RBAC Berechtigungen für Warteschlangendaten zuweisen.

Unterstützte Vorgänge

Die Erweiterungen unterstützen nur Vorgänge für Dateidaten. Welche Vorgänge Sie aufrufen können, hängt von den Berechtigungen des Microsoft Entra-Sicherheitsprinzipals ab, mit dem Sie sich bei PowerShell angemeldet haben.

Der Speicherkontext mit OAuth funktioniert nur, wenn er mit dem -EnableFileBackupRequestIntent-Parameter aufgerufen wird. Dadurch wird die explizite Absicht angegeben, die zusätzlichen Berechtigungen zu verwenden, die dieses Feature bereitstellt.

Der Speicherkontext mit OAuth funktioniert nur für Operationen mit Dateien und Verzeichnissen sowie für die Berechtigungen „Get/Set“ auf Azure-Dateifreigaben. Für alle anderen Vorgänge auf Speicherkonten und Dateifreigaben müssen Sie den Schlüssel des Speicherkontos oder das SAS-Token verwenden.

Voraussetzungen

Sie benötigen eine Azure-Ressourcengruppe und ein Speicherkonto innerhalb dieser Ressourcengruppe. Dem Speicherkonto muss eine entsprechende Rolle zugewiesen werden, die explizite Berechtigungen zur Durchführung von Datenoperationen auf Dateifreigaben gewährt. Vergewissern Sie sich, dass Sie über die erforderlichen Rollen und Berechtigungen für den Zugriff auf die Verwaltungsdienste und Datendienste verfügen. Einzelheiten zu den Berechtigungen, die für spezifische Vorgänge des Dateidienstes erforderlich sind, finden Sie unter Berechtigungen für das Aufrufen von Datenvorgängen.

Installieren des Moduls „Az.Storage“

Dieses Feature ist im neuesten Az.Storage-Modul nicht verfügbar. Installieren Sie das Modul mit diesem Befehl:

Install-Module Az.Storage -Repository PsGallery

Autorisieren des Zugriffs auf Dateidaten

Führen Sie die folgenden Schritte aus, um den Zugriff auf Dateidaten zu autorisieren.

Melden Sie sich mithilfe des Connect-AzAccount-Cmdlets bei Ihrem Azure-Konto an.
Rufen Sie den Speicherkontokontext mithilfe des Speicherkontoschlüssels ab, indem Sie das Get-AzStorageAccount-Cmdlet (Verwaltungsdienst) aufrufen. Ersetzen Sie <ResourceGroupName> und <StorageAccountName> durch Ihre eigenen Werte.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Erstellen Sie eine Dateifreigabe, indem Sie New-AzStorageShare aufrufen. Da Sie den Speicherkontokontext aus Schritt 2 verwenden, wird die Dateifreigabe mit Ihrem Speicherkontoschlüssel erstellt.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Rufen Sie den Speicherkontokontext mit OAuth ab, um Datenoperationen auf der Dateifreigabe (Datendienst) durchzuführen. Ersetzen Sie <StorageAccountName> durch den Namen Ihres Speicherkontos.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Um den Speicherkontokontext mit OAuth abzurufen, müssen Sie den Parameter -EnableFileBackupRequestIntent explizit an das Cmdlet New-AzStorageContext übergeben. Wenn Sie den Absichtsparameter nicht übergeben, schlagen nachfolgende Datenvorgangsanforderungen für Dateifreigaben unter Verwendung des Kontexts fehl.
Erstellen Sie mithilfe der Cmdlets New-AzStorageDirectory und Set-AzStorageFileContent ein Testverzeichnis und eine Datei in der Dateifreigabe. Denken Sie daran, einen lokalen Quelldateipfad anzugeben.
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
Da die Cmdlets mithilfe des Speicherkontokontexts aus Schritt 4 aufgerufen werden, werden die Datei und das Verzeichnis mit Microsoft Entra-Anmeldeinformationen erstellt.

Kernbefehle der Azure CLI, die im Rahmen der CLI bereitgestellt werden, unterstützen Files OAuth über die REST-Schnittstelle, und Sie können sie verwenden, um Dateidatenvorgänge mit Microsoft Entra-Anmeldeinformationen zu authentifizieren und zu autorisieren.

Unterstützte Vorgänge

Die Befehle unterstützen nur Vorgänge für Dateidaten. Welche Vorgänge Sie aufrufen können, hängt von den Berechtigungen des Microsoft Entra-Sicherheitsprinzipals ab, mit dem Sie sich bei der Azure CLI angemeldet haben.

Die OAuth-Authentifizierung und -Autorisierung funktioniert nur, wenn der CLI-Befehl mit der Option --backup-intent oder der Option --enable-file-backup-request-intent aufgerufen wird. Dadurch wird die explizite Absicht angegeben, die zusätzlichen Berechtigungen zu verwenden, die dieses Feature bereitstellt.

Alle Befehle unter az storage file, az storage directory Befehlsgruppen und az storage share list-handle und az storage share close-handle unterstützen die OAuth-Authentifizierung und -Autorisierung. Für alle anderen Vorgänge auf Speicherkonten und Dateifreigaben müssen Sie den Schlüssel des Speicherkontos oder das SAS-Token verwenden.