Acede às partilhas de ficheiros SMB Azure usando identidades geridas com o Microsoft Entra ID

Os passos de habilitação descritos aqui são para VMs do Azure. Se pretender ativar uma identidade gerida em máquinas Windows que não estejam no Azure (on-premises ou noutra cloud), deve integrá-las no Azure Arc e atribuir-lhes uma identidade gerida. Também pode autenticar usando uma identidade de aplicação em vez de usar uma identidade gerida numa VM ou dispositivo Windows.

Ativar uma identidade gerida numa VM do Azure

A identidade gerida pode ser atribuída ao sistema ou ao utilizador. Se a VM tiver identidades geridas atribuídas pelo sistema e pelo utilizador, o Azure, por defeito, utiliza a identidade atribuída pelo sistema. Atribua apenas um para melhores resultados.

Habilitar uma identidade gerenciada atribuída ao sistema

Siga estes passos para ativar uma identidade gerida atribuída pelo sistema numa VM Windows a correr no Azure:

1. Inicie sessão no portal Azure e crie uma VM Windows. A sua VM deve correr o Windows Server 2019 ou versões posteriores para as versões do servidor, ou qualquer versão do cliente Windows. Veja Criar uma máquina virtual Windows no portal Azure.

2. Pode ativar uma identidade gerida atribuída pelo sistema durante a criação da VM no separador de Gestão.

   

Habilitar uma identidade gerenciada atribuída pelo usuário

1. Inicie sessão no portal Azure e siga os passos para criar uma identidade gerida atribuída pelo utilizador.

2. Vai até à identidade gerida atribuída ao utilizador que acabaste de criar e copia o valor do ID do Cliente. Vai precisar deste valor mais à frente.

Atribuir uma função RBAC integrada à identidade gerida ou identidade da aplicação

Depois de ativares uma identidade gerida, concede todas as permissões necessárias através do Azure RBAC. Para atribuir papéis, inicie sessão como utilizador com permissão para atribuir papéis no âmbito exigido.

Siga estes passos para atribuir o papel incorporado Azure RBAC Storage File Data SMB MI Admin. Esta função dá acesso ao nível de administrador para identidades geridas em ficheiros e diretórios no Ficheiros do Azure.

1. Vai à conta de storage que contém a partilha de ficheiros que queres montar usando uma identidade gerida. No menu de serviço, selecione Controlo de Acesso (IAM).

2. Em Conceda acesso a este recurso, selecione Adicionar atribuição de função.

3. No separador Funções, em Funções de Trabalho, pesquise e selecione Storage File Data SMB MI Admin. Depois, selecione Seguinte.

4. No separador Members, em Atribuir acesso a, selecione Managed Identity para identidades de VM ou Azure Arc. Para as identidades das aplicações, selecione Utilizador, grupo ou principal de serviço.

5. Em Membros, selecione + Selecione membros.

6. Para VMs Azure ou identidades Azure Arc, selecione a identidade gerida para a sua VM ou dispositivo Windows. Para as identidades das aplicações, pesquise e selecione a identidade da aplicação. Escolha Selecionar.

7. Verifique se a identidade gerida ou a identidade da aplicação está listada em Membros. Selecione Avançar.

8. Selecione Rever + atribuir para adicionar a função à conta de armazenamento.

Adicionar uma identidade gerida atribuída pelo utilizador a uma VM

Se criou uma identidade gerida atribuída pelo utilizador, siga estes passos para a adicionar à sua VM:

1. Vá para a sua máquina virtual. No menu de serviço, em Segurança, selecione Identidade.

2. Selecione o separador Atribuído pelo utilizador e depois selecione Adicionar identidade gerida do utilizador. Selecione a identidade gerida que criou e depois selecione Adicionar.

Para configurar uma identidade gerida numa VM Linux a correr no Azure, siga estes passos. A sua VM deve estar a correr Azure Linux 3.0, Ubuntu 22.04, Ubuntu 24.04, RHEL 9.6+ ou SLES 15 SP6+.

Ativar uma identidade gerida numa VM do Azure

A identidade gerida pode ser atribuída ao sistema ou ao utilizador. Se a VM tiver identidades geridas atribuídas pelo sistema e pelo utilizador, o Azure, por defeito, utiliza a identidade atribuída pelo sistema. Atribua apenas um para melhores resultados.

Habilitar uma identidade gerenciada atribuída ao sistema

1. Inicie sessão no portal Azure.

2. Pode ativar uma identidade gerida atribuída pelo sistema durante a criação da VM no separador Management. Consulte Criar uma máquina virtual Linux no portal Azure.

   

Habilitar uma identidade gerenciada atribuída pelo usuário

1. Inicie sessão no portal Azure e siga os passos para criar uma identidade gerida atribuída pelo utilizador.

2. Vai até à identidade gerida atribuída ao utilizador que acabaste de criar e copia o valor do ID do Cliente. Vai precisar deste valor mais à frente.

Atribuir uma função RBAC incorporada à identidade gerida

1. Vai à conta de storage que contém a partilha de ficheiros que queres montar usando uma identidade gerida. No menu de serviço, selecione Controlo de Acesso (IAM).

2. Em Conceda acesso a este recurso, selecione Adicionar atribuição de função.

3. No separador Funções, em Funções de Trabalho, pesquise e selecione Storage File Data SMB MI Admin. Depois, selecione Seguinte.

4. No separador Members, em Atribuir acesso a, selecione Identidade Gerida.

5. Em Membros, selecione + Selecione membros. O painel de Selecionar Identidades Geridas aparece.

6. Em Identidade Gerida, selecione a identidade gerida e depois selecione Selecionar.

7. Verifique se a identidade gerida está listada em Membros. Selecione Avançar.

8. Selecione Rever + atribuir para adicionar a função à conta de armazenamento.

Adicionar uma identidade gerida atribuída pelo utilizador a uma VM

Se criou uma identidade gerida atribuída pelo utilizador, siga estes passos para a adicionar à sua VM:

1. Vá para a sua máquina virtual. No menu de serviço, em Segurança, selecione Identidade.

2. Selecione o separador Atribuído pelo utilizador e depois selecione Adicionar identidade gerida do utilizador. Selecione a identidade gerida que criou e depois selecione Adicionar.

Para preparar a sua VM cliente ou dispositivo Windows para autenticar usando uma identidade gerida, siga estes passos:

1. Inicie sessão na sua VM ou dispositivo que tenha a identidade gerida atribuída e abra uma janela PowerShell como administrador. Precisas de PowerShell 5.1+ ou PowerShell 7+.

2. Instale o módulo PowerShell Ficheiros do Azure SMB Managed Identity Client e importe-o:

   Install-Module AzFilesSmbMIClient 
   Import-Module AzFilesSmbMIClient 
   

3. Verifique a sua política atual de execução PowerShell executando o seguinte comando:

   Get-ExecutionPolicy -List 
   

   Se a política de execução em CurrentUser for Restricted ou Undefined, altere-a para RemoteSigned. Se a política de execução for RemoteSigned, Default, AllSigned, Bypass, ou Unrestricted, pode saltar este passo.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 
   

Atualizar as credenciais de autenticação

Antes de poder montar a partilha de ficheiros usando a identidade gerida, atualize as credenciais de autenticação e especifique o endpoint da sua conta de storage. Para copiar o URI da sua conta de armazenamento, vá à conta de armazenamento no portal Azure e depois selecione Settings>Endpoints no menu de serviço. Certifique-se de copiar todo o URI, incluindo a barra final: https://<storage-account-name>.file.core.windows.net/.

Para uma identidade gerida atribuída pelo sistema, execute o seguinte comando para obter um token OAuth, inseri-lo na cache Kerberos e atualize automaticamente quando o token estiver perto de expirar. Podes opcionalmente omitir refresh.

AzFilesSmbMIClient.exe refresh --uri https://<storage-account-name>.file.core.windows.net/

Para uma identidade gerida atribuída pelo utilizador, é necessário especificar o ID do cliente. Substitua <client-id> pelo ID do cliente da identidade gerida.

AzFilesSmbMIClient.exe refresh --uri https://<storage-account-name>.file.core.windows.net/ --clientId <client-id> 

Para preparar a sua VM Linux para autenticar usando uma identidade gerida, siga estes passos.

Descarregue e instale os pacotes de autenticação

A localização do pacote e os passos de instalação variam consoante a sua distribuição Linux.

Azure Linux 3.0

Execute os seguintes comandos para instalar o azfilesauth no Azure Linux 3.0:

tdnf update 
tdnf install azfilesauth

RHEL 9.6+

Execute os seguintes comandos para instalar azfilesauth no RHEL 9.6+:

curl -sSL -O https://packages.microsoft.com/config/$(source /etc/os-release && echo "$ID/${VERSION_ID%%.*}")/packages-microsoft-prod.rpm
sudo rpm -i packages-microsoft-prod.rpm
rm packages-microsoft-prod.rpm
dnf update
dnf install -y azfilesauth

Por vezes, o RHEL pode bloquear o acesso de chamadas ascendentes do kernel ao ficheiro de cache de credenciais. Se ocorrer uma falha, ver /var/log/messages para possíveis causas.

O RHEL utiliza uma credencial persistente ou cache KCM por defeito. Pode mudar para uma cache baseada em ficheiros para azfilesauth:

  sudo tee /etc/krb5.conf.d/00-azfilesauth.conf > /dev/null <<EOF
  [libdefaults]
    default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  EOF

SLES 15 SP6+

Execute os seguintes comandos para instalar azfilesauth no SLES 15 SP6+:

curl -sSL -O https://packages.microsoft.com/config/sles/15/packages-microsoft-prod.rpm
sudo rpm -i packages-microsoft-prod.rpm
rm packages-microsoft-prod.rpm
sudo zypper refresh
sudo zypper install -y azfilesauth

O SLES 15 SP6+ utiliza uma credencial persistente ou cache KCM por defeito. Pode mudar para uma cache baseada em ficheiros para azfilesauth:

  sudo tee /etc/krb5.conf.d/00-azfilesauth.conf > /dev/null <<EOF
  [libdefaults]
    default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  EOF

Ubuntu 22,04

Execute os seguintes comandos para instalar azfilesauth no Ubuntu 22.04:

curl -sSL -O https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
# the above steps update the sources.list
sudo apt-get update
sudo apt-get install -y azfilesauth

Ubuntu 24,04

Execute os seguintes comandos para instalar azfilesauth no Ubuntu 24.04:

curl -sSL -O https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
# the above steps update the sources.list
sudo apt-get update
sudo apt-get install -y azfilesauth

Configurar a autenticação

Tens duas opções para configurar a autenticação no Linux:

• Use uma identidade gerida de VM: Selecione esta opção se a sua VM tiver uma identidade gerida atribuída.
• Fornece diretamente o token OAuth: Seleciona esta opção se estiveres a gerir tokens OAuth tu próprio.

Opção 1: Usar uma identidade gerida por VM

Pode usar uma identidade gerida atribuída pelo sistema ou pelo utilizador para configurar a autenticação.

Se a sua VM tiver uma identidade gerida atribuída pelo utilizador, execute o seguinte comando para obter um token do Azure Instance Metadata Service (IMDS) e armazená-lo automaticamente. Substitua <storage-account-name> pelo nome da sua conta de armazenamento. Substitua <client-id> pelo ID do cliente da sua identidade gerenciada. Se não tiveres o ID do cliente, vai à identidade gerida no portal do Azure e copia o ID do cliente.

sudo azfilesauthmanager set https://<storage-account-name>.file.core.windows.net --imds-client-id <client-id>

Se a sua VM tiver uma identidade gerida atribuída pelo sistema, use a --system flag e não forneça um ID de cliente:

sudo azfilesauthmanager set https://<storage-account-name>.file.core.windows.net --system

Verifique se o ticket foi criado corretamente:

sudo azfilesauthmanager list

Opção 2: Forneça diretamente o token OAuth

Se estiver a gerir os tokens você mesmo, forneça o token OAuth diretamente. O valor aud (audiência) para o token deve ser https://storage.azure.com (sem barra lateral para a frente) e não https://storage.azure.com/ para montar a partilha de ficheiros.

Execute os seguintes comandos. Substitui <storage-account-name> e <access-token> pelos teus valores.

# Insert the token into your credential cache
sudo azfilesauthmanager set https://<storage-account-name>.file.core.windows.net <access-token> 
# Verify the ticket is properly stored
sudo azfilesauthmanager list

Nos clientes Windows, pode aceder diretamente à sua partilha de ficheiros do Azure usando o caminho UNC, introduzindo o caminho seguinte no Explorador de Ficheiros do Windows. Substitua <storage-account-name> pelo nome da sua conta storage e <file-share-name> pelo nome de partilha de ficheiros.

\\<storage-account-name>.file.core.windows.net\<file-share-name>

Para mais informações, consulte Mount SMB Azure partilha de ficheiros em Windows.

Execute o seguinte comando para montar a partilha de ficheiros com as opções de montagem recomendadas. Substitua <storage-account-name> pelo nome da sua conta storage e <file-share-name> pelo nome de partilha de ficheiros. Pode encontrar o seu ID de credencial no seguinte ficheiro de configuração: cat /etc/azfilesauth/config.yaml. Para uma identidade gerida atribuída pelo utilizador, inclua o ID do cliente da identidade gerida usando a username=<client-id> opção mount. Para uma identidade gerida atribuída ao sistema, omita a opção de montagem username=<client-id>.

sudo mount -t cifs //<storage-account-name>.file.core.windows.net/<file-share-name> /mnt/smb -o sec=krb5,cruid=<credential-id>,username=<client-id>,dir_mode=0755,file_mode=0755,serverino,nosharesock,mfsymlinks,actimeo=30

Verifique se a montagem teve sucesso:

ls -la /mnt/smb

Para mais informações, consulte Montar partilhas de ficheiros SMB do Azure em clientes Linux.

Atualize suas credenciais

Para evitar interrupções de acesso, deve atualizar periodicamente as suas credenciais. O serviço de atualização deteta e renova automaticamente as credenciais conforme necessário.

Depois de montar o compartilhamento de ficheiros pela primeira vez, inicie o serviço de atualização:

sudo systemctl start azfilesrefresh

Para garantir que o serviço inicia automaticamente em cada arranque:

sudo systemctl enable --now azfilesrefresh

A atualização automática de credenciais requer uma identidade gerida atribuída à sua VM. Se estiver a fornecer diretamente o token OAuth, deve atualizar as credenciais manualmente usando o azfilesauthmanager set comando descrito em Configurar autenticação, ou programaticamente através das APIs da biblioteca partilhada.

Se encontrar problemas ao montar a sua partilha de ficheiros no Windows, siga estes passos para permitir registos detalhados e recolher informações de diagnóstico:

1. Nos clientes Windows, use o Editor do Registo para definir o nível Data para verbosidade para 0x00000004 (4) para Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\Storage\Files\SmbAuth.

2. Tenta montar a partilha novamente e reproduz o erro.

3. Agora deves ter um ficheiro chamado AzFilesSmbMILog.log. Envie o ficheiro de registo para a equipa Ficheiros do Azure para obter assistência.

Se encontrar problemas ao montar a sua partilha de ficheiros no Linux, siga estes passos de diagnóstico SMB.

Para os programadores que precisam integrar identidades geridas nas suas aplicações Windows, estão disponíveis múltiplas abordagens de implementação. A abordagem que escolhe depende da arquitetura e dos requisitos da sua aplicação.

Integração em assembly gerida: pacote NuGet

Para aplicações .NET, o pacote NuGet Microsoft.Azure.AzFilesSmbMI inclui um assembly gerido () que fornece acesso direto à funcionalidade de autenticação SMB OAuth. Use esta abordagem para aplicações baseadas em C# e outras baseadas em .NET.

Para instalar o conjunto, use Install-Package Microsoft.Azure.AzFilesSmbMI -version 1.2.3168.94.

Integração nativa de DLL

Para aplicações nativas que necessitam de acesso direto à API, o AzFilesSmbMIClient está disponível como DLL nativo. Esta opção é particularmente útil para aplicações ou sistemas C/C++ que necessitam de integração de nível inferior. Veja a implementação do Windows e a referência API (ficheiro de cabeçalho nativo).

Métodos nativos de API

A DLL nativa exporta os seguintes métodos essenciais para a gestão de credenciais:

extern "C" AZFILESSMBMI_API HRESULT SmbSetCredential( 
    _In_  PCWSTR pwszFileEndpointUri, 
    _In_  PCWSTR pwszOauthToken, 
    _In_  PCWSTR pwszClientID, 
    _Out_ PDWORD pdwCredentialExpiresInSeconds 
); 
extern "C" AZFILESSMBMI_API HRESULT SmbRefreshCredential( 
    _In_ PCWSTR pwszFileEndpointUri, 
    _In_ PCWSTR pwszClientID 
); 
extern "C" AZFILESSMBMI_API HRESULT SmbClearCredential( 
    _In_ PCWSTR pwszFileEndpointUri 
); 

Os programadores Linux podem usar a biblioteca partilhada que é automaticamente instalada com o azfilesauth pacote. Podes ligar à biblioteca nas tuas aplicações C/C++ para acesso direto à API.

Certifique-se de incluir o cabeçalho public.

Para mais informações, consulte o projeto AzFilesAuthenticator.

Métodos de API de bibliotecas partilhadas

A biblioteca partilhada exporta os seguintes métodos essenciais para a gestão de credenciais:

#ifdef __cplusplus
extern "C" {
#endif

int extern_smb_set_credential_oauth_token(char* file_endpoint_uri,
                                                char* auth_token,
                                                unsigned int* credential_expires_in_seconds);

int extern_smb_clear_credential(char* file_endpoint_uri);

int extern_smb_list_credential(bool is_json);

const char* extern_smb_version();

#ifdef __cplusplus
}
#endif

Descrição da API

A tabela seguinte lista os comandos da API e a sua utilização. Os valores devolvidos seguem as convenções padrão de C (zero para sucesso, não zero para erros).