Acessar compartilhamentos de arquivos do Azure usando a ID do Microsoft Entra com o Azure Files OAuth sobre REST
O Azure Files OAuth sobre REST permite o acesso de leitura e gravação em nível de administrador a compartilhamentos de arquivos do Azure para usuários e aplicativos por meio do protocolo de autenticação OAuth, usando a ID do Microsoft Entra 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 das opções de autenticação baseada em identidade dos Arquivos do Azure para acesso SMB.
Limitações
O Azure Files OAuth sobre REST suporta apenas as APIs de Dados FileREST que suportam operações em ficheiros e diretórios. O OAuth não é suportado em APIs de plano de dados FilesREST que gerenciam recursos FileService e FileShare. Essas APIs de gerenciamento são chamadas usando a chave de conta de armazenamento ou o token SAS e são expostas por meio do plano de dados por motivos herdados. Recomendamos o uso das APIs do plano de controle (o provedor de recursos de armazenamento - Microsoft.Storage) que suportam OAuth para todas as atividades de gerenciamento relacionadas aos recursos FileService e FileShare.
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. 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 pela interface da 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 geridas
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 armazenamento pela autenticação OAuth e autorização para acessar compartilhamentos de arquivos do Azure com privilégios de leitura de tudo/gravação de tudo. 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, 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
Os usuários, grupos ou entidades de serviço que chamam a API REST com OAuth devem ter a readFileBackupSemantics ação 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 com Privilégios aos Dados dos Ficheiros de Armazenamento | Microsoft.Storage/storageAccounts/fileServices/fileShares/files/readMicrosoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action |
| Contribuidor com Privilégios aos Dados dos Ficheiros de Armazenamento | Microsoft.Storage/storageAccounts/fileServices/fileShares/files/readMicrosoft.Storage/storageAccounts/fileServices/fileShares/files/writeMicrosoft.Storage/storageAccounts/fileServices/fileShares/files/deleteMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/actionMicrosoft.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 Colaborador Elevado de Dados de Arquivo de Armazenamento SMB Share, 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 usuário, grupo ou entidade de serviço atribuída à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, grupo ou entidade de serviço terá:
- Storage File Data Privileged Reader: Acesso de leitura total 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.
- Contribuidor privilegiado de dados de arquivo de armazenamento: Leia, grave, modifique ACLs completas, exclua o acesso em todos os dados nos compartilhamentos de 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, esse recurso fornecerá privilégios de 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 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.
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 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 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 de 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, você pode usar a credencial de token para obter um objeto de cliente de serviço para usar na execução de operações autorizadas no serviço Arquivos do Azure.
Aqui está um código de exemplo:
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 do plano de dados FileREST
Você também pode autorizar o acesso a dados de arquivo usando o portal do Azure ou o Azure PowerShell.
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/actiono . 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 o esquema de autorização que está a ser utilizado quando navega para um contentor. 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.