Acceso a recursos compartidos de archivos de Azure mediante Microsoft Entra ID con OAuth de Azure Files a través de REST

Artículo
10/21/2023

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 de 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 de REST también pueden usar OAuth para acceder a recursos compartidos de archivos de Azure.

Importante

Debe llamar a la API de REST mediante un encabezado explícito para indicar la intención de usar el privilegio adicional. Esto también es cierto para el acceso a Azure PowerShell y la CLI de Azure.

Limitaciones

OAuth de Azure Files a través de REST (versión preliminar) solo admite las API de datos de REST de Files que admiten operaciones en archivos y directorios. OAuth no se admite en las API del plano de datos de FilesREST que administran los recursos FileService y FileShare. Estas API de administración se llaman mediante la clave de cuenta de almacenamiento o el token de SAS, y se exponen a través del plano de datos por motivos heredados. Se recomienda usar las API del plano de control (el proveedor de recursos de almacenamiento: Microsoft.Storage) que admitan OAuth para todas las actividades de administración relacionadas con los recursos FileService y FileShare.

La autorización de operaciones de datos de archivos con Microsoft Entra ID solo se admite para las versiones 2022-11-02 y posteriores de la API de REST. Control de versiones para servicios de 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 de REST pueden beneficiar a los clientes en los escenarios siguientes.

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 de REST de Azure Storage mediante identidades de usuario o aplicación de Microsoft Entra ID.

Los clientes y asociados también pueden permitir que los servicios propios y de terceros configuren 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 Explorador de Azure 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 con 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 solución 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 una mayor seguridad y facilidad de uso que el acceso de clave compartida. Puede reemplazar el acceso a la clave de la cuenta de almacenamiento por la autenticación y autorización de OAuth para acceder a 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 sobre REST, se requieren permisos adicionales 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 entidades de servicio que llaman a la API de REST con OAuth deben tener asignada la acción readFileBackupSemantics o writeFileBackupSemantics al rol que permita el acceso a los datos. Este es un requisito para usar esta característica. Para obtener información sobre los permisos necesarios para llamar a operaciones concretas de servicio de archivos, vea Permisos para llamar a operaciones de datos.

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

Rol	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 roles integrados existentes Lector de recursos compartidos de SMB de datos de archivos de Storage y Colaborador con privilegios elevados de recursos compartidos de SMB de datos de archivos de almacenamiento, pero hay algunas diferencias:

Los nuevos roles contienen las acciones de datos adicionales necesarias para el acceso de OAuth.
Cuando el usuario, el grupo o la entidad de servicio a los que se asignan los roles Lector con privilegios de datos de archivo de almacenamiento o Colaborador con privilegios de archivos de almacenamiento llama a la API de FilesREST Data mediante OAuth, el usuario, el grupo o la entidad de servicio tendrán:
- Lector con privilegios de datos de archivo 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 archivo de almacenamiento: Acceso de lectura, escritura, eliminación y modificación de ACL 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.
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 en los archivos y carpetas de todos los recursos compartidos de los 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 a:

la cuenta de almacenamiento
servicios de administración de recursos compartidos de archivos
servicios de datos (los datos del recurso compartido de archivos)

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

Importante

Los casos de uso con caracteres comodín definidos para la ruta de acceso Microsoft.Storage/storageAccounts/fileServices/* o el á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 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 Azure Identity simplifica el proceso de obtener un token de acceso de OAuth 2.0 para la autorización con Microsoft Entra ID 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 Azure Identity para dichos lenguajes para proporcionar un medio sencillo y seguro de obtener un token de acceso para la autorización de las solicitudes del 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 de token para obtener un objeto de cliente de servicio que se usará para realizar operaciones autorizadas en el servicio de Azure Files.

Este es un código de ejemplo:

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 aadEndpoint = "";
            string accountUri = "";
            string connectionString = "";
            string shareName = "test-share";
            string directoryName = "testDirectory";
            string fileName = "testFile"; 

            ShareClient sharedKeyShareClient = new ShareClient(connectionString, shareName); 
            await sharedKeyShareClient.CreateIfNotExistsAsync(); 

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

            ShareClientOptions clientOptions = new ShareClientOptions(ShareClientOptions.ServiceVersion.V2023_05_03);

            // Set Allow Trailing Dot and Source Allow Trailing Dot.
            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();
            await sharedKeyShareClient.DeleteIfExistsAsync();
        }
    }
}

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

También puede autorizar el acceso a los datos de archivo mediante el Azure Portal o Azure PowerShell.

Azure Portal puede usar la cuenta de Microsoft Entra o las claves de acceso de 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.

Si intenta acceder a datos de archivos, Azure Portal primero comprueba si tiene asignado un rol de Azure con Microsoft.Storage/storageAccounts/listkeys/action. Si tiene un rol asignado con esta acción, Azure Portal usa la clave de cuenta para acceder a los datos de archivos mediante 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 datos de archivos desde Azure Portal con la cuenta de Microsoft Entra, necesita permisos para acceder a datos de archivos y, también, permisos para examinar los recursos de la cuenta de almacenamiento en Azure Portal. Los roles integrados que proporciona Azure conceden acceso a 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 la asignación de un rol de Azure Resource Manager (ARM), como el rol Lector, con ámbito limitado al nivel de la cuenta de almacenamiento o superior. El rol Lector concede los permisos más restringidos, pero otro rol de ARM que conceda acceso a los recursos de administración de la cuenta de almacenamiento también es aceptable.

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

Azure proporciona extensiones para PowerShell que le 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 OAuth 2.0. PowerShell usa automáticamente ese token para autorizar las operaciones de datos posteriores en el almacenamiento de archivos. Para las operaciones admitidas, ya no necesita pasar una clave de cuenta o token SAS con el comando.

Puede asignar permisos para los datos de archivos a una entidad de seguridad de Microsoft Entra mediante Azure RBAC.

Operaciones compatibles

Las extensiones solo admiten operaciones en los datos de archivo. Las operaciones a las que pueda llamar dependerán de los permisos que se concedan a la entidad de seguridad de Microsoft Entra con la que inicie sesión en PowerShell.

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

El contexto de almacenamiento con OAuth solo funcionará para las operaciones en archivos y directorios y los 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.

Requisitos previos

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 tanto a los servicios de administración como a los servicios de datos. Para obtener información sobre los permisos necesarios para llamar a operaciones concretas de servicio de archivos, vea Permisos para llamar a operaciones de datos.

Instale el módulo Az.Storage

Esta característica está disponible en el último módulo de Az.Storage. Instale el módulo con 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 mediante el cmdlet Connect-AzAccount.
Obtenga el contexto de la cuenta de almacenamiento mediante la clave de cuenta de almacenamiento llamando al cmdlet Get-AzStorageAccount (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 cuenta de almacenamiento.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Obtenga el contexto de cuenta de almacenamiento mediante OAuth para realizar operaciones de datos en el recurso compartido 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 parámetro -EnableFileBackupRequestIntent al cmdlet New-AzStorageContext. Si no pasa el parámetro intención, se producirá un error en las solicitudes de operación de datos del recurso compartido de archivos posteriores mediante el contexto.
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 credenciales de Microsoft Entra.

Los comandos principales de la CLI de Azure que se incluyen como parte de la CLI admiten OAuth de archivos a través de la interfaz de 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 datos de archivo. Las operaciones a las que pueda llamar dependerán de los permisos que se concedan a la entidad de seguridad de Microsoft Entra con la que inicie 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 opción --backup-intent o --enable-file-backup-request-intent. Se trata de especificar la intención explícita para usar los permisos adicionales que proporciona esta característica.

Todos los comandos de az storage file, az storage directory grupos de comandos,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.