Acessar compartilhamentos de arquivos do Azure usando a ID do Microsoft Entra com o OAuth de Arquivos do Azure por REST

Artigo
10/25/2023

O OAuth dos Arquivos do Azure na versão prévia da REST permite acesso de leitura e gravação no nível do administrador aos compartilhamentos de arquivos do Azure para usuários e aplicativos por meio do protocolo de autenticação OAuth, por meio do Microsoft Entra ID para acesso baseado na API REST. Usuários, grupos, serviços primários, como o portal do Azure, e serviços e aplicativos de terceiros que usam interfaces REST agora podem usar a autenticação e a autorização do OAuth com uma conta do Microsoft Entra para acessar dados em compartilhamentos de arquivos do Azure. Os cmdlets do PowerShell e os comandos da CLI do Azure que chamam as APIs REST também podem usar o OAuth para acessar compartilhamentos de arquivos do Azure.

Importante

Você deve chamar a API REST usando um cabeçalho explícito para indicar sua intenção de usar o privilégio adicional. Isso também vale para o Azure PowerShell e acesso à CLI do Azure.

Limitações

O OAuth dos Arquivos do Azure na Versão prévia da REST é compatível apenas com as APIs de dados FileREST que dão suporte a operações em arquivos e diretórios. Não há suporte para o OAuth em APIs do plano de dados FilesREST que gerenciam os recursos FileService e FileShare. Essas APIs de gerenciamento são chamadas usando a Chave da Conta de Armazenamento ou o token SAS e são expostas por meio do plano de dados por motivos herdados. É recomendável usar as APIs do painel de controle (o provedor de recursos de armazenamento – Microsoft.Storage) que dão suporte ao OAuth para todas as atividades de gerenciamento relacionadas aos recursos FileService e FileShare.

A autorização de operação de dados de arquivo com o Microsoft Entra ID tem suporte apenas para as versões da API REST de 02-11-2022 e posteriores. Veja Controle de versão para o Armazenamento do Azure.

Casos de uso público pelos clientes

A autenticação e a autorização do OAuth com os Arquivos do Azure na interface da API REST podem beneficiar os clientes nos cenários a seguir.

Desenvolvimento de aplicativos e integração de serviços

A autenticação e a autorização do OAuth permitem que os desenvolvedores criem aplicativos que acessam as APIs REST do Armazenamento do Azure usando identidades de usuário ou aplicativo do Microsoft Entra ID.

Clientes e parceiros também podem habilitar serviços primários e de terceiros para configurar o acesso necessário de forma segura e transparente a uma conta de armazenamento do cliente.

Ferramentas de DevOps como o portal do Azure, o PowerShell e a CL, AzCopy e Gerenciador de Armazenamento podem gerenciar dados usando a identidade do usuário, eliminando a necessidade de gerenciar ou distribuir chaves de acesso de armazenamento.

Identidades gerenciadas

Clientes com aplicativos e identidades gerenciadas que exigem acesso aos dados de compartilhamento de arquivos para fins de backup, restauração ou auditoria podem se beneficiar da autenticação e autorização do OAuth. A imposição de permissões no nível de arquivo e do diretório para cada identidade adiciona complexidade e talvez não seja compatível com determinadas cargas de trabalho. Por exemplo, os clientes podem querer autorizar um serviço de solução de backup para acessar os compartilhamentos de arquivos do Azure com acesso somente leitura a todos os arquivos, independentemente das permissões específicas de arquivo.

Substituição da chave da conta de armazenamento

O Microsoft Entra ID fornece segurança superior e facilidade de uso sobre o acesso à chave compartilhada. Você pode substituir o acesso à chave da conta de armazenamento pela autenticação e autorização do OAuth para acessar os Compartilhamentos arquivos do Azure por privilégios read-all/write-all. Essa abordagem também oferece melhor auditoria e acompanhamento de acesso de usuários específicos.

Acesso privilegiado e permissões de acesso para operações de dados

Para usar o recurso OAuth dos Arquivos do Azure sobre REST, há permissões adicionais que precisam ser incluídas na função RBAC atribuída ao usuário, grupo ou entidade de serviço. Duas novas ações de dados são introduzidas como parte desse recurso:

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

Usuários, grupos ou entidades de serviço que chamam a API REST com OAuth devem ter a ação readFileBackupSemantics ou writeFileBackupSemantics atribuída à função que permite o acesso aos dados. Esse é um requisito para usar esse recurso. Para saber detalhes sobre as permissões necessárias para chamar operações específicas do serviço Arquivo, confira Permissões para chamar operações de dados.

Esse recurso fornece duas novas funções internas que incluem essas novas ações.

Função	Ações de dados
Leitor Privilegiado de Dados de Arquivo de Armazenamento	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Colaborador Privilegiado de Dados de Arquivo de Armazenamento	`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`

Essas novas funções são semelhantes às funções internas existentes de Leitor de Compartilhamento SMB de Dados de Arquivo de Armazenamento e de Colaborador com Privilégios Elevados de Compartilhamento de Arquivos de Armazenamento, mas há algumas diferenças:

As novas funções contêm as ações de dados adicionais necessárias para acesso ao OAuth.
Quando o usuário, o grupo ou a entidade de serviço atribuídas a funções de Leitor Privilegiado de Dados de Arquivos de Armazenamento ou de Colaborador Privilegiado de Dados de Arquivos de Armazenamento chama a API de Dados FilesREST usando OAuth, o usuário, o grupo ou a entidade de serviço terão:
- Leitor Privilegiado de Dados de Arquivos de Armazenamento: Acesso total para leitura em todos os dados nos compartilhamentos para todas as contas de armazenamento configuradas, independentemente das permissões NTFS de nível de arquivo/diretório definidas.
- Colaborador Privilegiado de Dados de Arquivos de Armazenamento: Acesso total para leitura, gravação, modificação de ACLs e exclusão em todos os dados nos compartilhamentos para todas as contas de armazenamento configuradas, independentemente das permissões NTFS de nível de arquivo/diretório definidas.
Com essas permissões e funções especiais, o sistema ignorará todas as permissões de nível de arquivo/diretório e permitirá o acesso aos dados de compartilhamento de arquivos.

Com as novas funções e ações de dados, essa versão prévia do recurso fornecerá privilégios em toda a conta de armazenamento que substituem todas as permissões em arquivos e pastas em todos os compartilhamentos de arquivos na conta de armazenamento. No entanto, as novas funções possuem apenas permissões para acessar serviços de dados. Não incluem nenhuma permissão para acessar serviços de gerenciamento de compartilhamento de arquivos (ações em compartilhamentos de arquivos). Para usar esse recurso, verifique se você tem permissões para acessar:

a conta de armazenamento
serviços de gerenciamento de compartilhamento de arquivos
serviços de dados (os dados no compartilhamento de arquivos)

Existem muitas funções internas que fornecem acesso aos serviços de gerenciamento. Você também pode criar funções personalizadas com as permissões apropriadas. Para saber mais sobre o controle de acesso baseado em função, confira o RBAC do Azure. Para obter mais informações sobre como as funções internas são definidas, confira Compreender as definições de função.

Importante

Os casos de uso curinga definidos para o caminho Microsoft.Storage/storageAccounts/fileServices/* ou escopo superior herdarão automaticamente o acesso adicional e as permissões concedidas por meio dessa nova ação de dados. Para impedir o acesso não intencional ou com excesso de privilégios aos Arquivos do Azure, implementamos verificações adicionais que exigem que os usuários e os aplicativos indiquem explicitamente sua intenção ao usar o privilégio adicional. Além disso, é altamente recomendável que os clientes revisem suas atribuições de função RBAC de usuário e substituam qualquer uso curinga por permissões explícitas para garantir o gerenciamento adequado de acesso aos dados.

Autorizar o acesso aos dados de arquivo no código do aplicativo

A biblioteca de clientes da Identidade do Azure simplifica o processo de obtenção de um token de acesso OAuth 2.0 para autorização com o Microsoft Entra ID por meio do SDK do Azure. As versões mais recentes das bibliotecas de cliente do Armazenamento do Microsoft Azure para .NET, Java, Python, JavaScript e Go se integram com as bibliotecas de Identidade do Azure para cada uma dessas linguagens para fornecer um meio simples e seguro de aquisição de um token de acesso para autorização de solicitações do serviços de arquivos do Azure.

Uma vantagem da biblioteca de cliente de Identidade do Azure é que ela permite que você use o mesmo código para adquirir o token de acesso se seu aplicativo está em execução no ambiente de desenvolvimento ou no Azure. A biblioteca de clientes da Identidade do Azure retorna um token de acesso para uma entidade de segurança. Quando seu código está em execução no Azure, a entidade de segurança pode ser uma identidade gerenciada para recursos do Azure, uma entidade de serviço, um usuário ou grupo. No ambiente de desenvolvimento, a biblioteca de clientes fornece um token de acesso para um usuário ou para uma entidade de serviço para fins de teste.

O token de acesso retornado pela biblioteca de clientes da Identidade do Azure é encapsulado em uma credencial de token. Você pode, então, usar a credencial de token para obter um objeto de cliente do serviço a ser usado na execução de operações autorizadas no serviço de Arquivos do Azure.

Aqui está um exemplo de código:

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

Autorizar o acesso usando a API de plano de dados do FileREST

Você também pode autorizar o acesso aos dados de arquivos usando o portal do Azure ou o Azure PowerShell.

O portal do Azure pode usar sua conta do Microsoft Entra ou as chaves de acesso da conta de armazenamento para acessar dados de arquivos em uma conta de armazenamento do Azure. O esquema de autorização que o portal do Azure usa depende das funções do Azure atribuídas a você.

Quando você tenta acessar dados de arquivos, o portal do Azure verifica primeiro se foi uma função do Azure atribuída a você com Microsoft.Storage/storageAccounts/listkeys/action. Se uma função com essa ação foi atribuída a você, o portal do Azure usará a chave de conta para acessar dados de arquivos por meio da autorização de chave compartilhada. Se uma função com essa ação não foi atribuída a você, o portal do Azure tentará acessar os dados usando a sua conta do Microsoft Entra.

Para acessar dados de arquivo do portal do Azure usando sua conta do Microsoft Entra, você precisa de permissões para acessar dados de arquivo e também precisará de permissões para navegar pelos recursos de conta de armazenamento no portal do Azure. As funções internas fornecidas pelo Azure concedem acesso aos recursos e arquivos, mas não concedem permissões aos recursos da conta de armazenamento. Por esse motivo, o acesso ao portal também requer a atribuição de uma função do Azure Resource Manager (ARM), como a função Leitor no escopo do nível da conta de armazenamento ou superior. A função Leitor concede as permissões mais restritivas, mas qualquer função do ARM que conceda acesso aos recursos de gerenciamento da conta de armazenamento é aceitável.

O portal do Azure indica qual esquema de autorização está em uso quando você navega para um contêiner. Para saber mais sobre o acesso a dados no portal, confira Escolher como autorizar o acesso a dados de arquivos no portal do Azure.

O Azure fornece extensões para o PowerShell que permitem que você entre e chame cmdlets do PowerShell usando as credenciais do Microsoft Entra. Quando você entra no PowerShell com as credenciais do Microsoft Entra, um token de acesso OAuth 2.0 é retornado. O PowerShell usa automaticamente esse token para autorizar operações de dados subsequentes no armazenamento de arquivos. Para operações com suporte, você não precisa passar uma chave de conta ou token SAS com o comando.

Você pode atribuir permissões de dados de arquivos a uma entidade de segurança do Microsoft Entra por meio do RBAC do Azure.

Operações com suporte

As extensões só dão suporte a operações em dados de arquivos. As operações que podem ser chamadas dependem das permissões concedidas à entidade de segurança do Microsoft Entra com a qual você entrou no PowerShell.

O contexto de armazenamento com OAuth só funcionará se for chamado com o parâmetro -EnableFileBackupRequestIntent. Isso especifica a intenção explícita de usar as permissões adicionais que esse recurso fornece.

O contexto de armazenamento com OAuth só funcionará para operações em arquivos e diretórios e permissões Obter/Definir em compartilhamentos de arquivos do Azure. Você deve usar a chave de conta de armazenamento ou o token SAS para todas as outras operações em compartilhamentos de arquivos e conta de armazenamento.

Pré-requisitos

Também precisará de um grupo de recursos do Azure e uma conta de armazenamento dentro desse grupo de recursos. A conta de armazenamento deve receber uma função apropriada que conceda permissões explícitas para executar operações de dados em compartilhamentos de arquivos. Verifique se você tem as funções e permissões necessárias para acessar os serviços de gerenciamento e os serviços de dados. Para saber detalhes sobre as permissões necessárias para chamar operações específicas do serviço Arquivo, confira Permissões para chamar operações de dados.

Instale o módulo Az.Storage

Esse recurso está disponível no módulo mais recente do Az.Storage. Instale o módulo usando este comando:

Install-Module Az.Storage -Repository PsGallery

Autorizar acesso aos dados de arquivos

Para autorizar o acesso aos dados de arquivos, siga estas etapas.

Entre em sua conta do Azure usando o cmdlet Connect-AzAccount.
Obtenha o contexto da conta de armazenamento usando a chave da conta de armazenamento chamando o cmdlet Get-AzStorageAccount (serviço de gerenciamento). Substitua <ResourceGroupName> e <StorageAccountName> por seus valores.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Crie um compartilhamento de arquivos chamando New-AzStorageShare. Como você está usando o contexto da conta de armazenamento da etapa 2, o compartilhamento de arquivos é criado usando a chave da conta de armazenamento.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Obtenha o contexto da conta de armazenamento usando o OAuth para executar operações de dados no compartilhamento de arquivos (serviço de dados). Substitua <StorageAccountName> pelo nome da sua conta de armazenamento.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Para obter o contexto da conta de armazenamento com o OAuth, você deve passar explicitamente o parâmetro -EnableFileBackupRequestIntent para o cmdlet New-AzStorageContext. Se você não passar o parâmetro de intenção, as solicitações subsequentes da operação de dados de compartilhamento de arquivos usando o contexto falharão.
Crie um diretório de teste e um arquivo no compartilhamento de arquivos usando cmdlets New-AzStorageDirectory e Set-AzStorageFileContent. Lembre-se de especificar um caminho de arquivo de origem local.
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
Como os cmdlets são chamados usando o contexto da conta de armazenamento da etapa 4, o arquivo e o diretório serão criados usando as credenciais do Microsoft Entra.

Os principais comandos da CLI do Azure que são enviados como parte da CLI dão suporte a Arquivos OAuth pela interface REST e você pode usá-los para autenticar e autorizar operações de dados de arquivo usando credenciais do Microsoft Entra.

Operações com suporte

Os comandos só dão suporte a operações em dados de arquivos. As operações que podem ser chamadas dependem das permissões concedidas à entidade de segurança do Microsoft Entra com a qual você entrou na CLI do Azure.

A autenticação e a autorização do OAuth só funcionarão se o comando da CLI for chamado com a opção --backup-intent ou a opção --enable-file-backup-request-intent . Isso especifica a intenção explícita de usar as permissões adicionais que esse recurso fornece.

Todos os comandos em grupos de comandos az storage file, az storage directory e suporte à autenticação e autorização do OAuth az storage share list-handle e az storage share close-handle . Você deve usar a chave de conta de armazenamento ou o token SAS para todas as outras operações em compartilhamentos de arquivos e conta de armazenamento.