Accedere alle condivisioni file di Azure usando Microsoft Entra ID con File di Azure OAuth su REST

Articolo
10/18/2023

File di Azure OAuth su REST consente l'accesso in lettura e scrittura a livello di amministratore alle condivisioni file di Azure per utenti e applicazioni tramite Protocollo di autenticazione OAuth, usando Microsoft Entra ID per l'accesso basato sull'API REST. Utenti, gruppi, servizi proprietari come portale di Azure e applicazioni e servizi di terze parti che usano interfacce REST possono ora usare l'autenticazione e l'autorizzazione OAuth con un account Microsoft Entra per accedere ai dati nelle condivisioni file di Azure. I cmdlet di PowerShell e i comandi dell'interfaccia della riga di comando di Azure che chiamano le API REST possono anche usare OAuth per accedere alle condivisioni file di Azure.

Importante

È necessario chiamare l'API REST usando un'intestazione esplicita per indicare la finalità di usare il privilegio aggiuntivo. Questo vale anche per l'accesso ad Azure PowerShell e all'interfaccia della riga di comando di Azure.

Limiti

File di Azure OAuth su REST supporta solo le API di dati FileREST che supportano operazioni su file e directory. OAuth non è supportato nelle API del piano dati FilesREST che gestiscono le risorse FileService e FileShare. Queste API di gestione vengono chiamate usando la chiave dell'account Archiviazione o il token di firma di accesso condiviso e vengono esposte tramite il piano dati per motivi legacy. È consigliabile usare le API del piano di controllo (il provider di risorse di archiviazione Microsoft.Archiviazione) che supportano OAuth per tutte le attività di gestione correlate alle risorse FileService e FileShare.

L'autorizzazione delle operazioni di dati dei file con Microsoft Entra ID è supportata solo per le versioni dell'API REST 2022-11-02 e successive. Vedere Controllo delle versioni per Archiviazione di Azure.

Casi d'uso dei clienti

L'autenticazione e l'autorizzazione OAuth con File di Azure tramite l'interfaccia API REST possono trarre vantaggio dai clienti negli scenari seguenti.

Integrazione di applicazioni e servizi

L'autenticazione e l'autorizzazione OAuth consentono agli sviluppatori di compilare applicazioni che accedono alle API REST Archiviazione di Azure usando identità utente o applicazione da Microsoft Entra ID.

I clienti e i partner possono anche abilitare i servizi proprietari e di terze parti per configurare l'accesso necessario in modo sicuro e trasparente a un account di archiviazione del cliente.

Gli strumenti DevOps, ad esempio i portale di Azure, PowerShell e l'interfaccia della riga di comando, AzCopy e Archiviazione Explorer possono gestire i dati usando l'identità dell'utente, eliminando la necessità di gestire o distribuire le chiavi di accesso alle risorse di archiviazione.

Identità gestite

I clienti con applicazioni e identità gestite che richiedono l'accesso ai dati di condivisione file per scopi di backup, ripristino o controllo possono trarre vantaggio dall'autenticazione e dall'autorizzazione OAuth. L'applicazione delle autorizzazioni a livello di file e directory per ogni identità aggiunge complessità e potrebbe non essere compatibile con determinati carichi di lavoro. Ad esempio, i clienti potrebbero voler autorizzare un servizio di soluzione di backup ad accedere alle condivisioni file di Azure con accesso in sola lettura a tutti i file senza considerare le autorizzazioni specifiche dei file.

sostituzione della chiave dell'account Archiviazione

Microsoft Entra ID offre maggiore sicurezza e facilità d'uso rispetto all'accesso con chiave condivisa. È possibile sostituire l'accesso alla chiave dell'account di archiviazione con l'autenticazione OAuth e l'autorizzazione per accedere alle condivisioni file di Azure con privilegi read-all/write-all. Questo approccio offre anche un controllo migliore e il monitoraggio dell'accesso utente specifico.

Autorizzazioni di accesso e accesso con privilegi per le operazioni dei dati

Per usare la funzionalità OAuth su REST di File di Azure, sono necessarie autorizzazioni aggiuntive da includere nel ruolo Controllo degli accessi in base al ruolo assegnato all'utente, al gruppo o all'entità servizio. Nell'ambito di questa funzionalità vengono introdotte due nuove azioni per i dati:

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

Gli utenti, i gruppi o le entità servizio che chiamano l'API REST con OAuth devono avere l'azione readFileBackupSemantics o writeFileBackupSemantics assegnata al ruolo che consente l'accesso ai dati. Si tratta di un requisito per usare questa funzionalità. Per informazioni dettagliate sulle autorizzazioni necessarie per chiamare operazioni specifiche del servizio file, vedere Autorizzazioni per chiamare le operazioni sui dati.

Questa funzionalità fornisce due nuovi ruoli predefiniti che includono queste nuove azioni.

Ruolo	Azioni dati
Lettore con privilegi per i dati dei file di archiviazione	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Collaboratore con privilegi per i dati dei file di archiviazione	`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`

Questi nuovi ruoli sono simili a quello esistente Archiviazione Lettore condivisione SMB di dati file e Archiviazione ruoli predefiniti Collaboratore con privilegi elevati di condivisione file di dati SMB, ma esistono alcune differenze:

I nuovi ruoli contengono le azioni di dati aggiuntive necessarie per l'accesso OAuth.
Quando l'utente, il gruppo o l'entità servizio assegnata Archiviazione lettore con privilegi per i dati dei file o Archiviazione ruoli collaboratore con privilegi per i dati file chiama l'API dati FilesREST usando OAuth, l'utente, il gruppo o l'entità servizio avranno:
- Archiviazione lettore con privilegi per i dati dei file: Accesso in lettura completo su tutti i dati nelle condivisioni per tutti gli account di archiviazione configurati indipendentemente dalle autorizzazioni NTFS a livello di file/directory impostate.
- Archiviazione Collaboratore con privilegi per i dati dei file: Lettura completa, scrittura, modifica degli elenchi di controllo di accesso, elimina l'accesso a tutti i dati nelle condivisioni per tutti gli account di archiviazione configurati indipendentemente dalle autorizzazioni NTFS a livello di file/directory impostate.
Con queste autorizzazioni e ruoli speciali, il sistema ignora le autorizzazioni a livello di file/directory e consente l'accesso ai dati di condivisione file.

Con le nuove azioni di ruoli e dati, questa funzionalità fornirà privilegi a livello di account di archiviazione che sostituisce tutte le autorizzazioni per file e cartelle in tutte le condivisioni file nell'account di archiviazione. Tuttavia, i nuovi ruoli contengono solo le autorizzazioni per accedere ai servizi dati. Non includono autorizzazioni per accedere ai servizi di gestione delle condivisioni file (azioni nelle condivisioni file). Per usare questa funzionalità, assicurarsi di disporre delle autorizzazioni per l'accesso:

l'account di archiviazione
servizi di gestione delle condivisioni file
servizi dati (i dati nella condivisione file)

Esistono molti ruoli predefiniti che forniscono l'accesso ai servizi di gestione. È anche possibile creare ruoli personalizzati con le autorizzazioni appropriate. Per altre informazioni sul controllo degli accessi in base al ruolo, vedere Controllo degli accessi in base al ruolo di Azure. Per altre informazioni sulla definizione dei ruoli predefiniti, vedere Informazioni sulle definizioni dei ruoli.

Importante

Tutti i casi d'uso con caratteri jolly definiti per il percorso Microsoft.Storage/storageAccounts/fileServices/* o un ambito superiore erediteranno automaticamente l'accesso aggiuntivo e le autorizzazioni concesse tramite questa nuova azione dati. Per impedire l'accesso imprevisto o con privilegi elevati a File di Azure, sono stati implementati controlli aggiuntivi che richiedono agli utenti e alle applicazioni di indicare in modo esplicito la loro intenzione di usare i privilegi aggiuntivi. È inoltre consigliabile che i clienti rivedano le assegnazioni di ruolo controllo degli accessi in base al ruolo degli utenti e sostituisci qualsiasi utilizzo con caratteri jolly con autorizzazioni esplicite per garantire una corretta gestione degli accessi ai dati.

Autorizzare l'accesso ai dati dei file nel codice dell'applicazione

La libreria client di Identità di Azure semplifica il processo di recupero di un token di accesso OAuth 2.0 per l'autorizzazione con Microsoft Entra ID tramite Azure SDK. Le versioni più recenti delle librerie client di Archiviazione di Azure per .NET, Java, Python, JavaScript e Go si integrano con le librerie di identità di Azure per ognuno di questi linguaggi per fornire un modo semplice e sicuro per acquisire un token di accesso per l'autorizzazione delle richieste dal servizio file di Azure.

Un vantaggio della libreria client di Identità di Azure è che consente di usare lo stesso codice per acquisire il token di accesso se l'applicazione è in esecuzione nell'ambiente di sviluppo o in Azure. La libreria client di Identità di Azure restituisce un token di accesso per un'entità di sicurezza. Quando il codice è in esecuzione in Azure, l'entità di sicurezza può essere un'identità gestita per le risorse di Azure, un'entità servizio o un utente o un gruppo. Nell'ambiente di sviluppo, la libreria client fornisce un token di accesso per un utente o un'entità servizio a scopo di test.

Il token di accesso restituito dalla libreria client di Identità di Azure viene incapsulato in una credenziale del token. È quindi possibile usare le credenziali del token per ottenere un oggetto client del servizio da usare per eseguire operazioni autorizzate sul servizio File di Azure.

Ecco del codice di esempio:

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

Autorizzare l'accesso tramite l'API del piano dati FileREST

È anche possibile autorizzare l'accesso ai dati dei file usando il portale di Azure o Azure PowerShell.

Il portale di Azure può usare l'account Microsoft Entra o la chiave di accesso dell'account di archiviazione per accedere ai dati dei file in un account di archiviazione di Azure. Lo schema di autorizzazione usato dal portale di Azure dipende dai ruoli di Azure assegnati all'utente.

Quando si tenta di accedere ai dati dei file, il portale di Azure controlla prima di tutto se è stato assegnato un ruolo di Azure con Microsoft.Storage/storageAccounts/listkeys/action. Se è stato assegnato un ruolo con questa azione, il portale di Azure usa la chiave dell'account per accedere ai dati dei file tramite l'autorizzazione con chiave condivisa. Se non è stato assegnato un ruolo con questa azione, il portale di Azure tenta di accedere ai dati usando l'account Microsoft Entra.

Per accedere ai dati dei file dalla portale di Azure usando l'account Microsoft Entra, sono necessarie le autorizzazioni per accedere ai dati dei file e sono necessarie anche le autorizzazioni per spostarsi tra le risorse dell'account di archiviazione nella portale di Azure. I ruoli predefiniti forniti da Azure concedono l'accesso alle risorse file, ma non concedono autorizzazioni alle risorse dell'account di archiviazione. Per questo motivo, l'accesso al portale richiede anche l'assegnazione di un ruolo di Azure Resource Manager (ARM), ad esempio il ruolo Lettore , con ambito al livello dell'account di archiviazione o superiore. Il ruolo Lettore concede le autorizzazioni più restrittive, ma qualsiasi ruolo arm che concede l'accesso alle risorse di gestione degli account di archiviazione è accettabile.

Il portale di Azure indica quale schema di autorizzazione è in uso quando si passa a un contenitore. Per altre informazioni sull'accesso ai dati nel portale, vedere Scegliere come autorizzare l'accesso ai dati dei file nel portale di Azure.

Azure fornisce estensioni per PowerShell che consentono di accedere e chiamare i cmdlet di PowerShell usando le credenziali di Microsoft Entra. Quando si accede a PowerShell con le credenziali di Microsoft Entra, viene restituito un token di accesso OAuth 2.0. PowerShell usa automaticamente tale token per autorizzare le operazioni successive sui dati sull'archiviazione file. Per le operazioni supportate, non è più necessario passare un chiave dell'account o un token di firma di accesso condiviso con il comando.

È possibile assegnare autorizzazioni ai dati dei file a un'entità di sicurezza Di Microsoft Entra tramite il controllo degli accessi in base al ruolo di Azure.

Operazioni supportate

Le estensioni supportano solo operazioni sui dati dei file. Le operazioni che è possibile chiamare dipendono dalle autorizzazioni concesse all'entità di sicurezza Microsoft Entra con cui è stato eseguito l'accesso a PowerShell.

Il contesto di archiviazione con OAuth funzionerà solo se viene chiamato con il -EnableFileBackupRequestIntent parametro . Si tratta di specificare la finalità esplicita di usare le autorizzazioni aggiuntive fornite da questa funzionalità.

Il contesto di archiviazione con OAuth funzionerà solo per le operazioni su file e directory e le autorizzazioni Get/Set per le condivisioni file di Azure. Per tutte le altre operazioni su account di archiviazione e condivisioni file, è necessario usare la chiave dell'account di archiviazione o il token di firma di accesso condiviso.

Prerequisiti

Sono necessari un gruppo di risorse di Azure e un account di archiviazione all'interno di tale gruppo di risorse. All'account di archiviazione deve essere assegnato un ruolo appropriato che concede autorizzazioni esplicite per eseguire operazioni sui dati nelle condivisioni file. Assicurarsi di disporre dei ruoli e delle autorizzazioni necessari per accedere sia ai servizi di gestione che ai servizi dati. Per informazioni dettagliate sulle autorizzazioni necessarie per chiamare operazioni specifiche del servizio file, vedere Autorizzazioni per chiamare le operazioni sui dati.

Installare il modulo Az.Archiviazione

Questa funzionalità è disponibile nel modulo Az.Archiviazione più recente. Installare il modulo usando questo comando:

Install-Module Az.Storage -Repository PsGallery

Autorizzare l'accesso ai dati dei file

Per autorizzare l'accesso ai dati dei file, seguire questa procedura.

Accedere all'account Azure usando il Connect-AzAccount cmdlet .
Ottenere il contesto dell'account di archiviazione usando la chiave dell'account di archiviazione chiamando il Get-AzStorageAccount cmdlet (servizio di gestione). Sostituire <ResourceGroupName> e <StorageAccountName> con i propri valori.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Creare una condivisione file chiamando New-AzStorageShare. Poiché si usa il contesto dell'account di archiviazione del passaggio 2, la condivisione file viene creata usando la chiave dell'account di archiviazione.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Ottenere il contesto dell'account di archiviazione usando OAuth per eseguire operazioni sui dati nella condivisione file (servizio dati). Sostituire <StorageAccountName> con il nome dell'account di archiviazione.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Per ottenere il contesto dell'account di archiviazione con OAuth, è necessario passare in modo esplicito il -EnableFileBackupRequestIntent parametro al New-AzStorageContext cmdlet . Se non si passa il parametro finalità, le successive richieste di operazioni sui dati di condivisione file che usano il contesto avranno esito negativo.
Creare una directory di test e un file nella condivisione file usando New-AzStorageDirectory i cmdlet e Set-AzStorageFileContent . Ricordarsi di specificare un percorso del file di origine locale.
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
Poiché i cmdlet vengono chiamati usando il contesto dell'account di archiviazione del passaggio 4, il file e la directory verranno creati usando le credenziali di Microsoft Entra.

I comandi principali dell'interfaccia della riga di comando di Azure forniti come parte dell'interfaccia della riga di comando supportano File OAuth tramite l'interfaccia REST ed è possibile usarli per autenticare e autorizzare operazioni sui dati di file usando le credenziali di Microsoft Entra.

Operazioni supportate

I comandi supportano solo operazioni sui dati dei file. Le operazioni che è possibile chiamare dipendono dalle autorizzazioni concesse all'entità di sicurezza Microsoft Entra con cui è stato eseguito l'accesso all'interfaccia della riga di comando di Azure.

L'autenticazione e l'autorizzazione OAuth funzioneranno solo se il comando dell'interfaccia della riga di comando viene chiamato con l'opzione o --enable-file-backup-request-intent l'opzione --backup-intent . Si tratta di specificare la finalità esplicita di usare le autorizzazioni aggiuntive fornite da questa funzionalità.

Tutti i comandi in az storage file, az storage directory i gruppi di comandi e az storage share close-handleaz storage share list-handle supportano l'autenticazione e l'autorizzazione OAuth. Per tutte le altre operazioni su account di archiviazione e condivisioni file, è necessario usare la chiave dell'account di archiviazione o il token di firma di accesso condiviso.