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

2025-05-20

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 de primeira parte, como o portal do Azure e serviços e aplicativos de terceiros usando interfaces REST, agora podem usar a autenticação e 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 APIs REST também podem usar o OAuth para acessar compartilhamentos de arquivos do Azure. 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 é verdadeiro para acesso ao Azure PowerShell e à CLI do Azure.

Importante

Este artigo explica como habilitar o acesso em nível de administrador aos compartilhamentos de arquivos do Azure para casos específicos de uso do cliente. Se você estiver procurando um artigo mais geral sobre autenticação baseada em identidade para usuários finais, consulte Visão geral da autenticação baseada em identidade dos Arquivos do Azure para acesso SMB.

Aplica-se a

Modelo de gestão	Modelo de cobrança	Camada de mídia	Redundância
Microsoft.Storage	Provisionado v2	HDD (padrão)	Local (LRS)
Microsoft.Storage	Provisionado v2	HDD (padrão)	Zona (ZRS)
Microsoft.Storage	Provisionado v2	HDD (padrão)	Localização geográfica (GRS)
Microsoft.Storage	Provisionado v2	HDD (padrão)	GeoZone (GZRS)
Microsoft.Storage	Provisionado v1	SSD (de alta qualidade)	Local (LRS)
Microsoft.Storage	Provisionado v1	SSD (de alta qualidade)	Zona (ZRS)
Microsoft.Storage	Pago conforme o uso	HDD (padrão)	Local (LRS)
Microsoft.Storage	Pago conforme o uso	HDD (padrão)	Zona (ZRS)
Microsoft.Storage	Pago conforme o uso	HDD (padrão)	Localização geográfica (GRS)
Microsoft.Storage	Pago conforme o uso	HDD (padrão)	GeoZone (GZRS)

Limitações

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

O OAuth de Arquivos do Azure sobre suporte a REST para APIs do plano de dados REST dos Arquivos do Azure que gerenciam os recursos FileService e FileShare está disponível com as versões da API REST 2024-11-04 e posteriores.

Consulte o controle de versão do Armazenamento do Azure.

Casos de uso público pelos clientes

A autenticação e autorização do OAuth com os Arquivos do Azure por meio da interface de 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 APIs REST do Armazenamento do Azure usando identidades de usuário ou aplicativo da ID do Microsoft Entra.

Clientes e parceiros também podem habilitar serviços de primeira e terceira parte 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 CLI, o AzCopy e o 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 diretório para cada identidade adiciona complexidade e pode não ser compatível com determinadas cargas de trabalho. Por exemplo, talvez os clientes queiram autorizar um serviço de solução de backup a acessar compartilhamentos de arquivos do Azure com acesso somente leitura a todos os arquivos sem levar em conta as permissões específicas do arquivo.

Substituição da chave da conta de armazenamento

A Microsoft Entra ID fornece uma segurança superior e facilidade de uso comparado ao acesso por chave compartilhada. Você pode substituir o acesso à chave da conta de armazenamento pela autenticação e autorização do OAuth para acessar os compartilhamentos de arquivos do Azure com privilégios de leitura total/gravação total. Essa abordagem também oferece uma melhor auditoria e rastreamento de acesso de usuário específico.

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

Para usar o recurso OAuth de Arquivos do Azure por 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 acesso a dados. Esse é um requisito para usar esse recurso. Para obter detalhes sobre as permissões necessárias para chamar operações de serviço de arquivo específicas, consulte 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`

Esses novos papéis são semelhantes aos papéis internos existentes de Leitor de Compartilhamento de Arquivo Storage SMB e Colaborador Elevado de Compartilhamento de Arquivo Storage SMB, 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, que está atribuído às funções de Leitor Privilegiado de Dados de Arquivo de Armazenamento ou Colaborador Privilegiado de Dados de Arquivo de Armazenamento, chama a API de Dados FilesREST usando OAuth, o usuário, o grupo ou a entidade de serviço terá:
- 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, esse 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 contêm apenas permissões para acessar serviços de dados. Eles não incluem permissões 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)

Há 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, consulte 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.

Tenha em mente que, para o tipo de recurso de compartilhamento de arquivos, o escopo rbac correspondente usa shares no plano de controle (operações de gerenciamento), mas usa fileshares no plano de dados (operações de dados). Se você tentar usar uma ID de recurso de compartilhamento de arquivos que contenha shares no escopo RBAC ou cadeias de caracteres de ação de dados, ela não funcionará. Você deve usar fileshares no escopo de atribuições RBAC, por exemplo:

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

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 privilégios excessivos aos Arquivos do Azure, implementamos verificações adicionais que exigem que usuários e aplicativos indiquem explicitamente sua intenção de 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 do arquivo no código do aplicativo

A biblioteca de clientes do Azure Identity 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 clientes do Armazenamento do Azure para .NET, Java, Python, JavaScript e Go se integram às bibliotecas de Identidade do Azure para cada um desses idiomas para fornecer um meio simples e seguro para adquirir um token de acesso para autorização de solicitações do serviço 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. Em seguida, você pode usar a credencial de token para obter um objeto cliente de serviço, que será usado na execução de operações autorizadas no serviço Azure Files.

O exemplo de código a seguir mostra como autorizar um objeto cliente usando a ID do Microsoft Entra e executar operações no nível do diretório e do arquivo. Este exemplo pressupõe que o compartilhamento de arquivos já 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();
        }
    }
}

Autorizar o acesso usando a API do plano de dados FileREST

Você também pode autorizar o acesso a dados de arquivo usando o portal do Azure, o Azure PowerShell ou a CLI do Azure.

O portal do Azure pode usar sua conta do Microsoft Entra ou a chave de acesso da conta de armazenamento para acessar dados de arquivo 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 arquivo, o portal do Azure verifica primeiro se você recebeu uma função do Azure com Microsoft.Storage/storageAccounts/listkeys/action. Se você tiver recebido uma função com essa ação, o portal do Azure usará a chave da conta para acessar dados de arquivo 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 precisa de permissões para navegar pelos recursos da conta de armazenamento no portal do Azure. As funções internas fornecidas pelo Azure concedem acesso aos recursos de arquivo, 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, com escopo no nível da conta de armazenamento ou superior. A função Leitor concede as permissões mais restritivas, mas qualquer função ARM que conceda acesso aos recursos de gerenciamento de 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 obter mais informações sobre o acesso a dados no portal, consulte Escolher como autorizar o acesso aos dados do arquivo 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 transmitir uma chave de conta ou um 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 arquivo. 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 -EnableFileBackupRequestIntent parâmetro. Isso é para especificar 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 Get/Set em compartilhamentos de arquivos do Azure. Para todas as outras operações em compartilhamentos de arquivos e conta de armazenamento, você deve usar a chave da conta de armazenamento ou o token SAS.

Pré-requisitos

Você 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 obter detalhes sobre as permissões necessárias para chamar operações de serviço de arquivo específicas, consulte Permissões para chamar operações de dados.

Instalar o módulo Az.Storage

Esse recurso está disponível no módulo Az.Storage mais recente. 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 do arquivo, siga estas etapas.

Entre em sua conta do Azure usando o Connect-AzAccount cmdlet.
Obtenha o contexto da conta de armazenamento usando a chave da conta de armazenamento chamando o Get-AzStorageAccount cmdlet (serviço de gerenciamento). Substitua <ResourceGroupName> e <StorageAccountName> por seus valores.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Criar 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 sua chave de 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 -EnableFileBackupRequestIntent parâmetro para o New-AzStorageContext cmdlet. Se você não passar o parâmetro de intenção, as solicitações subsequentes de 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 New-AzStorageDirectory e Set-AzStorageFileContent cmdlets. 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 as credenciais do Microsoft Entra.

Operações com suporte

Os comandos só dão suporte a operações em dados de arquivo. 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 --backup-intent opção ou a --enable-file-backup-request-intent opção. Isso é para especificar a intenção explícita de usar as permissões adicionais que esse recurso fornece.

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

Pré-requisitos

Comandos de instalação e exemplo

Se você ainda não fez isso, instale a versão mais recente da CLI do Azure.

Autorizar acesso aos dados de arquivos

Entre em sua conta do Azure.
```
az login
```
Criar um compartilhamento de arquivos chamando az storage share create cli. Como você está usando a cadeia de conexão, o compartilhamento de arquivos é criado usando sua chave de conta de armazenamento.
```
az storage share create --name testshare1 --connection-string <connection-string>
```
Crie um diretório de teste e carregue um arquivo no compartilhamento de arquivos usando az storage directory create e az storage file upload cli. Lembre-se de especificar o modo --auth como login e passar o parâmetro --backup-intent.
```
az storage directory create --name testdir1 --account-name filesoauthsa --share-name testshare1 --auth-mode login --backup-intent
az storage file upload  --account-name filesoauthsa --share-name testshare1 --auth-mode login --backup-intent --source <source file path>
```
Como os comandos da CLI são chamados usando um tipo de autenticação, como login (login --auth mode e parâmetro --backup-intent), o arquivo e o diretório serão criados usando as credenciais do Microsoft Entra.

Para obter mais informações, consulte a documentação mais recente da CLI para comandos com suporte:

Consulte também

Escolher como autorizar o acesso aos dados de arquivos no portal do Azure