Uzyskiwanie dostępu do udziałów plików Azure SMB przy użyciu tożsamości zarządzanych z Microsoft Entra ID

Kroki włączania opisane tutaj dotyczą maszyn wirtualnych Azure. Jeśli chcesz włączyć tożsamość zarządzaną na maszynach z systemem Windows, które nie działają na platformie Azure (lokalnie lub w innej chmurze), musisz dodać je do Azure Arc i przypisać im tożsamość zarządzaną. Można również uwierzytelnić się przy użyciu tożsamości aplikacji zamiast tożsamości zarządzanej na maszynie wirtualnej lub urządzeniu z systemem Windows.

Włącz tożsamość zarządzaną na maszynie wirtualnej Azure

Tożsamość zarządzana może być przypisana przez system lub przypisana przez użytkownika. Jeśli maszyna wirtualna ma tożsamości zarządzane przypisane przez system i przypisane przez użytkownika, Azure domyślnie wybiera tożsamości przypisane przez system. Przypisz tylko jeden, aby uzyskać najlepsze wyniki.

Włącz tożsamość zarządzaną przypisaną przez system

Wykonaj następujące kroki, aby włączyć tożsamość zarządzaną przypisaną przez system na maszynie wirtualnej Windows uruchomionej w Azure:

1. Zaloguj się do portalu Azure i utwórz maszynę wirtualną Windows. Maszyna wirtualna musi uruchomić Windows Server 2019 lub nowszą dla wersji serwera lub dowolnej wersji klienta Windows. Zobacz Utwórz maszynę wirtualną Windows w portalu Azure.

2. Tożsamość zarządzaną przypisaną przez system można włączyć podczas tworzenia maszyny wirtualnej na karcie Zarządzanie .

   

Włącz tożsamość zarządzaną przypisaną przez użytkownika

1. Zaloguj się do portalu Azure i wykonaj kroki, aby utwórz tożsamość zarządzaną przypisaną przez użytkownika.

2. Przejdź do właśnie utworzonej tożsamości zarządzanej przypisanej przez użytkownika i skopiuj wartość Identyfikator klienta . Ta wartość będzie potrzebna później.

Przypisz wbudowaną rolę RBAC do tożsamości zarządzanej lub tożsamości aplikacji

Po włączeniu tożsamości zarządzanej przyznaj wszystkie niezbędne uprawnienia za pośrednictwem Azure RBAC. Aby przypisać role, zaloguj się jako użytkownik z uprawnieniami do przypisywania ról w określonym zakresie.

Wykonaj następujące kroki, aby przypisać wbudowaną rolę RBAC Azure Storage File Data SMB MI Admin. Ta rola zapewnia dostęp na poziomie administratora dla tożsamości zarządzanych w plikach i katalogach w Azure Files.

1. Przejdź do konta storage zawierającego udział plików, który chcesz zainstalować przy użyciu tożsamości zarządzanej. W menu usługi wybierz pozycję Access Control (IAM).

2. W sekcji Przyznaj dostęp do tego zasobu wybierz Dodaj przypisanie do roli.

3. Na karcie Rola w obszarze Role funkcji zadania wyszukaj i wybierz Storage File Data SMB MI Admin. Następnie wybierz Dalej.

4. Na karcie Members w sekcji Przypisz dostęp do wybierz Zarządzana tożsamość dla maszyny wirtualnej lub tożsamości Azure Arc. W przypadku tożsamości aplikacji wybierz pozycję Użytkownik, grupa lub jednostka usługi.

5. W obszarze Członkowie wybierz pozycję + Wybierz członków.

6. W przypadku maszyn wirtualnych Azure lub tożsamości Azure Arc wybierz tożsamość zarządzaną dla maszyny wirtualnej lub urządzenia Windows. Aby znaleźć tożsamość aplikacji, wyszukaj ją i wybierz. Naciśnij przycisk Wybierz.

7. Sprawdź, czy tożsamość zarządzana lub tożsamość aplikacji jest wyświetlana w obszarze Członkowie. Wybierz Dalej.

8. Wybierz pozycję Przegląd i przypisz aby dodać przypisanie roli do konta storage.

Dodawanie tożsamości zarządzanej przypisanej przez użytkownika do maszyny wirtualnej

Jeśli utworzono tożsamość zarządzaną przypisaną przez użytkownika, wykonaj następujące kroki, aby dodać ją do maszyny wirtualnej:

1. Przejdź do maszyny wirtualnej. W menu usługi w obszarze Zabezpieczenia wybierz pozycję Tożsamość.

2. Wybierz kartę Użytkownik przypisany, a następnie wybierz pozycję Dodaj zarządzaną tożsamość przypisaną użytkownikowi. Wybierz utworzoną tożsamość zarządzaną, a następnie wybierz pozycję Dodaj.

Aby skonfigurować tożsamość zarządzaną na maszynie wirtualnej z systemem Linux uruchomionej w Azure, wykonaj następujące kroki. Maszyna wirtualna musi działać Azure Linux 3.0, Ubuntu 22.04, Ubuntu 24.04, RHEL 9.6 lub SLES 15 SP6+.

Włącz tożsamość zarządzaną na maszynie wirtualnej Azure

Tożsamość zarządzana może być przypisana przez system lub przypisana przez użytkownika. Jeśli maszyna wirtualna ma tożsamości zarządzane przypisane przez system i przypisane przez użytkownika, Azure domyślnie wybiera tożsamości przypisane przez system. Przypisz tylko jeden, aby uzyskać najlepsze wyniki.

Włącz tożsamość zarządzaną przypisaną przez system

1. Zaloguj się do portalu Azure.

2. Tożsamość zarządzaną przypisaną przez system można włączyć podczas tworzenia maszyny wirtualnej na karcie Management. Zobacz Utwórz maszynę wirtualną z systemem Linux w portalu Azure.

   

Włącz tożsamość zarządzaną przypisaną przez użytkownika

1. Zaloguj się do portalu Azure i wykonaj kroki, aby utwórz tożsamość zarządzaną przypisaną przez użytkownika.

2. Przejdź do właśnie utworzonej tożsamości zarządzanej przypisanej przez użytkownika i skopiuj wartość Identyfikator klienta . Ta wartość będzie potrzebna później.

Przypisywanie wbudowanej roli RBAC do tożsamości zarządzanej

1. Przejdź do konta storage zawierającego udział plików, który chcesz zainstalować przy użyciu tożsamości zarządzanej. W menu usługi wybierz pozycję Access Control (IAM).

2. W sekcji Przyznaj dostęp do tego zasobu wybierz Dodaj przypisanie do roli.

3. Na karcie Rola w obszarze Role funkcji zadania wyszukaj i wybierz Storage File Data SMB MI Admin. Następnie wybierz Dalej.

4. Na karcie Members w obszarze Przypisz dostęp do wybierz pozycję Zarządzana tożsamość.

5. W obszarze Członkowie wybierz pozycję + Wybierz członków. Zostanie wyświetlone okienko Wybierz tożsamości zarządzane .

6. W obszarze Tożsamość zarządzana wybierz tożsamość zarządzaną, a następnie wybierz pozycję Wybierz.

7. Sprawdź, czy tożsamość zarządzana znajduje się na liście Członkowie. Wybierz Dalej.

8. Wybierz pozycję Przegląd i przypisz aby dodać przypisanie roli do konta storage.

Dodawanie tożsamości zarządzanej przypisanej przez użytkownika do maszyny wirtualnej

Jeśli utworzono tożsamość zarządzaną przypisaną przez użytkownika, wykonaj następujące kroki, aby dodać ją do maszyny wirtualnej:

1. Przejdź do maszyny wirtualnej. W menu usługi w obszarze Zabezpieczenia wybierz pozycję Tożsamość.

2. Wybierz kartę Użytkownik przypisany, a następnie wybierz pozycję Dodaj zarządzaną tożsamość przypisaną użytkownikowi. Wybierz utworzoną tożsamość zarządzaną, a następnie wybierz pozycję Dodaj.

Aby przygotować swoją maszynę wirtualną lub urządzenie Windows do uwierzytelniania za pomocą tożsamości zarządzanej, upewnij się, że klient nie jest powiązany z domeną i postępuj zgodnie z tymi krokami.

1. Zaloguj się do maszyny wirtualnej lub urządzenia z przypisaną tożsamością zarządzaną i otwórz okno programu PowerShell jako administrator. Potrzebujesz programu PowerShell 5.1 lub nowszego lub programu PowerShell 7 lub nowszego.

2. Zainstaluj moduł programu PowerShell Azure Files SMB Managed Identity Client i zaimportuj go:

   Install-Module AzFilesSmbMIClient 
   Import-Module AzFilesSmbMIClient 
   

3. Sprawdź bieżące zasady wykonywania programu PowerShell, uruchamiając następujące polecenie:

   Get-ExecutionPolicy -List 
   

   Jeśli polityka wykonywania w systemie CurrentUser to Restricted lub Undefined, zmień ją na RemoteSigned. Jeśli zasady wykonywania to RemoteSigned, , DefaultAllSigned, Bypasslub Unrestricted, możesz pominąć ten krok.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
   

Odświeżanie poświadczeń uwierzytelniania

Przed zainstalowaniem udziału plików przy użyciu tożsamości zarządzanej odśwież poświadczenia uwierzytelniania i określ punkt końcowy konta storage. Aby skopiować identyfikator URI konta magazynu, przejdź do konta magazynu w portalu Azure, a następnie wybierz pozycję Ustawienia>Punkty końcowe z menu usługi. Pamiętaj, aby skopiować cały identyfikator URI, w tym ukośnik końcowy: https://<storage-account-name>.file.core.windows.net/.

W przypadku tożsamości zarządzanej przypisanej przez system uruchom następujące polecenie, aby uzyskać token OAuth, wstawić go do pamięci podręcznej Protokołu Kerberos i automatycznie odświeżyć, gdy token jest bliski wygaśnięcia. Opcjonalnie można pominąć refresh.

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

W przypadku tożsamości zarządzanej przypisanej przez użytkownika należy określić identyfikator klienta. Zastąp <client-id> identyfikatorem klienta tożsamości zarządzanej.

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

Aby przygotować maszynę wirtualną z systemem Linux do uwierzytelniania przy użyciu tożsamości zarządzanej, wykonaj następujące kroki.

Pobieranie i instalowanie pakietów uwierzytelniania

Kroki lokalizacji i instalacji pakietu różnią się w zależności od dystrybucji systemu Linux.

Azure Linux 3.0

Uruchom następujące polecenia, aby zainstalować azfilesauth w systemie Azure Linux 3.0:

sudo tdnf update 
sudo tdnf install azfilesauth

RHEL 9.6+

Uruchom następujące polecenia, aby zainstalować azfilesauth na 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
sudo dnf update
sudo dnf install -y azfilesauth

Czasami system RHEL może zablokować dostęp jądra upcall do pliku pamięci podręcznej poświadczeń. Jeśli wystąpi awaria, zobacz potencjalne przyczyny w /var/log/messages.

System RHEL domyślnie używa trwałych poświadczeń lub pamięci podręcznej KCM. Możesz przełączyć się do pamięci podręcznej opartej na plikach dla programu 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+

Uruchom następujące polecenia, aby zainstalować azfilesauth na systemie 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

System SLES 15 SP6+ domyślnie używa trwałych poświadczeń lub pamięci podręcznej KCM. Możesz przełączyć się do pamięci podręcznej opartej na plikach dla programu 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

Uruchom następujące polecenia, aby zainstalować azfilesauth w systemie 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

Uruchom następujące polecenia, aby zainstalować azfilesauth na 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

Konfigurowanie uwierzytelniania tożsamości zarządzanej

Dostępne są dwie opcje konfigurowania uwierzytelniania w systemie Linux:

• Użyj tożsamości zarządzanej maszyny wirtualnej: wybierz tę opcję, jeśli maszyna wirtualna ma przypisaną tożsamość zarządzaną.
• Podaj token OAuth bezpośrednio: wybierz tę opcję, jeśli samodzielnie zarządzasz tokenami OAuth.

Opcja 1. Używanie tożsamości zarządzanej maszyny wirtualnej

Do skonfigurowania uwierzytelniania można użyć tożsamości zarządzanej przypisanej przez system lub przypisanej przez użytkownika.

Jeśli maszyna wirtualna ma tożsamość zarządzaną przypisaną przez użytkownika, uruchom następujące polecenie, aby pobrać token z usługi Azure Instance Metadata Service (IMDS) i zapisać go automatycznie. Zastąp <storage-account-name> nazwą konta magazynowego. Zastąp znacznik <client-id> identyfikatorem klienta tożsamości zarządzanej. Jeśli nie masz identyfikatora klienta, przejdź do tożsamości zarządzanej w portalu Azure i skopiuj identyfikator klienta.

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

Jeśli maszyna wirtualna ma tożsamość zarządzaną przypisaną przez system, użyj --system flagi i nie podaj identyfikatora klienta:

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

Sprawdź, czy bilet został prawidłowo utworzony:

sudo azfilesauthmanager list

Opcja 2. Bezpośrednie podanie tokenu OAuth

Jeśli samodzielnie zarządzasz tokenami, podaj token OAuth bezpośrednio. Wartość aud (odbiorcy) tokenu musi być https://storage.azure.com (bez ukośnika końcowego) i nie https://storage.azure.com/, aby zainstalować udział plików.

Uruchom następujące polecenia. Zastąp <storage-account-name> i <access-token> wartościami.

# 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

Na komputerach z systemem Windows możesz uzyskać bezpośredni dostęp do udziału plików Azure przy użyciu ścieżki UNC, wprowadzając następującą ścieżkę do Eksploratora plików Windows. Zastąp <storage-account-name> nazwą konta storage i <file-share-name> nazwą udziału plików.

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

Aby uzyskać więcej informacji, zobacz Mount SMB Azure udział plików w Windows.

Uruchom następujące polecenie, aby zamontować zasób plików z zalecanymi opcjami montowania. Zastąp <storage-account-name> nazwą konta storage i <file-share-name> nazwą udziału plików. Identyfikator poświadczeń można znaleźć w następującym pliku konfiguracji: cat /etc/azfilesauth/config.yaml. W przypadku tożsamości zarządzanej przypisanej przez użytkownika dołącz identyfikator klienta tożsamości zarządzanej, używając opcji montowania username=<client-id>. W przypadku tożsamości zarządzanej przypisanej przez system pomiń opcję username=<client-id> montowania.

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

Sprawdź, czy montowanie zakończyło się pomyślnie:

ls -la /mnt/smb

Aby uzyskać więcej informacji, zobacz Mount SMB Azure file shares on Linux clients.

Odświeżanie poświadczeń

Aby zapobiec przerwom w dostępie, okresowo odświeżaj dane uwierzytelniające. Usługa odświeżania automatycznie wykrywa i odnawia poświadczenia zgodnie z potrzebami.

Po zainstalowaniu udziału plików po raz pierwszy uruchom usługę odświeżania:

sudo systemctl start azfilesrefresh

Aby upewnić się, że usługa jest uruchamiana automatycznie przy każdym rozruchu:

sudo systemctl enable --now azfilesrefresh

Automatyczne odświeżanie poświadczeń wymaga tożsamości zarządzanej przypisanej do maszyny wirtualnej. Jeśli dostarczasz token OAuth bezpośrednio, musisz odświeżyć poświadczenia ręcznie, używając polecenia opisanego azfilesauthmanager set w Configure managed identity authentication lub programatycznie za pomocą API współdzielonej biblioteki.

Jeśli podczas instalowania zasobu sieciowego na systemie Windows wystąpią problemy, wykonaj następujące kroki, aby włączyć szczegółowe rejestrowanie i zebrać informacje diagnostyczne:

1. Na klientach Windows użyj Edytora rejestru, aby ustawić poziom Data dla verbosity0x00000004 (4) dla Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\Storage\Files\SmbAuth.

2. Spróbuj ponownie zainstalować udział i odtwórz błąd.

3. Teraz powinien istnieć plik o nazwie AzFilesSmbMILog.log. Wyślij plik dziennika do zespołu Azure Files w celu uzyskania pomocy.

Jeśli podczas montowania udziału plików w systemie Linux wystąpią problemy, wykonaj te kroki diagnostyczne dla protokołu SMB.

W przypadku deweloperów, którzy muszą zintegrować tożsamości zarządzane z aplikacjami Windows, dostępnych jest wiele metod implementacji. Wybrane podejście zależy od architektury i wymagań aplikacji.

Integracja zestawu zarządzanego: pakiet NuGet

W przypadku aplikacji .NET pakiet NuGet Microsoft.Azure.AzFilesSmbMI zawiera zestaw zarządzany (Microsoft.Azure.AzFilesSmbMI.dll), który zapewnia bezpośredni dostęp do funkcji uwierzytelniania OAuth dla protokołu SMB. Użyj tego podejścia dla języka C# i innych aplikacji opartych na .NET.

Aby zainstalować zestaw, użyj Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94.

Natywna integracja bibliotek DLL

W przypadku aplikacji natywnych, które wymagają bezpośredniego dostępu do interfejsu API, AzFilesSmbMIClient jest dostępna jako native DLL. Ta opcja jest szczególnie przydatna w przypadku aplikacji lub systemów C/C++, które wymagają integracji niższego poziomu. Zobacz implementację Windows i dokumentację API (natywny plik nagłówka).

Metody natywnego interfejsu API

Natywna biblioteka DLL eksportuje następujące podstawowe metody zarządzania poświadczeniami:

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

Deweloperzy systemu Linux mogą używać biblioteki udostępnionej, która jest automatycznie instalowana z pakietem azfilesauth . Możesz łączyć się z biblioteką w aplikacjach C/C++, aby uzyskać bezpośredni dostęp do interfejsu API.

Pamiętaj, aby uwzględnić nagłówek public.

Aby uzyskać więcej informacji, zobacz projekt AzFilesAuthenticator.

Metody interfejsu API wspólnej biblioteki

Biblioteka udostępniona eksportuje następujące podstawowe metody zarządzania poświadczeniami:

#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

Opis interfejsu API

W poniższej tabeli wymieniono polecenia interfejsu API i ich użycie. Zwracane wartości są zgodne ze standardowymi konwencjami języka C (zero dla powodzenia, nonzero w przypadku błędów).