Acceso a recursos compartidos de archivos de Azure SMB mediante identidades administradas con el identificador de Microsoft Entra (versión preliminar)

Se aplica a: ✔️ Recursos compartidos de archivos Azure SMB

En este artículo se explica cómo puede usar identidades administradas para permitir que las máquinas virtuales (VM) Windows y Linux accedan a recursos compartidos de archivos de Azure SMB mediante la autenticación basada en identidades con el identificador de Microsoft Entra (versión preliminar).

Una identidad administrada es una identidad de Microsoft Entra ID administrada automáticamente por Azure. Normalmente, se usan identidades administradas al desarrollar aplicaciones en la nube para administrar las credenciales para autenticarse en los servicios de Azure.

Al final de esta guía, tendrá una cuenta de almacenamiento lista para acceder a ella con una identidad administrada. También sabrá cómo crear una identidad administrada para una máquina virtual y generar un token de OAuth para ella. A continuación, montará un recurso compartido de archivos mediante la autenticación y autorización basadas en identidades administradas, lo que elimina la necesidad de utilizar una clave de cuenta de almacenamiento.

¿Por qué autenticarse mediante una identidad administrada?

Por motivos de seguridad, no se recomienda usar claves de cuenta de almacenamiento para acceder a un recurso compartido de archivos. Al asignar una identidad administrada a una máquina virtual o usar una identidad de aplicación, puede usar esa identidad para autenticarse en Azure Files.

Entre las ventajas se incluyen:

Seguridad mejorada: Ninguna dependencia de las claves de cuenta de almacenamiento para administrar o exponer
Administración simplificada: No se requiere rotación de claves
Control de acceso específico: Acceso basado en roles en el nivel de identidad
Automatización fácil de usar: Fácil de integrar con canalizaciones de CI/CD, cargas de trabajo de Azure Kubernetes Service (AKS) y aplicaciones de cliente
Rentable en costo: Las identidades administradas pueden utilizarse sin incurrir en costos adicionales de almacenamiento.

Identidades administradas asignadas por el sistema y por el usuario

Hay dos tipos de identidades administradas en Azure: asignadas por el sistema y asignadas por el usuario.

Una identidad administrada asignada por el sistema está restringida a una por recurso y está vinculada al ciclo de vida de este recurso. Puede conceder permisos a la identidad administrada mediante el control de acceso basado en roles de Azure (Azure RBAC). La identidad administrada se autentica con Microsoft Entra ID, por lo que no tiene que almacenar ninguna credencial en el código. Las identidades administradas asignadas por el sistema no se admiten en máquinas virtuales Linux.

Las identidades administradas asignadas por el usuario permiten a los recursos de Azure autenticarse en servicios en la nube sin almacenar credenciales en el código. Este tipo de identidades administradas se crea como un recurso de Azure independiente y tiene su propio ciclo de vida. Un único recurso, como una máquina virtual, puede usar varias identidades administradas asignadas por el usuario. Del mismo modo, se puede compartir una identidad administrada asignada por un solo usuario en varias máquinas virtuales.

Las máquinas virtuales de Windows pueden configurarse con identidades administradas asignadas por el usuario y por el sistema.

Prerrequisitos

En este artículo se da por supuesto que tiene una suscripción de Azure con permisos para crear cuentas de almacenamiento y asignar roles de Azure Role-Based Access Control (RBAC). Para asignar roles, debe tener permiso de escritura de asignaciones de roles (Microsoft.Authorization/roleAssignments/write) en el ámbito en el que desea asignar el rol.

Además, los clientes que necesitan autenticarse mediante una identidad administrada no deben unirse a ningún dominio.

Preparación del entorno de PowerShell

Abra PowerShell como administrador y ejecute el siguiente comando para establecer la directiva de ejecución de PowerShell:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

Asegúrese de que tiene la versión más reciente de PowerShellGet:

Install-Module PowerShellGet -Force -AllowClobber

Instale el módulo Az si aún no está instalado:

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

Inicie sesión en Azure:

Connect-AzAccount

Seleccione la suscripción especificando el identificador de suscripción (recomendado):

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

También puede seleccionar la suscripción especificando el nombre de la suscripción:

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

Configurar la propiedad de acceso de identidad administrada en la cuenta de almacenamiento

Para autenticar una identidad administrada, debe habilitar una propiedad denominada SMBOAuth en la cuenta de almacenamiento que contiene el recurso compartido de archivos de Azure al que desea acceder. Se recomienda crear una nueva cuenta de almacenamiento para este fin. Solo puede usar una cuenta de almacenamiento existente si no tiene ningún otro origen de identidad configurado.

Para crear una cuenta de almacenamiento con SMBOAuth habilitado, ejecute el siguiente comando de PowerShell como administrador. Reemplace <resource-group>, <storage-account-name> y <region> por sus valores. Puede especificar una SKU diferente si es necesario.

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

Para habilitar SMBOAuth en una cuenta de almacenamiento existente, ejecute el siguiente comando de PowerShell. Reemplace <resource-group> y <storage-account-name> con sus valores.

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

Si ve errores que indican que el recurso no está permitido por la directiva, es posible que tenga una directiva establecida en la suscripción que no permita Set-AzStorageAccount. Para solucionarlo, vuelva a intentarlo con el siguiente comando:

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

A continuación, cree un recurso compartido de archivos mediante el protocolo SMB en la cuenta de almacenamiento. Reemplace <resource-group>, <storage-account-name> y <file-share-name> por sus valores.

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

Ahora debería tener una cuenta de almacenamiento y una compartición de archivos listas para la autenticación OAuth de SMB. Compruebe en el portal de Azure que se crearon la cuenta de almacenamiento y el recurso compartido de archivos.

Configuración de una identidad administrada

Puede usar identidades administradas con Windows o Linux. Seleccione la pestaña adecuada y siga las instrucciones del sistema operativo.

Windows
Linux

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

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

Siga estos pasos para habilitar una identidad administrada en una máquina virtual de Azure.

Inicie sesión en Azure Portal y cree una máquina virtual Windows. La máquina virtual debe ejecutar Windows Server 2019 o posterior para las SKU de servidor o cualquier SKU de cliente de Windows. Consulte Creación de una máquina virtual Windows en Azure Portal.
Habilite una identidad administrada en la máquina virtual. Puede ser asignado por el sistema o por el usuario. Si la máquina virtual tiene tanto identidades asignadas por el sistema como por el usuario, Azure usa por defecto la identidad asignada por el sistema. Asigne solo uno para obtener los mejores resultados. Puede habilitar una identidad administrada asignada por el sistema durante la creación de la máquina virtual en la pestaña Administración .

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

Una vez habilitada una identidad administrada, puede conceder todos los permisos necesarios a través de Azure RBAC. Para asignar roles, debe haber iniciado sesión como usuario con permiso de escritura de asignaciones de roles en el ámbito en el que desea asignar el rol.

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

Diríjase a la cuenta de almacenamiento que contiene la compartición de archivos que desea montar mediante una identidad administrada. Seleccione Control de acceso (IAM) en el menú servicio.
En Conceder acceso a este recurso seleccione Agregar asignación de rol.
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 y, a continuación, seleccione Siguiente.
En la pestaña Miembros , en Asignar acceso a, seleccione Identidad administrada para vm o identidades de Azure Arc. En Identidades de aplicación, seleccione Usuario, grupo o entidad de servicio.
En Miembros, haga clic en + Seleccionar miembros.
En El caso de las máquinas virtuales de Azure o las identidades de Azure Arc, seleccione la identidad administrada para la máquina virtual o el dispositivo Windows. Para identidades de aplicación, busque y seleccione la identidad de la aplicación. Haga clic en Seleccionar.
Debería ver ahora la identidad administrada o la identidad de la aplicación listada bajo Miembros. Seleccione Siguiente.
Seleccione Revisar y asignar para agregar la asignación de roles a la cuenta de almacenamiento.

Preparación del cliente para autenticarse mediante una identidad administrada

Siga estos pasos para preparar su sistema para montar la compartición de archivos mediante la autenticación de identidad administrada. Los pasos son diferentes para los clientes de Windows y Linux. Los clientes no deben estar unidos al dominio.

Windows
Linux

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

Inicie sesión en la máquina virtual o dispositivo que tenga asignada la identidad administrada y abra una ventana de PowerShell como administrador. Necesitará PowerShell 5.1 o PowerShell 7 y versiones posteriores.
Instale el módulo PowerShell Azure Files SMB Managed Identity Client e impórtelo:
```
Install-Module AzFilesSMBMIClient 
Import-Module AzFilesSMBMIClient 
```
Ejecute el siguiente comando para comprobar la directiva de ejecución de PowerShell actual:
```
Get-ExecutionPolicy -List 
```
Si la directiva de ejecución en CurrentUser es Restringida o No definida, cámbiela a RemoteSigned. Si la directiva de ejecución es RemoteSigned, Default, AllSigned, Bypass o 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, debe actualizar las credenciales de autenticación y especificar 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 Configuración>Puntos de conexión 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/

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

Esto obtendrá un token de OAuth e lo insertará en la caché de Kerberos y se actualizará automáticamente cuando el token esté cerca de la expiración. Opcionalmente, puede omitir el refresh.

Si la máquina virtual Windows tiene configuradas las identidades administradas asignadas por el usuario y por el sistema, puede usar el siguiente comando para especificar la identidad administrada asignada por el usuario. 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>

Sugerencia

Para ver la información de uso completa y los ejemplos, ejecute el archivo ejecutable sin parámetros: AzFilesSmbMIClient.exe

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

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 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 azfilesauth

Configurar la autenticación

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

Uso de una identidad administrada de máquina virtual: Elija esta opción cuando la máquina virtual tenga asignada una identidad administrada asignada por el usuario.
Proporcione directamente el token de OAuth: elija esta opción si va a administrar tokens de OAuth usted mismo.

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

Si la máquina virtual tiene una identidad administrada asignada por el usuario, ejecute los siguientes comandos. Asegúrese de reemplazar <client-id> por el identificador de cliente de la identidad administrada. Si no tiene el identificador de cliente, vaya a la identidad administrada y copie el identificador de cliente.

# 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

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 y reemplace <storage-account-name> y <access-token> por sus 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

Ahora debería poder montar la compartición de archivos en Windows o Linux sin usar una clave de cuenta de almacenamiento.

Windows
Linux

En los clientes de Windows, puede acceder directamente al recurso compartido de archivos de Azure mediante la ruta de acceso UNC escribiendo lo siguiente en el Explorador de archivos de Windows. Asegúrese de reemplazar <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 más información, consulte Cómo montar el recurso compartido de archivos SMB de Azure en Windows.

Ejecute el siguiente comando para montar el compartir de archivos con las opciones de montaje recomendadas. Asegúrese de reemplazar <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

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

Compruebe que el montaje se realizó correctamente:

ls -la /mnt/smb

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

Actualización de las credenciales

Después de montar el recurso compartido de archivos por primera vez, inicie el servicio de actualización para mantener actualizadas las credenciales. Solo puede actualizar las credenciales si la máquina virtual tiene asignada una identidad administrada asignada por el usuario. Si va a proporcionar el token de OAuth directamente, la actualización no funcionará.

sudo systemctl start azfilesauth

Debe actualizar las credenciales periódicamente para evitar interrupciones de acceso. Puede actualizar las credenciales manualmente mediante el azfilesauthmanager set comando tal como se describe en Configuración de la autenticación o puede automatizar la actualización mediante las API de biblioteca compartida.

Solución de problemas

Los pasos de solución de problemas son diferentes para los clientes de Windows y Linux.

Windows
Linux

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.

En clientes Windows, utilice 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.
Intente montar el recurso compartido de nuevo y reproduzca el error.
Ahora debería tener un archivo denominado AzFilesSmbMILog.log. Envíe el archivo de registro a azurefilespm@microsoft.com para obtener ayuda.

Opciones de instalación e integración de la biblioteca cliente

La siguiente información está pensada para desarrolladores que necesitan integrar identidades administradas en sus aplicaciones.

Windows
Linux

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

Integración de ensamblados administrados: paquete NuGet

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

Instalación: Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94

Integración de DLL nativa

En el caso de las aplicaciones nativas que requieren acceso directo a la API, AzFilesSmbMIClient está disponible como dll nativa. Esto es especialmente útil para aplicaciones o sistemas de C/C++ que requieren integración de nivel inferior. Consulta la implementación de Windows y la referencia de API (archivo de encabezado 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 paquete azfilesauth. Puede vincular con la biblioteca en las aplicaciones de C/C++ para el acceso directo a la API.

Asegúrese de incluir el encabezado público.

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 (0 para éxito, no cero para errores).

Comando	Descripción
extern_smb_set_credential_oauth_token()	Establece las credenciales del token de OAuth para un punto de conexión de almacenamiento específico.
extern_smb_clear_credential()	Quita las credenciales almacenadas de un punto de conexión de almacenamiento.
extern_smb_list_credential()	Enumera todas las credenciales almacenadas
extern_smb_version()	Devuelve la cadena de versión de la biblioteca azfilesauth

Consulte también

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-12-11