Aceder a partilhas de ficheiros do Azure usando o ID do Microsoft Entra com o OAuth do Azure Files via REST

O Azure Files OAuth sobre REST permite o acesso de leitura e gravação em nível de administrador a partilhas de ficheiros do Azure para utilizadores e aplicações por meio do protocolo de autenticação OAuth, usando a ID do Entra da Microsoft 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 autorização 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 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 é verdade para o Azure PowerShell e o acesso à CLI do Azure.

Importante

Este artigo explica como habilitar o acesso em nível de administrador a compartilhamentos de arquivos do Azure para casos de uso específicos de clientes. 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 faturação	Nível de média	Redundância
Microsoft.Armazenamento	Provisionado v2	HDD (padrão)	Localização (LRS)
Microsoft.Armazenamento	Provisionado v2	HDD (padrão)	Zona (ZRS)
Microsoft.Armazenamento	Provisionado v2	HDD (padrão)	Geo (GRS)
Microsoft.Armazenamento	Provisionado v2	HDD (padrão)	GeoZona (GZRS)
Microsoft.Armazenamento	Provisionado v1	SSD (de qualidade superior)	Localização (LRS)
Microsoft.Armazenamento	Provisionado v1	SSD (de qualidade superior)	Zona (ZRS)
Microsoft.Armazenamento	Pagamento conforme o consumo	HDD (padrão)	Localização (LRS)
Microsoft.Armazenamento	Pagamento conforme o consumo	HDD (padrão)	Zona (ZRS)
Microsoft.Armazenamento	Pagamento conforme o consumo	HDD (padrão)	Geo (GRS)
Microsoft.Armazenamento	Pagamento conforme o consumo	HDD (padrão)	GeoZona (GZRS)

Limitações

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

O suporte do OAuth do Azure Files através de REST para as APIs REST do plano de dados do Azure Files, que gerem os recursos FileService e FileShare, está disponível nas versões de API REST 2024-11-04 e posteriores.

Consulte Controle de versão para o Armazenamento do Azure.

Casos de uso de clientes

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

Desenvolvimento de aplicações e integração de serviços

A autenticação e a autorização 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.

Os 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, PowerShell e CLI, AzCopy e Storage Explorer, podem gerenciar dados usando a identidade do usuário, eliminando a necessidade de gerenciar ou distribuir chaves de acesso de armazenamento.

Identidades gerenciadas

Os clientes com aplicativos e identidades gerenciadas que exigem acesso a dados de compartilhamento de arquivos para fins de backup, restauração ou auditoria podem se beneficiar da autenticação e autorização 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, os clientes podem querer autorizar um serviço de solução de backup para acessar compartilhamentos de arquivos do Azure com acesso somente leitura a todos os arquivos, sem considerar permissões específicas de arquivos.

Substituição da chave da conta de armazenamento

O Microsoft Entra ID oferece segurança superior e facilidade de uso em relação ao acesso de chave compartilhada. Você pode substituir o acesso à chave da conta de armazenagem pela autenticação OAuth e autorização para aceder a partilhas de ficheiros do Azure com privilégios de leitura e escrita totais. Essa abordagem também oferece melhor auditoria e rastreamento de acesso de usuários específicos.

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

Para usar o recurso OAuth sobre REST dos Arquivos do Azure, existem permissões adicionais que precisam ser incluídas na função RBAC atribuída ao usuário, grupo ou principal 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

Os utilizadores, 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. Este é um requisito para usar esse recurso. Para obter detalhes sobre as permissões necessárias para chamar operações específicas do serviço de Arquivo, consulte Permissões para operações de chamada 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 arquivos de armazenamento	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Contribuidor privilegiado de dados de ficheiros 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 de Dados de Arquivo SMB e Contribuinte Elevado de Dados de Arquivo de Armazenamento SMB, mas há algumas diferenças:

As novas funções contêm as ações de dados adicionais necessárias para o acesso OAuth.
Quando o utilizador, grupo ou principal de serviço atribuído às funções 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 utilizador, grupo ou principal de serviço terá:
- Leitor Priviligiado de Dados em Ficheiros de Armazenamento: Acesso completo de leitura a todos os dados nas partilhas para todas as contas de armazenamento configuradas, independentemente das permissões NTFS definidas a nível de ficheiro/diretório.
- Contribuidor privilegiado de dados de arquivo de armazenamento: Leitura, gravação, modificação de ACLs completas, exclusão de acesso a todos os dados nas partilhas 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á quaisquer permissões de nível de arquivo/diretório e permitirá o acesso a dados de compartilhamento de arquivos.

Com as novas funções e ações de dados, este recurso fornecerá privilégios para toda a conta de armazenamento que substituem todas as permissões em ficheiros e pastas em todas as partilhas de ficheiros 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 utilizar esta funcionalidade, certifique-se de que tem permissões para aceder:

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 a 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 Azure RBAC. Para obter mais informações sobre como as funções internas são definidas, consulte Compreender as definições de função.

Lembre-se de que, para o tipo de recurso de partilha de ficheiros, o escopo RBAC correspondente utiliza shares no plano de controlo (operações de gestão), mas utiliza 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, isso 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

Quaisquer 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 evitar o acesso não intencional ou com privilégios excessivos aos Arquivos do Azure, implementamos verificações adicionais que exigem que os 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 de 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 cliente do Azure Identity simplifica o processo de obtenção de um token de acesso OAuth 2.0 para a autorização com o Microsoft Entra ID via o SDK Azure . As versões mais recentes das bibliotecas de cliente do Armazenamento do Azure para .NET, Java, Python, JavaScript e Go integram-se com as bibliotecas de Identidade do Azure para cada uma dessas linguagens para fornecer um meio simples e seguro de adquirir um token de acesso para autorização de solicitações do serviço de arquivo do Azure.

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

O token de acesso retornado pela biblioteca de cliente do Azure Identity é encapsulado em uma credencial de token. Em seguida, pode usar a credencial de token para obter um objeto cliente de serviço para usar 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 o Microsoft Entra ID e executar operações no nível de diretório e 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 tenta aceder a dados de ficheiros, o portal do Azure verifica primeiro se lhe foi atribuída uma função do Azure com Microsoft.Storage/storageAccounts/listkeys/action. Se lhe tiver sido atribuída uma função com esta ação, o portal do Azure utiliza a chave da conta para aceder aos dados do ficheiro através da autorização de chave partilhada. Se você não tiver recebido uma função com essa ação, o portal do Azure tentará acessar os dados usando 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 a recursos de arquivo, mas não concedem permissões a recursos de conta de armazenamento. Por esse motivo, o acesso ao portal também requer a atribuição de uma função ARM (Azure Resource Manager), como a função Leitor , com escopo para o 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 a dados de arquivo no portal do Azure.

Azure fornece extensões para PowerShell que permitem iniciar sessão e executar cmdlets do PowerShell usando credenciais do Microsoft Entra. Quando você entra no PowerShell com 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 em relação ao armazenamento de arquivos. Para operações suportadas, você não precisa mais passar uma chave de conta ou token SAS com o comando.

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

Operações suportadas

As extensões suportam apenas operações em dados de arquivo. As operações que um utilizador pode chamar dependem das permissões concedidas à entidade de segurança do Microsoft Entra com a qual iniciou sessão 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 contas de armazenamento e compartilhamentos de arquivos, 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 de 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 específicas do serviço de Arquivo, consulte Permissões para operações de chamada de dados.

Instalar o módulo Az.Storage

Este 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 o acesso aos dados do arquivo

Para autorizar o acesso aos dados do arquivo, siga estas etapas.

Entre na 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> pelos 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 sua chave de conta de armazenamento.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Obtenha o contexto da conta de armazenamento usando 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 OAuth, você deve passar explicitamente o -EnableFileBackupRequestIntent parâmetro para o New-AzStorageContext cmdlet. Se você não passar o parâmetro intent, 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 comandos principais da CLI do Azure, que são disponibilizados como parte do suporte da CLI para o OAuth através da interface REST, podem ser utilizados para autenticar e autorizar operações de dados em arquivos usando credenciais do Microsoft Entra.

Operações suportadas

Os comandos suportam apenas operações em dados de ficheiros. As operações que tu podes chamar dependem das permissões concedidas à entidade de segurança do Microsoft Entra com a qual iniciaste sessão na CLI do Azure.

A autenticação e autorização OAuth só funcionarão se o comando CLI for chamado com a --backup-intent opção ou --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 os grupos de comandos az storage file, az storage directory e az storage share list-handle e az storage share close-handle suportam autenticação e autorização OAuth. Para todas as outras operações em contas de armazenamento e compartilhamentos de arquivos, você deve usar a chave da conta de armazenamento ou o token SAS.

Pré-requisitos

Instalação e comandos de exemplo

Se ainda não tiver feito isso, instale a versão mais recente da CLI do Azure.

Autorizar o acesso aos dados do arquivo

Entre na sua conta do Azure.
```
az login
```
Crie 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 --auth modo como login e de passar o --backup-intent parâmetro.
```
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 cli são chamados usando o tipo de autenticação como login (--auth modelogin e --backup-intent parâmetro), 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 obter os comandos suportados:

Ver também

Escolher como autorizar o acesso a dados de ficheiros no portal do Azure

Comentários

Esta página foi útil?

Last updated on 2025-05-04