Acceso a recursos compartidos de archivos Azure SMB mediante identidades administradas con Microsoft Entra ID

Los pasos de habilitación que se describen aquí son para Azure máquinas virtuales. Si desea habilitar una identidad administrada en máquinas Windows que no son de Azure (locales u otras plataformas en la nube), debe incorporarlas a Azure Arc y asignar una identidad administrada. También puede autenticarse mediante la identidad de una aplicación en lugar de usar una identidad administrada en una máquina virtual o en un dispositivo Windows.

Habilitación de una identidad administrada en una máquina virtual de Azure

La identidad administrada puede ser asignada por el sistema o por el usuario. Si la máquina virtual tiene tanto identidades administradas asignadas por el sistema como asignadas por el usuario, Azure da prioridad de forma predeterminada a las asignadas por el sistema. Asigne solo uno para obtener los mejores resultados.

Habilitación de una identidad administrada asignada por el sistema.

Siga estos pasos para habilitar una identidad administrada asignada por el sistema en una máquina virtual de Windows que se ejecuta en Azure:

1. Inicie sesión en el portal de Azure y cree una máquina virtual de Windows. La máquina virtual debe ejecutar Windows Server 2019 o posterior para las versiones de servidor, o cualquier versión de cliente Windows. Consulte Crear una máquina virtual Windows en el portal de Azure.

2. Puede habilitar una identidad administrada asignada por el sistema durante la creación de la máquina virtual en la pestaña Administración .

   

Habilitación de una identidad administrada asignada por el usuario.

1. Inicie sesión en el portal de Azure y siga los pasos para crear una identidad administrada asignada por el usuario.

2. Vaya a la identidad administrada asignada por el usuario que acaba de crear y copie el valor del ID de cliente. Necesitarás este valor más adelante.

Asignación de un rol RBAC integrado a la identidad administrada o a la identidad de aplicación

Después de habilitar una identidad administrada, conceda todos los permisos necesarios a través de Azure RBAC. Para asignar roles, inicie sesión como usuario con permiso de escritura para la asignación de roles en el ámbito necesario.

Siga estos pasos para asignar el rol Azure RBAC integrado Storage File Data SMB MI Admin. Este rol proporciona acceso de nivel de administrador para identidades administradas en archivos y directorios de Azure Files.

1. Vaya a la cuenta de almacenamiento que contiene el recurso compartido de archivos que desea montar mediante una identidad administrada. En el menú servicio, seleccione Access Control (IAM).

2. En Conceder el acceso a este recurso, seleccione Agregar asignación de rol.

3. En la pestaña Rol, en Roles de función de trabajo, busque y seleccione Administrador de MI SMB de datos de archivos de almacenamiento. A continuación, seleccione Siguiente.

4. En la pestaña Members, en Assign access to, seleccione Managed identity for VM or Azure Arc identities. En Identidades de aplicación, seleccione Usuario, grupo o entidad de servicio.

5. En Miembros, seleccione + Seleccionar miembros.

6. Para máquinas virtuales de Azure o identidades de Azure Arc, seleccione la identidad administrada para su máquina virtual o dispositivo Windows. Para identidades de aplicación, busque y seleccione la identidad de la aplicación. Elija Seleccione.

7. Compruebe que la identidad administrada o la identidad de la aplicación se muestran en Miembros. Seleccione Siguiente.

8. Seleccione Review + assign para agregar la asignación de roles a la cuenta de storage.

Adición de una identidad administrada asignada por el usuario a una máquina virtual

Si creó una identidad administrada asignada por el usuario, siga estos pasos para agregarla a la máquina virtual:

1. Vaya a la máquina virtual. En el menú servicio, en Seguridad, seleccione Identidad.

2. Seleccione la pestaña User assigned (Usuario asignado) y, a continuación, seleccione Add user assigned managed identity (Agregar identidad administrada asignada por el usuario). Seleccione la identidad administrada que creó y, a continuación, seleccione Agregar.

Para configurar una identidad administrada en una máquina virtual Linux que se ejecuta en Azure, siga estos pasos. La máquina virtual debe ejecutar Azure Linux 3.0, Ubuntu 22.04, Ubuntu 24.04, RHEL 9.6 y versiones posteriores o SLES 15 SP6+.

Habilitación de una identidad administrada en una máquina virtual de Azure

La identidad administrada puede ser asignada por el sistema o por el usuario. Si la máquina virtual tiene tanto identidades administradas asignadas por el sistema como asignadas por el usuario, Azure da prioridad de forma predeterminada a las asignadas por el sistema. Asigne solo uno para obtener los mejores resultados.

Habilitación de una identidad administrada asignada por el sistema.

1. Inicie sesión en el portal de Azure.

2. Puede habilitar una identidad administrada asignada por el sistema durante la creación de la máquina virtual en la pestaña Management. Consulte Crear una máquina virtual Linux en el portal de Azure.

   

Habilitación de una identidad administrada asignada por el usuario.

1. Inicie sesión en el portal de Azure y siga los pasos para crear una identidad administrada asignada por el usuario.

2. Vaya a la identidad administrada asignada por el usuario que acaba de crear y copie el valor del ID de cliente. Necesitarás este valor más adelante.

Asignar un rol RBAC integrado a la identidad administrada

1. Vaya a la cuenta de almacenamiento que contiene el recurso compartido de archivos que desea montar mediante una identidad administrada. En el menú servicio, seleccione Access Control (IAM).

2. En Conceder el acceso a este recurso, seleccione Agregar asignación de rol.

3. En la pestaña Rol, en Roles de función de trabajo, busque y seleccione Administrador de MI SMB de datos de archivos de almacenamiento. A continuación, seleccione Siguiente.

4. En la pestaña Members, en Assign access to, seleccione Administrar identidad.

5. En Miembros, seleccione + Seleccionar miembros. Aparece el panel Seleccionar identidades administradas .

6. En Identidad administrada, seleccione la identidad administrada y, a continuación, elija Seleccionar.

7. Compruebe que la identidad administrada aparece en Miembros. Seleccione Siguiente.

8. Seleccione Review + assign para agregar la asignación de roles a la cuenta de storage.

Adición de una identidad administrada asignada por el usuario a una máquina virtual

Si creó una identidad administrada asignada por el usuario, siga estos pasos para agregarla a la máquina virtual:

1. Vaya a la máquina virtual. En el menú servicio, en Seguridad, seleccione Identidad.

2. Seleccione la pestaña User assigned (Usuario asignado) y, a continuación, seleccione Add user assigned managed identity (Agregar identidad administrada asignada por el usuario). Seleccione la identidad administrada que creó y, a continuación, seleccione Agregar.

Para preparar la máquina virtual cliente o Windows dispositivo para autenticarse mediante una identidad administrada, siga estos pasos:

1. Inicie sesión en la máquina virtual o dispositivo que tenga asignada la identidad administrada y abra una ventana de PowerShell como administrador. Necesita PowerShell 5.1 o PowerShell 7 y versiones posteriores.

2. Instale el módulo Azure Files SMB Managed Identity Client powerShell e impórtelo:

   Install-Module AzFilesSmbMIClient 
   Import-Module AzFilesSmbMIClient 
   

3. Ejecute el siguiente comando para comprobar la directiva de ejecución de PowerShell actual:

   Get-ExecutionPolicy -List 
   

   Si la directiva de ejecución de CurrentUser es Restricted o Undefined, cámbiela a RemoteSigned. Si la directiva de ejecución es RemoteSigned, Default, AllSigned, Bypasso Unrestricted, puede omitir este paso.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
   

Actualización de las credenciales de autenticación

Antes de poder montar el recurso compartido de archivos con la identidad administrada, actualice las credenciales de autenticación y especifique el punto de conexión de su cuenta de almacenamiento. Para copiar el URI de la cuenta de almacenamiento, vaya a la cuenta de almacenamiento en el portal de Azure y seleccione Settings>Endpoints en el menú del servicio. Asegúrese de copiar todo el URI, incluida la barra diagonal final: https://<storage-account-name>.file.core.windows.net/.

Para una identidad administrada asignada por el sistema, ejecute el siguiente comando para obtener un token de OAuth, insertarlo en la caché de Kerberos y actualizar automáticamente cuando el token esté cerca de expirar. Opcionalmente, puede omitir refresh.

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

Para una identidad administrada asignada por el usuario, debe especificar el identificador de cliente. Reemplace por <client-id> el identificador de cliente de la identidad administrada.

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

Para preparar la máquina virtual Linux para autenticarse mediante una identidad administrada, siga estos pasos.

Descarga e instalación de los paquetes de autenticación

La ubicación del paquete y los pasos de instalación difieren en función de la distribución de Linux.

Azure Linux 3.0

Ejecute los siguientes comandos para instalar azfilesauth en Azure Linux 3.0:

tdnf update 
tdnf install azfilesauth

RHEL 9.6+

Ejecute los siguientes comandos para instalar azfilesauth en 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

A veces, RHEL puede bloquear el acceso de invocaciones del kernel al archivo de caché de credenciales. Si se produce un error, consulte /var/log/messages para conocer posibles causas.

RHEL usa una credencial persistente o una caché de KCM de forma predeterminada. Puede utilizar una caché basada en archivos para 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+

Ejecute los siguientes comandos para instalar azfilesauth en 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+ usa una credencial persistente o una caché KCM de forma predeterminada. Puede utilizar una caché basada en archivos para 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

Ejecute los siguientes comandos para instalar azfilesauth en 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

Ejecute los siguientes comandos para instalar azfilesauth en 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

Configurar la autenticación

Tiene dos opciones para configurar la autenticación en Linux:

• Use una identidad administrada de máquina virtual: seleccione esta opción si la máquina virtual tiene asignada una identidad administrada.
• Proporcione directamente el token de OAuth: seleccione esta opción si va a administrar los tokens de OAuth usted mismo.

Opción 1: Uso de una identidad administrada de máquina virtual

Puede usar una identidad administrada asignada por el sistema o asignada por el usuario para configurar la autenticación.

Si la máquina virtual tiene una identidad administrada asignada por el usuario, ejecute el siguiente comando para obtener un token de Azure Instance Metadata Service (IMDS) y almacenarlo automáticamente. Sustituya <storage-account-name> por el nombre de su cuenta de almacenamiento. Reemplaza <client-id> por el ID de cliente de la identidad administrada. Si no tiene el identificador de cliente, vaya a la identidad administrada en el portal de Azure y copie el identificador de cliente.

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

Si la máquina virtual tiene una identidad administrada asignada por el sistema, use la --system marca y no proporcione un identificador de cliente:

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

Compruebe que el vale se haya creado correctamente:

sudo azfilesauthmanager list

Opción 2: Proporcionar el token de OAuth directamente

Si va a administrar tokens usted mismo, proporcione directamente el token de OAuth. El valor aud (audiencia) del token debe ser https://storage.azure.com (sin barra inclinada al final) y no https://storage.azure.com/ para montar el recurso compartido de archivos.

Ejecute los siguientes comandos. Reemplace <storage-account-name> y <access-token> por los valores.

# 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

En clientes Windows, puede acceder directamente a un recurso compartido de archivos de Azure mediante la ruta de acceso UNC introduciendo la siguiente ruta en el Explorador de archivos de Windows. Reemplace <storage-account-name> por el nombre de la cuenta de almacenamiento y <file-share-name> por el nombre del recurso compartido de archivos.

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

Para obtener más información, consulte Montar recurso de archivos SMB de Azure en Windows.

Ejecuta el siguiente comando para montar la compartición de archivos con las opciones de montaje recomendadas. Reemplace <storage-account-name> por el nombre de la cuenta de almacenamiento y <file-share-name> por el nombre del recurso compartido de archivos. Puede encontrar el identificador de credencial en el siguiente archivo de configuración: cat /etc/azfilesauth/config.yaml. Para una identidad administrada asignada por el usuario, incluya el ID de cliente de la identidad administrada usando la opción de montaje username=<client-id>. En una identidad administrada por el sistema, ignore la opción de montaje 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

Compruebe que el montaje se realizó correctamente:

ls -la /mnt/smb

Para obtener más información, consulte Montar comparticiones de archivos de Azure SMB en clientes Linux.

Actualización de las credenciales

Para evitar interrupciones de acceso, debe actualizar las credenciales periódicamente. El servicio de actualización detecta y renueva automáticamente las credenciales según sea necesario.

Después de montar la compartición de archivos por primera vez, inicie el servicio de actualización.

sudo systemctl start azfilesrefresh

Para asegurarse de que el servicio se inicia automáticamente en cada arranque:

sudo systemctl enable --now azfilesrefresh

La actualización automática de credenciales requiere una identidad administrada asignada a la máquina virtual. Si va a proporcionar el token de OAuth directamente, debe actualizar las credenciales manualmente mediante el azfilesauthmanager set comando tal como se describe en Configuración de la autenticación o mediante programación a través de las API de la biblioteca compartida.

Si tiene problemas al montar el recurso compartido de archivos en Windows, siga estos pasos para habilitar el registro detallado y recopilar información de diagnóstico:

1. En Windows clientes, use el Editor del Registro para establecer el nivel Data para verbosity en 0x00000004 (4) para Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\Storage\Files\SmbAuth.

2. Intente montar el recurso compartido de nuevo y reproduzca el error.

3. Ahora debería tener un archivo denominado AzFilesSmbMILog.log. Envíe el archivo de registro al equipo de Azure Files para obtener ayuda.

Si tiene problemas al montar el recurso compartido de archivos en Linux, siga estos pasos de diagnóstico de SMB.

Para los desarrolladores que necesitan integrar identidades administradas en sus aplicaciones de Windows, hay disponibles varios enfoques de implementación. El enfoque que elija depende de la arquitectura y los requisitos de la aplicación.

Integración de ensamblados administrados: paquete NuGet

Para las aplicaciones de .NET, el paquete NuGet Microsoft.Azure.AzFilesSmbMI incluye un ensamblado administrado () que proporciona acceso directo a la funcionalidad de autenticación OAuth de SMB. Use este enfoque para C# y otras aplicaciones basadas en .NET.

Para instalar el ensamblaje, use Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94.

Integración de DLL nativa

En el caso de las aplicaciones nativas que necesitan acceso directo a la API, AzFilesSmbMIClient está disponible como DLL. Esta opción es especialmente útil para aplicaciones o sistemas de C/C++ que necesitan integración de nivel inferior. Consulte la implementación de Windows y la referencia de API (archivo de cabecera nativo).

Métodos de API nativos

El archivo DLL nativo exporta los siguientes métodos principales para la administración de credenciales:

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

Los desarrolladores de Linux pueden usar la biblioteca compartida que se instala automáticamente con el azfilesauth paquete. Puede enlazar contra la biblioteca en sus aplicaciones de C/C++ para acceso directo a la API.

Asegúrese de incluir el encabezado public.

Para obtener más información, consulte el proyecto AzFilesAuthenticator.

Métodos de API de biblioteca compartida

La biblioteca compartida exporta los siguientes métodos principales para la administración de credenciales:

#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

Descripción de API

En la tabla siguiente se enumeran los comandos de API y su uso. Los valores devueltos siguen las convenciones estándar de C (cero para éxito, distinto de cero para los errores).