Accedere alle condivisioni file di Azure utilizzando Microsoft Entra ID con OAuth di Azure Files tramite REST

✔️ Si applica a: condivisioni file SMB e NFS classiche create con il Microsoft.Storage provider di risorse

✖️ Non si applica a: Condivisioni di file create con il Microsoft.FileShares fornitore di risorse (anteprima)

Usando Azure Files OAuth su REST, gli utenti e le applicazioni possono ottenere l'accesso in lettura e scrittura a livello di amministratore alle condivisioni file Azure tramite il protocollo di autenticazione OAuth. Questo metodo di accesso usa Microsoft Entra ID per l'accesso basato sull'API REST.

Utenti, gruppi, servizi Microsoft come il portale di Azure e servizi e applicazioni partner che usano interfacce REST possono ora usare l'autenticazione OAuth e l'autorizzazione con un account Microsoft Entra per accedere ai dati in File di Azure. I cmdlet di Azure PowerShell e i comandi dell'interfaccia della riga di comando di Azure che chiamano le API REST possono anche usare OAuth per accedere a File di Azure.

È necessario chiamare l'API REST usando un'intestazione esplicita per indicare la finalità di usare il privilegio aggiuntivo. Questo requisito si applica anche ai Azure PowerShell e all'accesso Azure CLI.

Questo articolo illustra come abilitare l'accesso a livello di amministratore per condivisioni di file Azure per casi d'uso specifici di cliente. Per un articolo più generale sull'autenticazione basata sull'identità per gli utenti, vedere Panoramica dell'autenticazione basata sull'identità di File di Azure.

Limitazioni

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

Il supporto Azure Files OAuth su REST per le API REST del piano dati di Azure Files che gestiscono le risorse FileService e FileShare è disponibile con le versioni dell'API REST 2024-11-04 e successive.

Vedere Versioning per Azure Storage.

Casi d'uso dei clienti

L'autenticazione e l'autorizzazione OAuth con Azure Files 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 creare applicazioni che accedono alle API REST di Archiviazione di Azure usando identità utente o applicazione da Microsoft Entra ID.

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

Gli strumenti DevOps, ad esempio il portale di Azure, Azure PowerShell, l'interfaccia della riga di comando di Azure, AzCopy e Azure Storage Explorer possono gestire i dati usando l'identità dell'utente. L'uso di questa identità elimina 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 a livello di 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 a Azure condivisioni file con accesso in sola lettura a tutti i file senza considerare le autorizzazioni specifiche del file.

Sostituzione delle chiavi dell'account di archiviazione

Microsoft Entra ID offre maggiore sicurezza e facilità d'uso rispetto all'accesso con chiave condivisa. Sostituire l'accesso alle chiavi dell'account di archiviazione di Azure usando l'autenticazione e autorizzazione OAuth per accedere alle condivisioni di file di Azure con privilegi di lettura completa/scrittura completa. Questo approccio offre anche un controllo e un monitoraggio migliori dell'accesso utente specifico.

Accesso con privilegi e autorizzazioni di accesso per operazioni sui dati

Per utilizzare la funzionalità OAuth di File di Azure su REST, includere autorizzazioni aggiuntive nel ruolo di controllo degli accessi basato sui ruoli (RBAC) che si assegna all'utente, gruppo o principale del servizio. Questa funzionalità introduce due nuove azioni 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 tramite OAuth devono avere assegnata al ruolo l'azione readFileBackupSemantics o writeFileBackupSemantics che consente l'accesso ai dati. Questa assegnazione è un requisito per usare questa funzionalità. Per informazioni dettagliate sulle autorizzazioni necessarie per chiamare operazioni specifiche del servizio File di Azure, vedere Autorizzazioni per chiamare le operazioni sui dati.

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

Role	Azioni dati
Lettore privilegiato per i dati dei file di archiviazione	`Microsoft.Storage/storageAccounts/fileServices/fileshares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Collaboratore privilegiato per i dati di file di storage	`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 ruoli sono simili ai ruoli predefiniti Lettore di condivisione SMB dei dati dei file di archiviazione e Collaboratore con privilegi elevati per la condivisione SMB dei dati dei file di archiviazione, ma esistono alcune differenze:

I nuovi ruoli contengono le azioni di dati aggiuntive richieste dall'accesso OAuth.
Quando all'utente, al gruppo o all'entità servizio viene assegnato il ruolo di Lettore Privilegiato dei Dati dei File di Archiviazione o Collaboratore Privilegiato dei Dati dei File di Archiviazione e chiama l'API dati FileREST usando OAuth, l'utente, il gruppo o l'entità servizio dispone di:
- Lettore con privilegi per i dati dei file di archiviazione: 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 o a livello di directory impostate.
- Collaboratore con privilegi per i dati dei file di archiviazione: lettura completa, scrittura, modifica-ACL ed eliminazione dell'accesso a tutti i dati nelle condivisioni per tutti gli account di archiviazione configurati indipendentemente dalle autorizzazioni NTFS a livello di file o a livello di directory impostate.
Quando si usano queste autorizzazioni e ruoli speciali, il sistema ignora le autorizzazioni a livello di file o a livello di directory e concede l'accesso ai dati di condivisione file.

Quando si utilizzano i nuovi ruoli e le azioni sui dati, questa funzionalità fornisce privilegi a livello di account di archivio che sostituiscono tutte le autorizzazioni su file e cartelle in tutte le condivisioni di file nell'account di archivio. 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).

Molti ruoli predefiniti 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 Azure RBAC. Per altre informazioni sul modo in cui vengono definiti i ruoli predefiniti, vedere Informazioni sulle definizioni di ruolo.

Per il tipo di risorsa di condivisione file, l'ambito RBAC corrispondente usa shares nel piano di controllo (operazioni di gestione) ma usa fileshares nel piano dati (operazioni dati). Se si tenta di usare un ID risorsa di condivisione file che contiene shares nell'ambito RBAC o nelle stringhe di azione dati, non funziona. È necessario usare fileshares quando si assegnano RBAC, ad esempio:

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

Importante

Tutti i casi d'uso dei caratteri jolly definiti per il percorso Microsoft.Storage/storageAccounts/fileServices/* o per un ambito superiore ereditano automaticamente l'accesso supplementare e le autorizzazioni concesse tramite questa nuova azione sui dati. Per impedire l'accesso indesiderato o eccessivo a File di Azure, il sistema implementa controlli aggiuntivi che richiedono agli utenti e alle applicazioni di indicare in modo esplicito la loro intenzione di usare il privilegio aggiuntivo. È anche necessario esaminare le assegnazioni di ruolo RBAC dell'utente e sostituire l'uso dei caratteri jolly con autorizzazioni esplicite per garantire una corretta gestione dell'accesso ai dati.

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

La libreria client di Azure Identity semplifica il processo di recupero di un token di accesso OAuth 2.0 per l'autorizzazione con 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. Questa integrazione offre un mezzo 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 è possibile usare lo stesso codice per acquisire il token di accesso indipendentemente dal fatto che l'applicazione sia in esecuzione nell'ambiente di sviluppo o in Azure. La libreria client Azure Identity 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 gruppo. Nell'ambiente di sviluppo, la libreria client fornisce un token di accesso per un utente o un'entità servizio a scopo di test.

La libreria client Azure Identity incapsula il token di accesso in una credenziale del token. Usare le credenziali del token per ottenere un oggetto client del servizio per eseguire operazioni autorizzate sul servizio Azure Files.

Nell'esempio di codice seguente viene illustrato come autorizzare un oggetto client usando Entra ID ed eseguire operazioni a livello di directory e file. In questo esempio si presuppone che la condivisione file esista già.

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

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

È anche possibile autorizzare l'accesso ai dati dei file usando il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure.

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

Quando si tenta di accedere ai dati dei file, il portale di Azure verifica innanzitutto se si dispone di un ruolo di Azure con Microsoft.Storage/storageAccounts/listkeys/action. Se si ha un ruolo con questa azione, il portale di Azure usa la chiave dell'account di archiviazione per accedere ai dati dei file tramite l'autorizzazione con chiave condivisa. Se non si ha un ruolo con questa azione, il portale di Azure tenta di accedere ai dati usando l'account Entra.

Per accedere ai dati dei file dal portale di Azure usando l'account Entra, sono necessarie le autorizzazioni per accedere ai dati dei file. Sono necessarie anche le autorizzazioni per spostarsi tra le risorse dell'account di archiviazione nel portale di Azure. I ruoli predefiniti di Azure concedono l'accesso alle risorse file, ma non concedono le 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, 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 di Resource Manager che concede l'accesso alle risorse di gestione degli account di archiviazione è accettabile.

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

Le estensioni per Azure PowerShell consentono di accedere e chiamare i cmdlet di Azure PowerShell usando le credenziali Entra. Quando si accede ad Azure PowerShell usando le credenziali Entra, si riceve un token di accesso OAuth 2.0. Azure PowerShell usa automaticamente tale token per autorizzare le operazioni successive sui dati nell'archiviazione file. Per le operazioni supportate, non è più necessario passare una 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 Entra con cui è stato eseguito l'accesso ad Azure PowerShell.

Il contesto di archiviazione con OAuth funziona solo se viene chiamato con il -EnableFileBackupRequestIntent parametro . Questo parametro specifica la finalità esplicita di usare le autorizzazioni aggiuntive fornite da questa funzionalità.

Il contesto di archiviazione con OAuth funziona solo per operazioni su file e directory e le Get/Set autorizzazioni delle condivisioni di file Azure. Per tutte le altre operazioni sugli account di archiviazione e sulle condivisioni di file, è necessario utilizzare la chiave dell'account di archiviazione o il token SAS.

Prerequisiti

Sono necessari un gruppo di risorse Azure e un account di archiviazione all'interno di tale gruppo di risorse. All'account di archiviazione deve essere assegnato un ruolo che concede autorizzazioni esplicite per eseguire operazioni sui dati sulle 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 di Azure, vedere Autorizzazioni per chiamare le operazioni sui dati.

È anche necessario installare il modulo Az.Storage più recente:

Install-Module Az.Storage -Repository PsGallery

Autorizzare l'accesso ai dati dei file

Per autorizzare l'accesso ai dati dei file tramite Azure PowerShell, seguire questa procedura:

Accedere all'account Azure usando il cmdlet Connect-AzAccount.
Ottenere il contesto dell'account di archiviazione usando la chiave dell'account di archiviazione. Chiamare 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. Dato che utilizzi il contesto dell'account di archiviazione dal passaggio 2, crei la condivisione file utilizzando 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 effettuare operazioni sui dati nella condivisione di file (servizio di dati). Sostituire <StorageAccountName> con il nome dell'account di archiviazione.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Per ottenere il contesto dell'account di archiviazione usando OAuth, è necessario passare il parametro -EnableFileBackupRequestIntent in modo esplicito al cmdlet New-AzStorageContext. Se non si passa il parametro finalità, le successive richieste di operazioni sui dati di condivisione file tramite il contesto hanno esito negativo.
Creare una directory di test e un file nella condivisione file usando i cmdlet New-AzStorageDirectory 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é si chiamano i cmdlet utilizzando il contesto dell'account di archiviazione dalla fase 4, si creano il file e la directory utilizzando le credenziali Entra.

I comandi principali dell'Azure CLI forniti come parte del CLI supportano OAuth su REST per Azure Files. È possibile usarli per autenticare e autorizzare le operazioni di dati dei file usando le credenziali Entra.

Operazioni supportate

I comandi supportano le operazioni solo sui dati dei file. Le operazioni che è possibile chiamare dipendono dalle autorizzazioni concesse all'entità di sicurezza Entra usata per accedere al CLI di Azure.

L'autenticazione e l'autorizzazione OAuth funzionano solo se si chiama il comando dell'interfaccia della riga di comando usando l'opzione --backup-intent o l'opzione --enable-file-backup-request-intent . Usando queste opzioni, si specifica la finalità esplicita di usare le autorizzazioni aggiuntive fornite da questa funzionalità.

Tutti i comandi nei gruppi di comandi az storage file e az storage directory eseguono, insieme ai comandi az storage share list-handle e az storage share close-handle, l’autenticazione e l’autorizzazione OAuth. Per tutte le altre operazioni sugli account di archiviazione e le condivisioni file, è necessario usare la chiave dell'account di archiviazione o il token di firma di accesso condiviso .For all other operations on storage accounts and file shares, you must use the storage account key or shared access signature (SAS).

Prerequisiti

Se non è già stato fatto, installare la versione più recente dell'interfaccia della riga di comando di Azure.

Autorizzare l'accesso ai dati dei file

Seguire questa procedura per autorizzare l'accesso ai dati dei file usando l'interfaccia della riga di comando di Azure:

Accedi al tuo account Azure.
```
az login
```
Creare una condivisione file chiamando az storage share create. Poiché si usa la stringa di connessione, la condivisione file viene creata tramite la chiave dell'account di archiviazione.
```
az storage share create --name testshare1 --connection-string <connection-string>
```
Creare una directory di test e caricare un file nella condivisione file usando az storage directory create e az storage file upload. Specificare --auth-mode come login e passare il parametro --backup-intent.
```
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>
```
Poiché i comandi CLI utilizzano il tipo di autenticazione come login (--auth-mode login con il parametro --backup-intent), il file e la directory vengono creati tramite le credenziali Entra.

Per altre informazioni, vedere la documentazione relativa ai comandi supportati: