Доступ к общим папкам SMB Azure с помощью управляемых удостоверений с Microsoft Entra ID

Описанные здесь шаги включения предназначены для Azure виртуальных машин. Если вы хотите включить управляемое удостоверение на компьютерах, не являющихся Azure Windows (локально или в другом облаке), необходимо подключить их к Azure Arc и назначить управляемое удостоверение. Вы также можете пройти проверку подлинности с помощью удостоверения приложения, а не с помощью управляемого удостоверения на виртуальной машине или на устройстве Windows.

Включение управляемого удостоверения на виртуальной машине Azure

Управляемое удостоверение может быть назначено системой или назначаемое пользователем. Если у виртуальной машины есть как управляемые удостоверения, назначенные системой, так и назначенные пользователем, Azure по умолчанию использует назначенные системой удостоверения. Назначьте только один для наилучших результатов.

Включить управляемое удостоверение, назначенное системой

Выполните следующие действия, чтобы включить управляемое удостоверение, назначаемое системой, на виртуальной машине Windows, работающей в Azure:

1. Войдите на портал Azure и создайте виртуальную машину Windows. Виртуальная машина должна запускаться Windows Server 2019 или более поздней для версий сервера или любой версии клиента Windows. См. раздел Создание виртуальной машины Windows в портале Azure.

2. Во время создания виртуальной машины на вкладке "Управление " можно включить управляемое удостоверение, назначаемое системой.

   

Включить управляемое удостоверение личности, назначаемое пользователем

1. Войдите на портал Azure и выполните действия, чтобы создать управляемое удостоверение, назначаемое пользователем.

2. Перейдите к управляемому удостоверению, назначенному пользователем, которое вы только что создали, и скопируйте значение идентификатора клиента. Это значение понадобится позже.

Назначьте встроенную роль RBAC для управляемого удостоверения или удостоверения приложения

После того как вы включите управляемое удостоверение, предоставьте все необходимые разрешения через Azure RBAC. Чтобы назначить роли, войдите как пользователь с правами записи на назначение ролей в необходимой области.

Выполните следующие действия, чтобы назначить встроенную роль Azure RBAC Storage File Data SMB MI Admin. Эта роль предоставляет доступ на уровне администратора для управляемых удостоверений в файлах и каталогах в Файлы Azure.

1. Перейдите к учетной записи storage, содержащей общую папку, которую вы хотите подключить с помощью управляемого удостоверения. В меню службы выберите контроль доступа (IAM).

2. В разделе Предоставить доступ к этому ресурсу выберите Добавить назначение роли.

3. На вкладке "Роль" в разделе "Роли по функциям работы" найдите и выберите Storage File Data SMB MI Admin. Затем выберите "Далее".

4. На вкладке Members в разделе Назначьте доступ к выберите Управляемая идентичность для удостоверений виртуальной машины или Azure Arc. Для удостоверений приложений выберите «Пользователь», «Группа» или «Уполномоченный сервис».

5. В разделе "Участники" выберите +Выбрать участников.

6. Для удостоверений Azure ВМ или Azure Arc выберите управляемое удостоверение для вашей виртуальной машины или устройства Windows. Для удостоверений приложения найдите и выберите соответствующее удостоверение. Нажмите кнопку "Выбрать".

7. Убедитесь, что управляемое удостоверение или удостоверение приложения указано в разделе Members. Нажмите кнопку Далее.

8. Выберите Review + assign, чтобы добавить назначение роли в учетную запись хранилища.

Добавьте управляемую идентичность, назначенную пользователем, на виртуальную машину

Если вы создали управляемое удостоверение, назначаемое пользователем, выполните следующие действия, чтобы добавить его в виртуальную машину:

1. Перейдите на виртуальную машину. В меню службы в разделе "Безопасность" выберите "Удостоверение".

2. Выберите вкладку «Назначенный пользователем» и выберите «Добавить назначенную пользователем управляемую идентичность». Выберите созданное управляемое удостоверение и нажмите кнопку "Добавить".

Чтобы настроить управляемое удостоверение на виртуальной машине Linux, работающей в Azure, выполните следующие действия. Виртуальная машина должна работать Azure Linux 3.0, Ubuntu 22.04, Ubuntu 24.04, RHEL 9.6+ или SLES 15 с пакетом обновления 6 (SP6).

Включение управляемого удостоверения на виртуальной машине Azure

Управляемое удостоверение может быть назначено системой или назначаемое пользователем. Если у виртуальной машины есть как управляемые удостоверения, назначенные системой, так и назначенные пользователем, Azure по умолчанию использует назначенные системой удостоверения. Назначьте только один для наилучших результатов.

Включить управляемое удостоверение, назначенное системой

1. Войдите на портал Azure.

2. Управляемую идентификацию, назначаемую системой, можно включить во время создания виртуальной машины на вкладке Management. См. раздел Создание виртуальной машины Linux на портале Azure.

   

Включить управляемое удостоверение личности, назначаемое пользователем

1. Войдите на портал Azure и выполните действия, чтобы создать управляемое удостоверение, назначаемое пользователем.

2. Перейдите к управляемому удостоверению, назначенному пользователем, которое вы только что создали, и скопируйте значение идентификатора клиента. Это значение понадобится позже.

Назначьте встроенную роль RBAC управляемому удостоверению

1. Перейдите к учетной записи storage, содержащей общую папку, которую вы хотите подключить с помощью управляемого удостоверения. В меню службы выберите контроль доступа (IAM).

2. В разделе Предоставить доступ к этому ресурсу выберите Добавить назначение роли.

3. На вкладке "Роль" в разделе "Роли по функциям работы" найдите и выберите Storage File Data SMB MI Admin. Затем выберите "Далее".

4. На вкладке Members в разделе Assign access to выберите Managed identity.

5. В разделе "Участники" выберите +Выбрать участников. Откроется панель "Выбор управляемых удостоверений ".

6. В разделе "Управляемое удостоверение" выберите управляемое удостоверение и нажмите кнопку "Выбрать".

7. Убедитесь, что управляемое удостоверение отображается в разделе "Участники". Нажмите кнопку Далее.

8. Выберите Review + assign, чтобы добавить назначение роли в учетную запись хранилища.

Добавьте управляемую идентичность, назначенную пользователем, на виртуальную машину

Если вы создали управляемое удостоверение, назначаемое пользователем, выполните следующие действия, чтобы добавить его в виртуальную машину:

1. Перейдите на виртуальную машину. В меню службы в разделе "Безопасность" выберите "Удостоверение".

2. Выберите вкладку «Назначенный пользователем» и выберите «Добавить назначенную пользователем управляемую идентичность». Выберите созданное управляемое удостоверение и нажмите кнопку "Добавить".

Чтобы подготовить виртуальную машину клиента или устройство Windows для проверки подлинности с помощью управляемого удостоверения, выполните следующие действия.

1. Войдите на виртуальную машину или устройство с назначенным управляемым удостоверением и откройте окно PowerShell от имени администратора. Вам потребуется PowerShell 5.1+ или PowerShell 7+.

2. Установите модуль PowerShell Файлы Azure SMB Managed Identity Client и импортируйте его.

   Install-Module AzFilesSmbMIClient 
   Import-Module AzFilesSmbMIClient 
   

3. Проверьте текущую политику выполнения PowerShell, выполнив следующую команду:

   Get-ExecutionPolicy -List 
   

   Если политика выполнения на CurrentUser является Restricted или Undefined, измените её на RemoteSigned. Если политика выполнения имеет RemoteSignedзначение , Defaultили AllSignedBypassUnrestricted, можно пропустить этот шаг.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
   

Обновите учетные данные аутентификации

Прежде чем подключить файловый ресурс с помощью управляемого удостоверения, обновите учетные данные проверки подлинности и укажите конечную точку учетной записи хранилища. Чтобы скопировать URI учетной записи хранения, перейдите к учетной записи хранения на портале Azure и выберите Settings< >c2>Endpoints в меню службы. Обязательно скопируйте весь идентификатор ресурса (URI), включая завершающий слеш: https://<storage-account-name>.file.core.windows.net/.

Для управляемого удостоверения, назначаемого системой, выполните следующую команду, чтобы получить маркер OAuth, вставьте его в кэш Kerberos и автоматически обновите, когда маркер близок к истечению срока действия. При необходимости можно опустить refresh.

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

Для управляемого удостоверения, назначаемого пользователем, необходимо указать идентификатор клиента. Замените <client-id> идентификатором клиента управляемого удостоверения.

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

Чтобы подготовить виртуальную машину Linux для проверки подлинности с помощью управляемого удостоверения, выполните следующие действия.

Скачивание и установка пакетов проверки подлинности

Расположение пакета и этапы установки отличаются в зависимости от дистрибутива Linux.

Azure Linux 3.0

Выполните следующие команды, чтобы установить azfilesauth на Azure Linux 3.0:

tdnf update 
tdnf install azfilesauth

RHEL 9.6+

Выполните следующие команды, чтобы установить azfilesauth на 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

Иногда RHEL может блокировать доступ кэш-файла учетных данных для вызовов ядра. В случае сбоя обратитесь к /var/log/messages для ознакомления с потенциальными причинами.

RHEL использует постоянные учетные данные или кэш KCM по умолчанию. Вы можете переключиться в файловый кэш для azfilesauth:

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

SLES 15 с пакетом обновления 6 (SP6)

Выполните следующие команды, чтобы установить azfilesauth на SLES 15 с пакетом обновления 6 и выше (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+ по умолчанию использует персистентные данные учетных записей или кэш KCM. Вы можете переключиться в файловый кэш для 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

Выполните следующие команды, чтобы установить azfilesauth в 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

Выполните следующие команды, чтобы установить azfilesauth в 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

Настройка проверки подлинности

Существует два варианта настройки проверки подлинности в Linux:

• Используйте управляемое удостоверение виртуальной машины: выберите этот параметр, если у виртуальной машины назначено управляемое удостоверение.
• Укажите маркер OAuth напрямую: выберите этот параметр, если вы самостоятельно управляете маркерами OAuth.

Вариант 1: Использование управляемого удостоверения виртуальной машины

Для настройки проверки подлинности можно использовать назначаемое системой или назначаемое пользователем управляемое удостоверение.

Если у виртуальной машины есть управляемое удостоверение, назначаемое пользователем, выполните следующую команду, чтобы получить маркер из службы метаданных экземпляра Azure (IMDS) и сохранить его автоматически. Замените <storage-account-name> на имя вашей учетной записи хранения. Замените <client-id> на ID клиента управляемого удостоверения. Если у вас нет идентификатора клиента, перейдите к управляемому удостоверению на портале Azure и скопируйте идентификатор клиента.

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

Если у виртуальной машины есть управляемое удостоверение, назначаемое системой, используйте --system флаг и не укажите идентификатор клиента:

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

Убедитесь, что билет был создан правильно:

sudo azfilesauthmanager list

Вариант 2. Предоставление маркера OAuth напрямую

Если вы управляете маркерами самостоятельно, укажите маркер OAuth напрямую. Значение aud (аудитория) для маркера должно быть https://storage.azure.com (без косой черты вперед) и не https://storage.azure.com/ для подключения общей папки.

Выполните указанные ниже команды. Замените <storage-account-name> и <access-token> значениями.

# 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

На Windows клиентах вы можете напрямую получить доступ к общей папке Azure с помощью пути UNC, введя следующий путь в Windows проводнике. Замените <storage-account-name> именем учетной записи storage и <file-share-name> именем общей папки.

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

Дополнительные сведения см. в разделе Подключение файлового ресурса Azure SMB в Windows.

Выполните следующую команду, чтобы подключить общую папку с рекомендуемыми параметрами подключения. Замените <storage-account-name> именем учетной записи storage и <file-share-name> именем общей папки. Идентификатор учетных данных можно найти в следующем файле конфигурации: cat /etc/azfilesauth/config.yaml Для управляемого удостоверения, назначенного пользователем, добавьте идентификатор клиента этого удостоверения, используя параметр подключения username=<client-id>. Для управляемого удостоверения, назначаемого системой, опустите параметр 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

Убедитесь, что монтирование выполнено успешно:

ls -la /mnt/smb

Дополнительные сведения см. в статье Подключение SMB Azure файловых хранилищ на клиентах Linux.

Обновление учетных данных

Чтобы предотвратить прерывание доступа, следует периодически обновлять учетные данные. Служба обновления автоматически обнаруживает и обновляет учетные данные по мере необходимости.

После первого подключения общей папки запустите службу обновления:

sudo systemctl start azfilesrefresh

Чтобы убедиться, что служба запускается автоматически при каждой загрузке:

sudo systemctl enable --now azfilesrefresh

Для автоматического обновления учетных данных требуется управляемое удостоверение, назначенное виртуальной машине. Если вы предоставляете маркер OAuth напрямую, необходимо вручную обновить учетные данные с помощью azfilesauthmanager set команды, как описано в разделе "Настройка проверки подлинности" или программно через API общей библиотеки.

Если при подключении общей папки к Windows возникают проблемы, выполните следующие действия, чтобы включить подробное ведение журнала и собрать диагностические сведения:

1. На клиентах Windows используйте редактор реестра, чтобы установить уровень Data для verbosity на 0x00000004 (4) для Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Майкрософт\Windows Azure\Storage\Files\SmbAuth.

2. Повторите попытку подключения общего ресурса и воспроизведите ошибку.

3. Теперь у вас должен быть файл с именем AzFilesSmbMILog.log. Отправьте файл журнала в команду Файлы Azure для получения помощи.

Если при подключении общей папки в Linux возникают проблемы, выполните следующие шаги диагностики SMB.

Для разработчиков, которым необходимо интегрировать управляемые идентификаторы в их Windows приложения, существует несколько подходов к их реализации. Выбранный подход зависит от архитектуры и требований приложения.

Интеграция управляемой сборки: пакет NuGet

Для приложений .NET Майкрософт.Azure. AzFilesSmbMI пакет NuGet включает управляемую сборку (Майкрософт.Azure.AzFilesSmbMI.dll), которая обеспечивает прямой доступ к функциям проверки подлинности OAuth SMB. Используйте этот подход для C# и других приложений на основе .NET.

Чтобы установить сборку, используйте Install-Package Майкрософт.Azure.AzFilesSmbMI -version 1.2.3168.94.

Интеграция с родной библиотекой DLL

Для собственных приложений, которым требуется прямой доступ к API, AzFilesSmbMIClient доступен в виде библиотеки DLL native DLL. Этот параметр особенно полезен для приложений или систем C++, которым требуется интеграция с более низким уровнем. См. документацию по реализации Windows и API (нативный заголовочный файл).

Собственные методы API

Собственная библиотека DLL экспортирует следующие основные методы для управления учетными данными:

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 могут использовать общую библиотеку, которая автоматически установлена с пакетом azfilesauth . Вы можете подключаться к библиотеке в ваших приложениях C/C++ для прямого доступа к API.

Обязательно включите заголовок public.

Дополнительные сведения см. в проекте AzFilesAuthenticator.

Методы API общей библиотеки

Общая библиотека экспортирует следующие основные методы для управления учетными данными:

#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

В следующей таблице перечислены команды API и их использование. Возвращаемые значения соответствуют стандартным соглашениям C (ноль для успешного выполнения, ненулевые значения для ошибок).