Acceso a comparticiones de archivos de Azure usando Microsoft Entra ID con OAuth de Azure Files a través de REST

2025-05-20

OAuth de Azure Files a través de REST permite acceso de lectura y escritura de nivel de administrador a los recursos compartidos de archivos de Azure para usuarios y aplicaciones a través del protocolo de autenticación de OAuth, por medio de Microsoft Entra ID para el acceso basado en la API de REST. Los usuarios, grupos, servicios de primera entidad, como Azure Portal y servicios y aplicaciones de terceros que usan interfaces REST, ahora pueden usar la autenticación y autorización de OAuth con una cuenta de Microsoft Entra para acceder a los datos de recursos compartidos de archivos de Azure. Los cmdlets de PowerShell y los comandos de la CLI de Azure que llaman a las API REST también pueden usar OAuth para acceder a recursos compartidos de archivos de Azure. Debe llamar a la API REST mediante un encabezado explícito para indicar la intención de usar el privilegio adicional. Esto también es cierto para el acceso de Azure PowerShell y la CLI de Azure.

Importante

En este artículo se explica cómo habilitar el acceso de nivel de administrador a recursos compartidos de archivos de Azure para casos de uso específicos del cliente. Si busca un artículo más general sobre la autenticación basada en identidades para los usuarios finales, consulte Introducción a la autenticación basada en identidad de Azure Files para el acceso SMB.

Se aplica a

Modelo de administración	Modelo de facturación	Nivel multimedia	Redundancia
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	Local (LRS)
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	Zona (ZRS)
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	Geo (GRS)
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	GeoZone (GZRS)
Microsoft.Storage	Aprovisionado v1	SSD (Premium)	Local (LRS)
Microsoft.Storage	Aprovisionado v1	SSD (Premium)	Zona (ZRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	Local (LRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	Zona (ZRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	Geo (GRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	GeoZone (GZRS)

Limitaciones

La autorización de operaciones de datos de archivos con el identificador de Entra de Microsoft solo se admite para las versiones de la API REST 2022-11-02 y versiones posteriores.

La compatibilidad con OAuth de Azure Files sobre REST para las API del plano de datos REST de Azure Files que administran los recursos FileService y FileShare está disponible con las versiones de api REST 2024-11-04 y posteriores.

Consulte Control de versiones para Azure Storage.

Casos de uso de clientes

La autenticación y autorización de OAuth con Azure Files a través de la interfaz de la API REST pueden beneficiar a los clientes en los siguientes escenarios.

Integración del servicio y desarrollo de aplicaciones

La autenticación y autorización de OAuth permiten a los desarrolladores crear aplicaciones que accedan a las API REST de Azure Storage mediante identidades de usuario o aplicación de Microsoft Entra ID.

Los clientes y asociados también pueden habilitar servicios propios y de terceros para configurar el acceso necesario de forma segura y transparente a una cuenta de almacenamiento del cliente.

Las herramientas de DevOps, como Azure Portal, PowerShell y la CLI, AzCopy y el Explorador de Storage, pueden administrar datos mediante la identidad del usuario, lo que elimina la necesidad de administrar o distribuir claves de acceso de almacenamiento.

Identidades administradas

Los clientes con aplicaciones e identidades administradas que requieren acceso a los datos del recurso compartido de archivos para fines de copia de seguridad, restauración o auditoría pueden beneficiarse de la autenticación y autorización de OAuth. La aplicación de permisos de nivel de archivo y directorio para cada identidad agrega complejidad y podría no ser compatible con determinadas cargas de trabajo. Por ejemplo, es posible que los clientes quieran autorizar a un servicio de copia de seguridad para acceder a recursos compartidos de archivos de Azure con acceso de solo lectura a todos los archivos sin tener en cuenta los permisos específicos del archivo.

Reemplazo de la clave de la cuenta de almacenamiento

Microsoft Entra ID proporciona mayor seguridad y facilidad de uso sobre el acceso a claves compartidas. Puede reemplazar el acceso a la clave de la cuenta de almacenamiento por la autenticación de OAuth y la autorización para acceder a los recursos compartidos de Archivos de Azure con privilegios de lectura y escritura. Este enfoque también ofrece una mejor auditoría y seguimiento del acceso específico de los usuarios.

Permisos de acceso y acceso con privilegios para las operaciones de datos

Para usar la característica OAuth de Azure Files a través de REST, hay permisos adicionales necesarios para incluirse en el rol RBAC asignado al usuario, grupo o entidad de servicio. Se presentan dos nuevas acciones de datos como parte de esta característica:

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

Los usuarios, grupos o principales de servicio que llaman a la API REST con OAuth deben tener asignada la acción readFileBackupSemantics o writeFileBackupSemantics al rol que permita acceder a los datos. Este es un requisito para usar esta característica. Para obtener más información sobre los permisos necesarios para llamar a operaciones específicas del servicio de archivos, consulte Permisos para llamar a operaciones de datos.

Esta característica proporciona dos nuevos roles integrados que incluyen estas nuevas acciones.

Función	Acciones de datos
Lector con privilegios de datos de archivos de Storage	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Colaborador con privilegios de datos de archivos de Storage	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/fileShares/files/write` `Microsoft.Storage/storageAccounts/fileServices/fileShares/files/delete` `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` `Microsoft.Storage/storageAccounts/fileServices/fileshares/files/modifypermissions/action`

Estos nuevos roles son similares a los Lector de recursos compartidos SMB de datos de archivos de almacenamiento existentes y colaborador con privilegios elevados de recursos compartidos de archivos de almacenamiento SMB roles integrados, pero hay algunas diferencias:

Los nuevos roles contienen las acciones de datos adicionales necesarias para el acceso de OAuth.
Cuando el usuario, grupo o entidad de servicio a los que se ha asignado los roles Lector de datos de archivos de almacenamiento con privilegios o Colaborador de datos de archivos de almacenamiento con privilegios llama a la API de datos FilesREST mediante OAuth, el usuario, grupo o la entidad de servicio tendrá:
- Lector con privilegios de datos de archivos de almacenamiento: Acceso de lectura completo en todos los datos de los recursos compartidos para todas las cuentas de almacenamiento configuradas, independientemente de los permisos NTFS de nivel de archivo o directorio establecidos.
- Colaborador con privilegios de datos de archivos de almacenamiento: Lectura completa, escritura, modificación de ACL, eliminación del acceso a todos los datos de los recursos compartidos de todas las cuentas de almacenamiento configuradas independientemente de los permisos NTFS de nivel de archivo o directorio establecidos.
Con estos permisos y roles especiales, el sistema omitirá los permisos de nivel de archivo o directorio y permitirá el acceso a los datos del recurso compartido de archivos.

Con los nuevos roles y acciones de datos, esta característica proporcionará privilegios para toda la cuenta de almacenamiento que reemplazan todos los permisos de archivos y carpetas en todos los recursos compartidos de archivos de la cuenta de almacenamiento. Sin embargo, los nuevos roles solo contienen permisos para acceder a los servicios de datos. No incluyen ningún permiso para acceder a los servicios de administración de recursos compartidos de archivos (acciones en recursos compartidos de archivos). Para usar esta característica, asegúrese de que tiene permisos para acceder:

la cuenta de almacenamiento
Servicios de administración de recursos compartidos de archivos
servicios de datos (los datos de la compartición de archivos)

Hay muchos roles integrados que proporcionan acceso a los servicios de administración. También puede crear roles personalizados con los permisos adecuados. Para más información sobre el control de acceso basado en rol, consulte Azure RBAC. Para más información sobre cómo se definen los roles integrados, consulte Descripción de definiciones de roles.

Tenga en cuenta que para el tipo de recurso del recurso compartido de archivos, el ámbito RBAC correspondiente usa shares en el plano de control (operaciones de administración), pero usa fileshares en el plano de datos (operaciones de datos). Si intenta usar un identificador de recurso de recurso compartido de archivos que contiene shares en el ámbito de RBAC o las cadenas de acción de datos, no funcionará. Debe usar fileshares en el ámbito de las asignaciones de RBAC, por ejemplo:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>/fileServices/default/fileshares/<share-name>

Importante

Los casos de uso de caracteres comodín definidos para la ruta de acceso Microsoft.Storage/storageAccounts/fileServices/* o un ámbito superior heredarán automáticamente el acceso adicional y los permisos concedidos a través de esta nueva acción de datos. Para evitar el acceso no deseado o con privilegios excesivos a Azure Files, hemos implementado comprobaciones adicionales que requieren que los usuarios y las aplicaciones indiquen explícitamente su intención de usar el privilegio adicional. Además, se recomienda encarecidamente que los clientes revisen sus asignaciones de roles de RBAC de usuario y reemplacen cualquier uso de caracteres comodín con permisos explícitos para garantizar la administración adecuada del acceso a los datos.

Autorización del acceso a los datos de archivo en el código de la aplicación

La biblioteca cliente de Identidad de Azure simplifica el proceso de obtención de un token de acceso de OAuth 2.0 para la autorización con el identificador de Microsoft Entra a través del SDK de Azure. Las versiones más recientes de las bibliotecas cliente de Azure Storage para .NET, Java, Python, JavaScript y Go se integran con las bibliotecas de Identidad de Azure para cada uno de esos lenguajes para proporcionar un medio sencillo y seguro para adquirir un token de acceso para la autorización de solicitudes desde el servicio de archivos de Azure.

Una ventaja de la biblioteca cliente de Azure Identity es que permite usar el mismo código para adquirir el token de acceso tanto si la aplicación se ejecuta en el entorno de desarrollo como en Azure. La biblioteca cliente de Azure Identity devuelve un token de acceso para una entidad de seguridad. Cuando el código se ejecuta en Azure, la entidad de seguridad puede ser una identidad administrada para recursos de Azure, una entidad de servicio, un usuario o un grupo. En el entorno de desarrollo, la biblioteca cliente proporciona un token de acceso para un usuario o una entidad de servicio con fines de prueba.

El token de acceso devuelto por la biblioteca cliente de Azure Identity se encapsula en una credencial de token. A continuación, puede usar la credencial del token para obtener un objeto de cliente de servicio que se usará para realizar operaciones autorizadas en el servicio Azure Files.

En el ejemplo de código siguiente se muestra cómo autorizar un objeto de cliente mediante el identificador de Microsoft Entra y realizar operaciones en el nivel de directorio y archivo. En este ejemplo se supone que la compartición de archivos ya existe.

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

namespace FilesOAuthSample
{
    internal class Program
    {
        static async Task Main(string[] args)
        {
            string tenantId = "";
            string appId = "";
            string appSecret = "";
            string entraEndpoint = "";
            string accountUri = "https://<storage-account-name>.file.core.windows.net/";
            string shareName = "test-share";
            string directoryName = "test-directory";
            string fileName = "test-file";  

            TokenCredential tokenCredential = new ClientSecretCredential(
                tenantId,
                appId,
                appSecret,
                new TokenCredentialOptions()
                {
                    AuthorityHost = new Uri(entraEndpoint)
                });

            // Set client options
            ShareClientOptions clientOptions = new ShareClientOptions();
            clientOptions.AllowTrailingDot = true;
            clientOptions.AllowSourceTrailingDot = true;

            // x-ms-file-intent=backup will automatically be applied to all APIs
            // where it is required in derived clients
            clientOptions.ShareTokenIntent = ShareTokenIntent.Backup;

            ShareServiceClient shareServiceClient = new ShareServiceClient(
                new Uri(accountUri),
                tokenCredential,
                clientOptions);

            ShareClient shareClient = shareServiceClient.GetShareClient(shareName);
            ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient(directoryName);
            await directoryClient.CreateAsync();

            ShareFileClient fileClient = directoryClient.GetFileClient(fileName);
            await fileClient.CreateAsync(maxSize: 1024);
            await fileClient.GetPropertiesAsync();
        }
    }
}

Autorización del acceso mediante la API de plano de datos FileREST

También puede autorizar el acceso a los datos de archivos mediante Azure Portal, Azure PowerShell o la CLI de Azure.

Azure Portal puede usar la cuenta de Microsoft Entra o la clave de acceso de la cuenta de almacenamiento para acceder a los datos de archivos de una cuenta de Almacenamiento de Azure. El esquema de autorización que use Azure Portal depende de los roles de Azure que tenga asignados.

Al intentar acceder a los datos de archivo, Azure Portal comprueba primero si se le ha asignado un rol de Azure con Microsoft.Storage/storageAccounts/listkeys/action. Si se le ha asignado un rol con esta acción, Azure Portal usa la clave de cuenta para acceder a los datos de archivo a través de la autorización de clave compartida. Si no tiene un rol asignado con esta acción, Azure Portal intenta acceder a los datos mediante la cuenta de Microsoft Entra.

Para acceder a los datos de archivo desde Azure Portal mediante su cuenta de Microsoft Entra, necesita permisos para acceder a los datos de archivos y también necesita permisos para navegar por los recursos de la cuenta de almacenamiento en Azure Portal. Los roles integrados proporcionados por Azure conceden acceso a los recursos de archivos, pero no conceden permisos a los recursos de la cuenta de almacenamiento. Por este motivo, el acceso al portal también requiere asignar un rol de Azure Resource Manager (ARM), como el rol Lector , con ámbito al nivel de la cuenta de almacenamiento o superior. El rol Lector concede los permisos más restrictivos, pero cualquier rol de ARM que conceda acceso a los recursos de administración de cuentas de almacenamiento es aceptable.

Azure Portal indica qué esquema de autorización se está usando al examinar un contenedor. Para más información sobre el acceso a datos en el portal, consulte Elección de cómo autorizar el acceso a los datos de archivos en Azure Portal.

Azure proporciona extensiones para PowerShell que permiten iniciar sesión y llamar a cmdlets de PowerShell mediante credenciales de Microsoft Entra. Al iniciar sesión en PowerShell con credenciales de Microsoft Entra, se devuelve un token de acceso de OAuth 2.0. PowerShell usa automáticamente ese token para autorizar las operaciones de datos posteriores en el almacenamiento de archivos. En el caso de las operaciones admitidas, ya no es necesario pasar una clave de cuenta o un token de SAS con el comando .

Puede asignar permisos a los datos de archivo a una entidad de seguridad de Microsoft Entra a través de Azure RBAC.

Operaciones compatibles

Las extensiones solo admiten operaciones en los datos de archivo. Las operaciones a las que puede llamar dependen de los permisos concedidos a la entidad de seguridad de Microsoft Entra con la que inició sesión en PowerShell.

El contexto de almacenamiento con OAuth solo funcionará si se llama con el -EnableFileBackupRequestIntent parámetro . Esto es para especificar la intención explícita de usar los permisos adicionales que proporciona esta característica.

El contexto de almacenamiento con OAuth solo funcionará para operaciones en archivos y directorios y permisos Get/Set en recursos compartidos de archivos de Azure. Para todas las demás operaciones en recursos compartidos de archivos y cuentas de almacenamiento, debe usar la clave de cuenta de almacenamiento o el token de SAS.

Prerrequisitos

Necesitará un grupo de recursos de Azure y una cuenta de almacenamiento dentro de ese grupo de recursos. A la cuenta de almacenamiento se le debe asignar un rol adecuado que conceda permisos explícitos para realizar operaciones de datos en recursos compartidos de archivos. Asegúrese de que tiene los roles y permisos necesarios para acceder a los servicios de administración y a los servicios de datos. Para obtener más información sobre los permisos necesarios para llamar a operaciones específicas del servicio de archivos, consulte Permisos para llamar a operaciones de datos.

Instalación del módulo Az.Storage

Esta característica está disponible en el módulo Az.Storage más reciente. Instale el módulo mediante este comando:

Install-Module Az.Storage -Repository PsGallery

Autorizar el acceso a los datos del archivo

Para autorizar el acceso a los datos de archivo, siga estos pasos.

Inicie sesión en su cuenta de Azure con el Connect-AzAccount cmdlet .
Obtenga el contexto de la cuenta de almacenamiento usando la clave de la cuenta de almacenamiento mediante una llamada al Get-AzStorageAccount cmdlet (servicio de administración). Reemplace <ResourceGroupName> y <StorageAccountName> con sus valores.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Cree un recurso compartido de archivos llamando a New-AzStorageShare. Dado que usa el contexto de la cuenta de almacenamiento del paso 2, el recurso compartido de archivos se crea con la clave de la cuenta de almacenamiento.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Obtenga el contexto de la cuenta de almacenamiento utilizando OAuth para realizar operaciones de datos en la compartición de archivos (servicio de datos). Sustituya <StorageAccountName> por el nombre de su cuenta de almacenamiento.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Para obtener el contexto de la cuenta de almacenamiento con OAuth, debe pasar explícitamente el -EnableFileBackupRequestIntent parámetro al New-AzStorageContext cmdlet . Si no pasa el parámetro Intent, las operaciones de solicitud de datos para compartir archivos posteriores utilizando el contexto fallarán.
Cree un directorio de prueba y un archivo en el recurso compartido de archivos mediante los cmdlets New-AzStorageDirectory y Set-AzStorageFileContent. Recuerde especificar una ruta de acceso del archivo de origen local.
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
Dado que se llama a los cmdlets mediante el contexto de la cuenta de almacenamiento del paso 4, el archivo y el directorio se crearán mediante las credenciales de Microsoft Entra.

Los comandos principales de la CLI de Azure que se incluyen como parte de la CLI admiten OAuth a través de la interfaz REST y puede usarlos para autenticar y autorizar operaciones de datos de archivos mediante credenciales de Microsoft Entra.

Operaciones compatibles

Los comandos solo admiten operaciones en los datos de archivo. Las operaciones a las que puede llamar dependen de los permisos concedidos a la entidad de seguridad de Microsoft Entra con la que inició sesión en la CLI de Azure.

La autenticación y autorización de OAuth solo funcionarán si se llama al comando de la CLI con la --backup-intent opción o --enable-file-backup-request-intent opción . Esto es para especificar la intención explícita de usar los permisos adicionales que proporciona esta característica.

Todos los comandos bajo los grupos de comandos az storage file y az storage directory, así como az storage share list-handle y az storage share close-handle, admiten la autenticación y autorización de OAuth. Para todas las demás operaciones en recursos compartidos de archivos y cuentas de almacenamiento, debe usar la clave de cuenta de almacenamiento o el token de SAS.

Prerrequisitos

Comandos de instalación y ejemplo

Si aún no lo ha hecho, instale la versión más reciente de la CLI de Azure.