Toegang tot Azure SMB-bestandsshares via beheerde identiteiten met Microsoft Entra ID

De stappen voor het inschakelen die hier worden beschreven, zijn bedoeld voor Azure VM's. Als u een beheerde identiteit wilt inschakelen op niet-Azure Windows-machines (on-premises of in een andere cloud), moet u ze aanmelden bij Azure Arc en een beheerde identiteit toewijzen. U kunt zich ook verifiëren met behulp van een toepassings-id in plaats van een beheerde identiteit op een virtuele machine of Windows apparaat.

Een beheerde identiteit inschakelen op een Azure-VM

De beheerde identiteit kan worden toegewezen aan het systeem of de gebruiker. Als de VM zowel systeemtoegewezen als gebruikerstoegewezen beheerde identiteiten heeft, geeft Azure standaard voorrang aan de systeemtoegewezen identiteit. Wijs slechts één toe voor de beste resultaten.

Een door het systeem toegewezen beheerde identiteit inschakelen

Volg deze stappen om een door het systeem toegewezen beheerde identiteit in te schakelen op een Windows VM die wordt uitgevoerd in Azure:

1. Meld u aan bij de Azure-portal en maak een Windows VM. De VM moet Windows Server 2019 of hoger hebben voor serversystemen, of een Windows-clientversie. Zie Maak een Windows virtuele machine in de Azure-portal.

2. U kunt een door het systeem toegewezen beheerde identiteit inschakelen tijdens het maken van de VIRTUELE machine op het tabblad Beheer .

   

Een door de gebruiker toegewezen beheerde identiteit inschakelen

1. Meld u aan bij de Azure-portal en volg de stappen om een door de gebruiker toegewezen beheerde identiteit te maken.

2. Ga naar de door de gebruiker toegewezen beheerde identiteit die u zojuist hebt gemaakt en kopieer de waarde van de client-id . U hebt deze waarde later nog nodig.

Een ingebouwde RBAC-rol toewijzen aan de beheerde identiteit of toepassingsidentiteit

Nadat u een beheerde identiteit hebt ingeschakeld, verleent u alle benodigde machtigingen via Azure RBAC. Als u rollen wilt toewijzen, meldt u zich aan als gebruiker met schrijfmachtiging voor roltoewijzing voor het vereiste bereik.

Volg deze stappen om de ingebouwde Azure RBAC-rol toe te wijzen Opslagbestandsgegevens SMB MI Admin. Deze rol biedt beheerderstoegang voor beheerde identiteiten in bestanden en mappen in Azure Files.

1. Ga naar het storage-account dat de bestandsshare bevat die u wilt koppelen met behulp van een beheerde identiteit. Selecteer in het servicemenu Access Control (IAM).

2. Selecteer onder Toegang verlenen tot deze resource, Roltoewijzing toevoegen.

3. Zoek naar en selecteer op het tabblad Rol, onder Functierolposities, de SMB MI-beheerder van opslagbestandsgegevens. Selecteer vervolgens Volgende.

4. Selecteer op het tabblad Leden onder Toegang toewijzen aan de optie Managed identity voor identiteiten van de virtuele machine of Azure Arc. Voor toepassingsidentiteiten selecteert u Gebruiker, groep of service-principal.

5. Selecteer onder Ledende optie + Leden selecteren.

6. Voor Azure VM's of Azure Arc identiteiten selecteert u de beheerde identiteit voor uw VM of Windows apparaat. Zoek en selecteer de toepassings-id voor toepassingsidentiteiten. Kies en selecteer.

7. Controleer of de beheerde identiteit of toepassingsidentiteit wordt vermeld onder Leden. Kies Volgende.

8. Selecteer Review + assign om de roltoewijzing toe te voegen aan het storage-account.

Een door de gebruiker toegewezen beheerde identiteit toevoegen aan een VIRTUELE machine

Als u een door de gebruiker toegewezen beheerde identiteit hebt gemaakt, volgt u deze stappen om deze toe te voegen aan uw VIRTUELE machine:

1. Ga naar uw virtuele machine. Selecteer Identiteit in het servicemenu onder Beveiliging.

2. Selecteer het tabblad Door de gebruiker toegewezen en selecteer vervolgens Gebruiker toegewezen beheerd identiteit toevoegen. Selecteer de beheerde identiteit die u hebt gemaakt en selecteer vervolgens Toevoegen.

Volg deze stappen om een beheerde identiteit te configureren op een Linux-VM die wordt uitgevoerd in Azure. Uw virtuele machine moet draaien op Azure Linux 3.0, Ubuntu 22.04, Ubuntu 24.04, RHEL 9.6+, of SLES 15 SP6+.

Een beheerde identiteit inschakelen op een Azure-VM

De beheerde identiteit kan worden toegewezen aan het systeem of de gebruiker. Als de VM zowel systeemtoegewezen als gebruikerstoegewezen beheerde identiteiten heeft, geeft Azure standaard voorrang aan de systeemtoegewezen identiteit. Wijs slechts één toe voor de beste resultaten.

Een door het systeem toegewezen beheerde identiteit inschakelen

1. Meld u aan bij de Azure-portal.

2. U kunt een door het systeem toegewezen beheerde identiteit inschakelen tijdens het maken van de virtuele machine op het tabblad Management. Zie Maak een virtuele Linux-machine in de Azure-portal.

   

Een door de gebruiker toegewezen beheerde identiteit inschakelen

1. Meld u aan bij de Azure-portal en volg de stappen om een door de gebruiker toegewezen beheerde identiteit te maken.

2. Ga naar de door de gebruiker toegewezen beheerde identiteit die u zojuist hebt gemaakt en kopieer de waarde van de client-id . U hebt deze waarde later nog nodig.

Een ingebouwde RBAC-rol toewijzen aan de beheerde identiteit

1. Ga naar het storage-account dat de bestandsshare bevat die u wilt koppelen met behulp van een beheerde identiteit. Selecteer in het servicemenu Access Control (IAM).

2. Selecteer onder Toegang verlenen tot deze resource, Roltoewijzing toevoegen.

3. Zoek naar en selecteer op het tabblad Rol, onder Functierolposities, de SMB MI-beheerder van opslagbestandsgegevens. Selecteer vervolgens Volgende.

4. Selecteer op het tabblad Leden onder Toegang toewijzen aanBeheerde identiteit.

5. Selecteer onder Ledende optie + Leden selecteren. Het deelvenster Selecteer beheerde identiteiten wordt weergegeven.

6. Selecteer onder Beheerde identiteit de beheerde identiteit en kies vervolgens Selecteren.

7. Controleer of de beheerde identiteit wordt vermeld onder Leden. Kies Volgende.

8. Selecteer Review + assign om de roltoewijzing toe te voegen aan het storage-account.

Een door de gebruiker toegewezen beheerde identiteit toevoegen aan een VIRTUELE machine

Als u een door de gebruiker toegewezen beheerde identiteit hebt gemaakt, volgt u deze stappen om deze toe te voegen aan uw VIRTUELE machine:

1. Ga naar uw virtuele machine. Selecteer Identiteit in het servicemenu onder Beveiliging.

2. Selecteer het tabblad Door de gebruiker toegewezen en selecteer vervolgens Gebruiker toegewezen beheerd identiteit toevoegen. Selecteer de beheerde identiteit die u hebt gemaakt en selecteer vervolgens Toevoegen.

Voer de volgende stappen uit om uw client-VM of Windows apparaat voor te bereiden om te verifiëren met behulp van een beheerde identiteit:

1. Meld u aan bij uw VIRTUELE machine of apparaat waaraan de beheerde identiteit is toegewezen en open een PowerShell-venster als beheerder. U hebt PowerShell 5.1+ of PowerShell 7+ nodig.

2. Installeer de PowerShell-module Azure Files SMB Managed Identity Client en importeer deze:

   Install-Module AzFilesSmbMIClient 
   Import-Module AzFilesSmbMIClient 
   

3. Controleer uw huidige PowerShell-uitvoeringsbeleid door de volgende opdracht uit te voeren:

   Get-ExecutionPolicy -List 
   

   Als het uitvoeringsbeleid CurrentUser is ingesteld op Restricted of Undefined, wijzigt u het in RemoteSigned. Als het uitvoeringsbeleid isRemoteSigned, Default, , AllSignedof BypassUnrestricted, kunt u deze stap overslaan.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
   

De verificatiereferenties vernieuwen

Voordat u de bestandsdeling kunt koppelen met behulp van de beheerde identiteit, ververst u de authenticatiegegevens en geeft u het eindpunt van uw opslagaccount op. Als u de URI van uw opslagaccount wilt kopiëren, gaat u naar het opslagaccount in de Azure-portal en selecteert u vervolgens Settings>Endpoints in het servicemenu. Zorg ervoor dat u de volledige URI kopieert, inclusief de afsluitende slash: https://<storage-account-name>.file.core.windows.net/.

Voer voor een door het systeem toegewezen beheerde identiteit de volgende opdracht uit om een OAuth-token op te halen, in te voegen in de Kerberos-cache en automatisch te vernieuwen wanneer het token bijna is verlopen. U kunt eventueel weglaten refresh.

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

Voor een door de gebruiker toegewezen beheerde identiteit moet u de client-id opgeven. Vervang door <client-id> de client-id van de beheerde identiteit.

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

Volg deze stappen om uw Virtuele Linux-machine voor te bereiden op verificatie met behulp van een beheerde identiteit.

De verificatiepakketten downloaden en installeren

De pakketlocatie en installatiestappen verschillen afhankelijk van uw Linux-distributie.

Azure Linux 3.0

Voer de volgende opdrachten uit om azfilesauth te installeren op Azure Linux 3.0:

tdnf update 
tdnf install azfilesauth

RHEL 9.6+

Voer de volgende opdrachten uit om te installeren azfilesauth op RHEL 9.6+:

curl -sSL -O https://packages.microsoft.com/config/$(source /etc/os-release && echo "$ID/${VERSION_ID%%.*}")/packages-microsoft-prod.rpm
sudo rpm -i packages-microsoft-prod.rpm
rm packages-microsoft-prod.rpm
dnf update
dnf install -y azfilesauth

Soms kan RHEL de toegang tot de kernel upcall naar de credential cache blokkeren. Als er een fout optreedt, raadpleeg /var/log/messages voor mogelijke oorzaken.

RHEL maakt standaard gebruik van een permanente referentie of KCM-cache. U kunt overschakelen naar een op bestanden gebaseerde cache voor azfilesauth:

  sudo tee /etc/krb5.conf.d/00-azfilesauth.conf > /dev/null <<EOF
  [libdefaults]
    default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  EOF

SLES 15 SP6+

Voer de volgende opdrachten uit om te installeren azfilesauth op SLES 15 SP6+:

curl -sSL -O https://packages.microsoft.com/config/sles/15/packages-microsoft-prod.rpm
sudo rpm -i packages-microsoft-prod.rpm
rm packages-microsoft-prod.rpm
sudo zypper refresh
sudo zypper install -y azfilesauth

SLES 15 SP6+ maakt standaard gebruik van een permanente referentie of KCM-cache. U kunt overschakelen naar een op bestanden gebaseerde cache voor azfilesauth:

  sudo tee /etc/krb5.conf.d/00-azfilesauth.conf > /dev/null <<EOF
  [libdefaults]
    default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  EOF

Ubuntu 22.04

Voer de volgende opdrachten uit om te installeren azfilesauth op 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 -y azfilesauth

Ubuntu 24.04

Voer de volgende opdrachten uit om te installeren azfilesauth op 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 -y azfilesauth

Verificatie configureren

U hebt twee opties voor het configureren van verificatie in Linux:

• Gebruik een beheerde identiteit voor een VIRTUELE machine: selecteer deze optie als aan uw VIRTUELE machine een beheerde identiteit is toegewezen.
• Geef het OAuth-token rechtstreeks op: selecteer deze optie als u zelf OAuth-tokens beheert.

Optie 1: Een beheerde identiteit voor een VM gebruiken

U kunt een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit gebruiken om verificatie te configureren.

Als uw VIRTUELE machine een door de gebruiker toegewezen beheerde identiteit heeft, voert u de volgende opdracht uit om een token op te halen uit de Azure Instance Metadata Service (IMDS) en deze automatisch op te slaan. Vervang door <storage-account-name> de naam van uw opslagaccount. Vervang door <client-id> de client-id van uw beheerde identiteit. Als u de client-id niet hebt, gaat u naar de beheerde identiteit in de Azure-portal en kopieert u de client-id.

sudo azfilesauthmanager set https://<storage-account-name>.file.core.windows.net --imds-client-id <client-id>

Als uw VM een door het systeem toegewezen beheerde identiteit heeft, gebruikt u de --system vlag en geeft u geen client-id op:

sudo azfilesauthmanager set https://<storage-account-name>.file.core.windows.net --system

Controleer of het ticket juist is gemaakt:

sudo azfilesauthmanager list

Optie 2: Het OAuth-token rechtstreeks opgeven

Als u tokens zelf beheert, geeft u het OAuth-token rechtstreeks op. De aud (doelgroep) waarde voor het token moet https://storage.azure.com (geen afsluitende schuine streep naar voren) zijn en mag niet https://storage.azure.com/ zijn om de bestandsdeling te koppelen.

Voer de volgende opdrachten uit. Vervang <storage-account-name> en <access-token> door uw waarden.

# 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

Op Windows-klanten krijgt u rechtstreeks toegang tot uw Azure-bestandsonderdeel met behulp van het UNC-pad door het volgende pad in te voeren in de Windows Verkenner. Vervang <storage-account-name> door de naam van uw storage account en <file-share-name> door de naam van uw bestandsshare.

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

Zie Mount SMB Azure file share on Windows voor meer informatie.

Voer de volgende opdracht uit om de bestandsshare te koppelen met de aanbevolen koppelingsopties. Vervang <storage-account-name> door de naam van uw storage account en <file-share-name> door de naam van uw bestandsshare. U vindt uw referentie-id in het volgende configuratiebestand: cat /etc/azfilesauth/config.yaml Neem voor een door de gebruiker toegewezen beheerde identiteit de client-id van de beheerde identiteit op met behulp van de username=<client-id> koppelingsoptie. Voor een door het systeem toegewezen beheerde identiteit laat u de koppelingsoptie achterwege username=<client-id>.

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

Controleer of de koppeling is geslaagd:

ls -la /mnt/smb

Zie SMB Azure-bestandsshares koppelen op Linux-clients voor meer informatie.

Werk uw inloggegevens bij

Als u toegangsonderbrekingen wilt voorkomen, moet u uw referenties regelmatig vernieuwen. De vernieuwingsservice detecteert en vernieuwt zo nodig automatisch referenties.

Nadat u de bestandsshare voor het eerst hebt gekoppeld, start u de vernieuwingsservice:

sudo systemctl start azfilesrefresh

Om ervoor te zorgen dat de service automatisch wordt gestart bij elke opstartbewerking:

sudo systemctl enable --now azfilesrefresh

Voor het automatisch vernieuwen van referenties is een beheerde identiteit vereist die is toegewezen aan uw virtuele machine. Als u het OAuth-token rechtstreeks opgeeft, moet u referenties handmatig vernieuwen met behulp van de azfilesauthmanager set opdracht zoals beschreven in Verificatie configureren of programmatisch via de gedeelde bibliotheek-API's.

Als u problemen ondervindt bij het koppelen van uw bestandsshare op Windows, volgt u deze stappen om uitgebreide logboekregistratie in te schakelen en diagnostische gegevens te verzamelen:

1. Op Windows-clients gebruikt u de Register-editor om het niveau Data voor verbosity in te stellen op 0x00000004 (4) voor Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\Storage\Files\SmbAuth.

2. Probeer de share opnieuw te koppelen en de fout te reproduceren.

3. U hebt nu een bestand met de naam AzFilesSmbMILog.log. Stuur het logboekbestand naar het Azure Files-team voor hulp.

Als u problemen ondervindt bij het koppelen van uw bestandsdeling op Linux, volgt u deze diagnostische stappen voor SMB.

Voor ontwikkelaars die beheerde identiteiten moeten integreren in hun Windows toepassingen, zijn er meerdere implementatiemethoden beschikbaar. De benadering die u kiest, is afhankelijk van uw toepassingsarchitectuur en -vereisten.

NuGet-pakket voor beheerde assembly-integratie

De Microsoft.Azure.AzFilesSmbMI NuGet-pakket voor .NET-toepassingen bevat een beheerde assembly (Microsoft.Azure.AzFilesSmbMI.dll) die directe toegang biedt tot de SMB OAuth-verificatiefunctionaliteit. Gebruik deze methode voor C# en andere op .NET gebaseerde toepassingen.

Gebruik Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94 om de assembly te installeren.

Systeemeigen DLL-integratie

Voor systeemeigen toepassingen die directe API-toegang nodig hebben, is AzFilesSmbMIClient beschikbaar als een natieve DLL. Deze optie is met name handig voor C/C++-toepassingen of -systemen die integratie op een lager niveau nodig hebben. Zie de Windows-implementatie en API-verwijzing (systeemeigen headerbestand).

Systeemeigen API-methoden

De systeemeigen DLL exporteert de volgende kernmethoden voor referentiebeheer:

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-ontwikkelaars kunnen de gedeelde bibliotheek gebruiken die automatisch met het azfilesauth pakket wordt geïnstalleerd. U kunt een koppeling maken met de bibliotheek in uw C/C++-toepassingen voor directe API-access.

Zorg ervoor dat u de public header opneemt.

Zie het project AzFilesAuthenticator voor meer informatie.

Api-methoden voor gedeelde bibliotheken

De gedeelde bibliotheek exporteert de volgende kernmethoden voor referentiebeheer:

#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

API-beschrijving

De volgende tabel bevat de API-opdrachten en het bijbehorende gebruik. Geretourneerde waarden volgen de standaard-C-conventies (nul voor succes, niet-nul voor fouten).