Accedere alle condivisioni file di Azure SMB usando identità gestite con Microsoft Entra ID (anteprima)

Si applica a: ✔️ Condivisioni file di Azure SMB

Questo articolo illustra come usare le identità gestite per consentire alle macchine virtuali Windows e Linux di accedere alle condivisioni file di Azure SMB usando l'autenticazione basata su identità con Microsoft Entra ID (anteprima).

Un'identità gestita è un'identità nell'ID Microsoft Entra gestito automaticamente da Azure. In genere si usano le identità gestite durante lo sviluppo di applicazioni cloud per gestire le credenziali per l'autenticazione nei servizi di Azure.

Al termine di questa guida, si avrà un account di archiviazione pronto per l'accesso con un'identità gestita. Si saprà anche come creare un'identità gestita per una macchina virtuale e generare un token OAuth. Si monterà quindi una condivisione file usando l'autenticazione e l'autorizzazione basate su identità gestite, eliminando la necessità di usare una chiave dell'account di archiviazione.

Perché eseguire l'autenticazione con un'identità gestita?

Per motivi di sicurezza, non è consigliabile usare le chiavi dell'account di archiviazione per accedere a una condivisione file. Quando si assegna un'identità gestita a una macchina virtuale o si usa un'identità dell'applicazione, è possibile usare tale identità per l'autenticazione in File di Azure.

I vantaggi includono:

• Sicurezza avanzata: Nessuna dipendenza dalle chiavi dell'account di archiviazione da gestire o esporre

• Gestione semplificata: Nessuna rotazione delle chiavi necessaria

• Controllo di accesso con granularità fine: Accesso basato sui ruoli a livello di identità

• Automazione semplice: Facile integrazione con pipeline CI/CD, carichi di lavoro del servizio Azure Kubernetes e applicazioni dei clienti

• Conveniente: Le identità gestite possono essere usate senza costi di archiviazione aggiuntivi

Identità gestite assegnate dal sistema e identità assegnate dall'utente

In Azure sono disponibili due tipi di identità gestite: assegnata dal sistema e assegnata dall'utente.

Un'identità gestita assegnata dal sistema è limitata a una per risorsa ed è associata al ciclo di vita di questa risorsa. È possibile concedere autorizzazioni all'identità gestita usando il controllo degli accessi in base al ruolo di Azure. L'identità gestita viene autenticata con Microsoft Entra ID, quindi non è necessario archiviare credenziali nel codice. Le identità gestite assegnate dal sistema non sono supportate nelle macchine virtuali Linux.

Le identità gestite assegnate dall'utente consentono alle risorse di Azure di eseguire l'autenticazione ai servizi cloud senza archiviare le credenziali nel codice. Questo tipo di identità gestite viene creato come risorsa di Azure autonoma e ha un proprio ciclo di vita. Una singola risorsa, ad esempio una macchina virtuale, può usare più identità gestite assegnate dall'utente. Analogamente, un'unica identità gestita assegnata dall'utente può essere condivisa tra più macchine virtuali.

Le macchine virtuali Windows possono essere configurate con identità gestite assegnate dall'utente e dal sistema.

Prerequisiti

Questo articolo presuppone che si disponga di una sottoscrizione Azure con autorizzazioni per creare account di archiviazione e assegnare ruoli di controllo degli accessi in base al ruolo di Azure (RBAC). Per assegnare ruoli, è necessario disporre dell'autorizzazione di scrittura per le assegnazioni di ruolo (Microsoft.Authorization/roleAssignments/write) nell'ambito a cui si vuole assegnare il ruolo.

Inoltre, i client che devono eseguire l'autenticazione usando un'identità gestita non devono essere aggiunti ad alcun dominio.

Preparare l'ambiente PowerShell

Aprire PowerShell come amministratore ed eseguire il comando seguente per impostare i criteri di esecuzione di PowerShell:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser 

Assicurarsi di avere la versione più recente di PowerShellGet:

Install-Module PowerShellGet -Force -AllowClobber 

Installare il modulo Az se non è già installato:

Install-Module -Name Az -Repository PSGallery -Force 
Import-Module Az 

Accedere ad Azure:

Connect-AzAccount

Selezionare la sottoscrizione specificando l'ID sottoscrizione (scelta consigliata):

Set-AzContext -SubscriptionId "<subscription-ID>" 

È anche possibile selezionare la sottoscrizione specificando il nome della sottoscrizione:

Set-AzContext -Subscription "<subscription-name>" 

Configurare la proprietà di accesso all'identità gestita nell'account di archiviazione

Per autenticare un'identità gestita, è necessario abilitare una proprietà denominata SMBOAuth nell'account di archiviazione che contiene la condivisione file di Azure a cui si vuole accedere. A questo scopo, è consigliabile creare un nuovo account di archiviazione. È possibile usare un account di archiviazione esistente solo se non è configurata un'altra origine di identità.

Per creare un nuovo account di archiviazione con SMBOAuth abilitato, eseguire il comando di PowerShell seguente come amministratore. Sostituire <resource-group>, <storage-account-name> e <region> con i propri valori. Se necessario, è possibile specificare uno SKU diverso.

New-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name> -SkuName Standard_LRS -Location <region> -EnableSmbOAuth $true

Per abilitare SMBOAuth in un account di archiviazione esistente, eseguire il comando di PowerShell seguente. Sostituire <resource-group> e <storage-account-name> con i propri valori.

Set-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name> -EnableSmbOAuth $true

Se vengono visualizzati errori che indicano che la risorsa è negata dai criteri di sottoscrizione, potrebbe esserci un criterio impostato nella sottoscrizione che non consente Set-AzStorageAccount. Per risolvere il problema, riprovare usando il comando seguente:

Set-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name> -EnableSmbOAuth $true -AllowBlobPublicAccess $false

Creare quindi una condivisione file SMB nell'account di archiviazione. Sostituire <resource-group>, <storage-account-name> e <file-share-name> con i propri valori.

$storageAccount = Get-AzStorageAccount -ResourceGroupName <resource-group> -Name <storage-account-name>
New-AzStorageShare -Name <file-share-name> -Context $storageAccount.Context

A questo momento dovrebbe essere disponibile un account di archiviazione e una condivisione file pronti per l'autenticazione OAuth SMB. Verificare nel portale di Azure che l'account di archiviazione e la condivisione file siano stati creati.

Configurare identità gestita

È possibile usare le identità gestite con Windows o Linux. Selezionare la scheda appropriata e seguire le istruzioni per il sistema operativo.

Windows

I passaggi di abilitazione descritti di seguito sono relativi alle macchine virtuali di Azure. Se si vuole abilitare un'identità gestita in computer Windows non Azure (locale o altro cloud), è necessario eseguirne l'onboarding in Azure Arc e assegnare un'identità gestita. È anche possibile eseguire l'autenticazione usando un'identità dell'applicazione anziché usare un'identità gestita in una macchina virtuale o in un dispositivo Windows.

Abilitare l'identità gestita in una macchina virtuale di Azure

Seguire questa procedura per abilitare un'identità gestita in una macchina virtuale di Azure.

1. Accedere al portale di Azure e creare una macchina virtuale Windows. La macchina virtuale deve eseguire Windows Server 2019 o versione successiva per gli SKU del server o qualsiasi SKU client Windows. Vedere Creare una macchina virtuale Windows nel portale di Azure.

2. Abilitare un'identità gestita nella macchina virtuale. Può essere assegnata dal sistema o assegnata dall'utente. Se la macchina virtuale dispone di identità assegnate sia dal sistema che dall'utente, Azure usa per impostazione predefinita quelle assegnate dal sistema. Assegnare solo uno per ottenere risultati ottimali. È possibile abilitare un'identità gestita assegnata dal sistema durante la creazione della macchina virtuale nella scheda Gestione .

   

Assegnare il ruolo RBAC predefinito all'identità gestita o all'identità dell'applicazione

Dopo che un'identità gestita è stata abilitata, è possibile concedere tutte le autorizzazioni necessarie tramite Azure RBAC. Per assegnare i ruoli, è necessario accedere come utente con autorizzazioni di scrittura per le assegnazioni di ruolo nell'ambito a cui si vuole assegnare il ruolo.

Seguire questi passaggi per assegnare il ruolo RBAC predefinito di Azure Amministratore MI dei dati file SMB di archiviazione, che consente l'accesso a livello di amministratore per le identità gestite sui file e le directory in Azure Files.

1. Accedere all'account di archiviazione che contiene la condivisione file che si desidera montare utilizzando un'identità gestita. Selezionare Controllo di accesso (IAM) dal menu del servizio.

2. Sotto Concedi l'accesso a questa risorsa, seleziona Aggiungi assegnazione ruolo.

3. Nella scheda Ruolo, in Ruoli delle funzioni lavorative, cercare e selezionare Archiviazione file di dati SMB MI Admin e quindi selezionare Avanti.

4. Nella scheda Membri , in Assegna accesso a, selezionare Identità gestita per macchine virtuali o identità di Azure Arc. Per le identità dell'applicazione selezionare Utente, gruppo o entità servizio.

5. In Membri fare clic su + Seleziona membri.

6. Per le macchine virtuali di Azure o le identità di Azure Arc, selezionare l'identità gestita per la macchina virtuale o il dispositivo Windows. Per identità dell'applicazione, cercare e selezionare l'identità dell'applicazione. Fare clic su Seleziona.

7. A questo punto dovrebbe essere visualizzata l'identità gestita o l'identità dell'applicazione elencata in Membri. Seleziona Avanti.

8. Selezionare Rivedi e assegna per aggiungere l'assegnazione di ruolo all'account di archiviazione.

Linux

Per configurare un'identità gestita in una macchina virtuale Linux in esecuzione in Azure, seguire questa procedura. La macchina virtuale deve eseguire Azure Linux 3.0, Ubuntu 22.04 o Ubuntu 24.04.

Annotazioni

Le identità gestite assegnate dal sistema non sono supportate nelle macchine virtuali Linux. È necessario creare un'identità gestita assegnata dall'utente.

1. Accedere al portale di Azure e creare un'identità gestita assegnata dall'utente.

2. Passare all'identità gestita appena creata e copiare l'ID client. che sarà necessario più avanti.

3. Navigare nell'account di archiviazione che contiene la condivisione file che si desidera montare usando un'identità gestita. Selezionare Controllo di accesso (IAM) dal menu del servizio.

4. Sotto Concedi l'accesso a questa risorsa, seleziona Aggiungi assegnazione ruolo.

5. Nella scheda Ruolo, in Ruoli di funzione lavorativa cercare e selezionare Archiviazione file di dati SMB MI Admin e quindi selezionare Avanti.

6. Nella scheda Membri, in Assegna accesso a, selezionare Identità gestita.

7. In Membri fare clic su + Seleziona membri. Viene visualizzato il riquadro Seleziona identità gestite .

8. In Identità gestita selezionare l'identità gestita assegnata dall'utente creata e quindi fare clic su Seleziona.

9. Verrà ora visualizzata l'identità gestita elencata in Membri. Seleziona Avanti.

10. Selezionare Rivedi e assegna per aggiungere l'assegnazione di ruolo all'account di archiviazione.

11. Passare alla VM. Dal menu del servizio, in Sicurezza, selezionare Identità.

12. Selezionare la scheda Assegnata dall'utente e quindi selezionare Aggiungi identità gestita assegnata dall'utente. Seleziona l'identità gestita che hai creato e assegnato all'utente, quindi seleziona Aggiungi.

Preparare il client per l'autenticazione usando un'identità gestita

Seguire questa procedura per preparare il sistema per montare la condivisione file usando l'autenticazione dell'identità gestita. I passaggi sono diversi per i client Windows e Linux. I clienti non devono essere uniti a un dominio.

Windows

Per preparare la macchina virtuale client o il dispositivo Windows per l'autenticazione usando un'identità gestita, seguire questa procedura.

1. Accedere alla macchina virtuale o al dispositivo con l'identità gestita assegnata e aprire una finestra di PowerShell come amministratore. È necessario PowerShell 5.1+ o PowerShell 7+.

2. Installare il modulo PowerShell Azure Files SMB Managed Identity Client e importarlo:

   Install-Module AzFilesSMBMIClient 
   Import-Module AzFilesSMBMIClient 
   

3. Controllare i criteri di esecuzione correnti di PowerShell eseguendo il comando seguente:

   Get-ExecutionPolicy -List 
   

   Se i criteri di esecuzione in CurrentUser sono limitati o non definiti, impostarlo su RemoteSigned. Se i criteri di esecuzione sono RemoteSigned, Default, AllSigned, Bypass o Unrestricted, è possibile ignorare questo passaggio.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
   

Aggiornare le credenziali di autenticazione

Prima di poter montare la condivisione file usando l'identità gestita, è necessario aggiornare le credenziali di autenticazione e specificare l'endpoint dell'account di archiviazione. Per copiare l'URI dell'account di archiviazione, passare all'account di archiviazione nel portale di Azure e quindi selezionare Impostazioni>Endpoint dal menu del servizio. Assicurarsi di copiare l'intero URI, inclusa la barra finale: https://<storage-account-name>.file.core.windows.net/

AzFilesSMBMIClient.exe refresh --uri https://<storage-account-name>.file.core.windows.net/

In questo modo si otterrà un token OAuth e lo inserirà nella cache Kerberos e si aggiornerà automaticamente quando il token è vicino alla scadenza. Facoltativamente, è possibile omettere .refresh

Se la macchina virtuale Windows ha sia identità gestite assegnate dall'utente che assegnate dal sistema configurate, è possibile usare il comando seguente per specificare l'identità gestita assegnata dall'utente. Sostituire <client-id> con l'ID client dell'identità gestita.

AzFilesSmbMIClient.exe refresh --uri https://<storage-account-name>.file.core.windows.net/ --clientId <client-id> 

Suggerimento

Per visualizzare informazioni complete sull'utilizzo ed esempi, eseguire il file eseguibile senza parametri: AzFilesSmbMIClient.exe

Linux

Per preparare la macchina virtuale Linux per l'autenticazione usando un'identità gestita, seguire questa procedura.

Scaricare e installare i pacchetti di autenticazione

La posizione del pacchetto e i passaggi di installazione variano a seconda della distribuzione di Linux.

Azure Linux 3.0

Eseguire i comandi seguenti per installare azfilesauth in Azure Linux 3.0:

tdnf update 
tdnf install azfilesauth

Ubuntu 22.04

Eseguire i comandi seguenti per eseguire l'installazione azfilesauth in Ubuntu 22.04:

curl -sSL -O https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb rm packages-microsoft-prod.deb
# the above steps update the sources.list
sudo apt-get update sudo apt-get install azfilesauth

Ubuntu 24.04

Eseguire i comandi seguenti per eseguire l'installazione azfilesauth in Ubuntu 24.04:

curl -SSL -O https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb rm packages-microsoft-prod.deb
# the above steps update the sources.list
sudo apt-get update sudo apt-get install azfilesauth

Configurare l'autenticazione

Sono disponibili due opzioni per la configurazione dell'autenticazione in Linux:

• Usare un'identità gestita della macchina virtuale: Scegliere questa opzione quando alla macchina virtuale è assegnata un'identità gestita assegnata dall'utente.
• Specificare direttamente il token OAuth: scegliere questa opzione se si gestiscono i token OAuth manualmente.

Opzione 1: Usare un'identità gestita della macchina virtuale

Se la macchina virtuale ha un'identità gestita assegnata dall'utente, eseguire i comandi seguenti. Assicurarsi di sostituire <client-id> con l'ID client dell'identità gestita. Se non si ha l'ID client, passare all'identità gestita e copiare l'ID client.

# Get a token from the Azure Instance Metadata Service (IMDS) and store it automatically
sudo azfilesauthmanager set https://<storage_account>.file.core.windows.net --imds-client-id <client-id>
# Verify the ticket was created properly
sudo azfilesauthmanager list

Opzione 2: Specificare direttamente il token OAuth

Se si gestiscono i token manualmente, specificare direttamente il token OAuth. Il valore aud (gruppo di destinatari) per il token deve essere https://storage.azure.com (nessuna barra finale) e non https://storage.azure.com/ per montare la condivisione file.

Eseguire i comandi seguenti e sostituire <storage-account-name> e <access-token> con i valori.

# Insert the token into your credential cache
sudo azfilesauthmanager set https://<storage-account-name>.file.core.windows.net <access-token> 
# Verify the ticket is properly stored
sudo azfilesauthmanager list

Montare la condivisione di file

È ora possibile montare la condivisione file in Windows o Linux senza usare una chiave dell'account di archiviazione.

Windows

Nei client Windows è possibile accedere direttamente alla condivisione file di Azure usando il percorso UNC immettendo quanto segue in Esplora file di Windows. Assicurarsi di sostituire <storage-account-name> con il nome dell'account di archiviazione e <file-share-name> con il nome della condivisione file:

\\<storage-account-name>.file.core.windows.net\<file-share-name>

Per altre informazioni, vedere Montare una condivisione file di Azure SMB in Windows.

Linux

Eseguire il comando seguente per montare la condivisione file con le opzioni di montaggio consigliate. Assicurarsi di sostituire <storage-account-name> con il nome dell'account di archiviazione e <file-share-name> con il nome della condivisione file. È possibile trovare l'ID credenziale nel file di configurazione seguente: cat /etc/azfilesauth/config.yaml

sudo mount -t cifs //<storage-account-name>.file.core.windows.net/<file-share-name> /mnt/smb -o sec=krb5,cruid=<credential-id>,dir_mode=0755,file_mode=0755,serverino,nosharesock,mfsymlinks,actimeo=30

Verificare che il montaggio sia riuscito:

ls -la /mnt/smb

Per ulteriori informazioni, vedere Montare condivisioni file di Azure SMB su client Linux.

Aggiornare le credenziali

Dopo aver montato la condivisione file per la prima volta, avviare il servizio di aggiornamento per mantenere aggiornate le credenziali. È possibile aggiornare le credenziali solo se alla macchina virtuale è assegnata un'identità gestita assegnata dall'utente. Se si specifica direttamente il token OAuth, l'aggiornamento non funzionerà.

sudo systemctl start azfilesauth

È consigliabile aggiornare periodicamente le credenziali per evitare interruzioni dell'accesso. È possibile aggiornare manualmente le credenziali usando il azfilesauthmanager set comando come descritto in Configurare l'autenticazione oppure è possibile automatizzare l'aggiornamento usando le API della libreria condivisa.

Risoluzione dei problemi

I passaggi per la risoluzione dei problemi sono diversi per i client Windows e Linux.

Windows

Se si verificano problemi durante il montaggio della condivisione file in Windows, seguire questa procedura per abilitare il log dettagliato e raccogliere informazioni diagnostiche.

1. Nei client Windows, utilizzare l'Editor del Registro per impostare il livello dati per il livello di verbosità su 0x00000004 (4) per Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\Storage\Files\SmbAuth.

2. Provare a montare di nuovo la condivisione e riprodurre l'errore.

3. A questo momento dovrebbe essere disponibile un file denominato AzFilesSmbMILog.log. Inviare il file di log a azurefilespm@microsoft.com per assistenza.

Linux

Se si verificano problemi durante il montaggio della condivisione file in Linux, seguire questa procedura di diagnostica SMB.

Opzioni di installazione e integrazione della libreria client

Le informazioni seguenti sono destinate agli sviluppatori che devono integrare le identità gestite nelle applicazioni.

Windows

Per gli sviluppatori che devono integrare le identità gestite nelle applicazioni Windows, sono disponibili più approcci di implementazione a seconda dell'architettura e dei requisiti dell'applicazione.

Integrazione di assembly gestiti: pacchetto NuGet

Per le applicazioni .NET, il pacchetto NuGet Microsoft.Azure.AzFilesSmbMI include un assembly gestito (Microsoft.Azure.AzFilesSmbMI.dll) che fornisce l'accesso diretto alla funzionalità di autenticazione OAuth SMB. Questo approccio è consigliato per C# e per altre applicazioni basate su .NET.

Installazione: Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94

Integrazione della DLL nativa

Per le applicazioni native che richiedono l'accesso diretto all'API, AzFilesSmbMIClient è disponibile come DLL nativa. Ciò è particolarmente utile per applicazioni o sistemi C/C++ che richiedono l'integrazione di livello inferiore. Vedere l'implementazione di Windows e il riferimento API (file di intestazione nativa).

Metodi dell'API nativa

La DLL nativa esporta i metodi di base seguenti per la gestione delle credenziali:

extern "C" AZFILESSMBMI_API HRESULT SmbSetCredential( 
    _In_  PCWSTR pwszFileEndpointUri, 
    _In_  PCWSTR pwszOauthToken, 
    _In_  PCWSTR pwszClientID, 
    _Out_ PDWORD pdwCredentialExpiresInSeconds 
); 
extern "C" AZFILESSMBMI_API HRESULT SmbRefreshCredential( 
    _In_ PCWSTR pwszFileEndpointUri, 
    _In_ PCWSTR pwszClientID 
); 
extern "C" AZFILESSMBMI_API HRESULT SmbClearCredential( 
    _In_ PCWSTR pwszFileEndpointUri 
); 

Linux

Gli sviluppatori Linux possono usare la libreria condivisa installata automaticamente con il pacchetto azfilesauth. È possibile collegarsi alla libreria nelle applicazioni C/C++ per l'accesso diretto alle API.

Assicurarsi di includere l'intestazione pubblica.

Per altre informazioni, vedere il progetto AzFilesAuthenticator.

Metodi dell'API della libreria condivisa

La libreria condivisa esporta i metodi di base seguenti per la gestione delle credenziali:

#ifdef __cplusplus
extern "C" {
#endif

int extern_smb_set_credential_oauth_token(char* file_endpoint_uri,
                                                char* auth_token,
                                                unsigned int* credential_expires_in_seconds);

int extern_smb_clear_credential(char* file_endpoint_uri);

int extern_smb_list_credential(bool is_json);

const char* extern_smb_version();

#ifdef __cplusplus
}
#endif

Descrizione API

La tabella seguente elenca i comandi api e il relativo utilizzo. I valori restituiti seguono le convenzioni C standard (0 per esito positivo, diverso da zero per gli errori).

Comando	Descrizione
extern_smb_set_credential_oauth_token()	Imposta le credenziali del token OAuth per un endpoint di archiviazione specifico
extern_smb_clear_credential()	Rimuove le credenziali archiviate per un endpoint di archiviazione
extern_smb_list_credential()	Elenca tutte le credenziali archiviate
extern_smb_version()	Restituisce la stringa di versione della libreria azfilesauth

Vedere anche

• Panoramica sull'autenticazione basata su identità per l'accesso SMB ai file di Azure
• Panoramica dell'autorizzazione e del controllo di accesso di File di Azure