Autorize o acesso a blobs e arquivos com o AzCopy e o Microsoft Entra ID

Você pode fornecer o AzCopy com credenciais de autorização usando o Microsoft Entra ID. Dessa forma, você não precisará acrescentar um token de assinatura de acesso compartilhado (SAS) a cada comando.

Comece verificando suas atribuições de função. Em seguida, escolha o tipo de entidade de segurança que você deseja autorizar. Uma identidade de usuário, uma identidade gerenciadae uma entidade de serviço são cada uma um tipo de entidade de segurança.

Para autorizar o acesso, você definirá as variáveis de ambiente na memória. Em seguida, execute qualquer comando AzCopy. O AzCopy recuperará o token de autenticação necessário para concluir a operação. Após a conclusão da operação, o token desaparece da memória.

O AzCopy recupera o token OAuth usando as credenciais que você fornece. Como alternativa, o AzCopy pode usar o token OAuth de uma sessão ativa da CLI do Azure ou do Azure PowerShell.

Para obter mais informações sobre o AzCopy, consulte Introdução ao AzCopy.

Verificar atribuições de função

O nível de autorização de que você precisa é baseado em se você planeja carregar arquivos ou apenas baixá-los.

Se você quiser apenas baixar arquivos, verifique se a função de Leitor de Dados de Blob de Armazenamento (Armazenamento de Blobs do Azure) ou a de Leitor Privilegiado de Dados de Arquivo de Armazenamento (Arquivos do Azure) foi atribuída à sua identidade de usuário, identidade gerenciada ou entidade de serviço.

Se você quiser carregar arquivos, verifique se uma dessas funções foi atribuída à sua entidade de segurança.

• Colaborador de dados de blob de armazenamento
• Proprietário de Dados do Blob de Armazenamento

Se você quiser carregar arquivos em um compartilhamento de arquivos do Azure, verifique se a Leitor Privilegiado de Dados de Arquivo de Armazenamento foi atribuída à sua entidade de segurança.

Essas funções podem ser atribuídas à entidade de segurança em qualquer um desses escopos:

• Contêiner (sistema de arquivo) ou compartilhamento de arquivo
• Conta de armazenamento
• Resource group
• Subscription

Para saber como verificar e atribuir funções, consulte Atribuir uma função do Azure para acesso a dados de blob(Armazenamento de Blobs) ou Escolha como autorizar o acesso aos dados de arquivo no portal do Azure (Arquivos do Azure).

Você não precisará ter uma dessas funções atribuídas à entidade de segurança se sua entidade de segurança for adicionada à lista de controle de acesso (ACL) do contêiner ou diretório de destino. Na ACL, sua entidade de segurança precisa de permissão de gravação no diretório de destino e permissão de execução no contêiner e em cada diretório pai.

Para saber mais, consulte Modelo de controle de acesso no Azure Data Lake Storage.

Autorizar com o AzCopy

O AzCopy usa as credenciais que você fornece para autorizar a entidade de segurança.

Autorizar uma identidade de usuário

Depois de verificar se a identidade do usuário recebeu o nível de autorização necessário, digite o comando a seguir e pressione a tecla ENTER.

export AZCOPY_AUTO_LOGIN_TYPE=DEVICE

Em seguida, execute qualquer comando azcopy (por exemplo: azcopy list https://contoso.blob.core.windows.net).

Esse comando retorna um código de autenticação e a URL de um site. Abra o site, forneça o código e, em seguida, escolha o botão Avançar.

Uma janela de entrada será exibida. Nessa janela, entre em sua conta do Azure usando suas credenciais de conta do Azure. Depois de se conectar com êxito, a operação pode ser concluída.

Autorizar uma identidade gerenciada

Essa é uma ótima opção se você planeja usar o AzCopy dentro de um script que é executado sem interação do usuário e o script é executado de uma Máquina Virtual (VM) do Azure. Ao usar essa opção, você não precisará armazenar nenhuma credencial na VM.

Você pode entrar em sua conta usando uma identidade gerenciada de todo o sistema que você habilitou em sua VM ou usando a ID do cliente, a ID de objeto ou a ID de recurso de uma identidade gerenciada atribuída pelo usuário que você atribuiu a sua VM.

Para saber mais sobre como habilitar uma identidade gerenciada em todo o sistema ou criar uma identidade gerenciada atribuída pelo usuário, consulte Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure.

Autorizar usando uma identidade gerenciada em todo o sistema

Primeiro, verifique se você habilitou uma identidade gerenciada em todo o sistema em sua VM. Consulte Identidade Gerenciada atribuída pelo sistema.

Digite o comando a seguir e pressione a tecla ENTER.

export AZCOPY_AUTO_LOGIN_TYPE=MSI

Em seguida, execute qualquer comando azcopy (por exemplo: azcopy list https://contoso.blob.core.windows.net).

Autorizar usando uma identidade gerenciada atribuída pelo usuário

Primeiro, verifique se você habilitou uma identidade gerenciada atribuída pelo usuário em sua VM. Consulte Identidade gerenciada atribuída pelo usuário.

Digite o comando a seguir e pressione a tecla ENTER.

export AZCOPY_AUTO_LOGIN_TYPE=MSI

Em seguida, digite qualquer um dos comandos a seguir e pressione a tecla ENTER.

export AZCOPY_MSI_CLIENT_ID=<client-id>

Substitua o espaço reservado <client-id> pela ID do cliente da identidade gerenciada atribuída pelo usuário.

export AZCOPY_MSI_OBJECT_ID=<object-id>

Substitua o espaço reservado <object-id> pela ID do objeto da identidade gerenciada atribuída pelo usuário.

export AZCOPY_MSI_RESOURCE_STRING=<resource-id>

Substitua o espaço reservado <resource-id> pela ID do recurso da identidade gerenciada atribuída pelo usuário.

Depois de definir essas variáveis, você pode executar qualquer comando azcopy (por exemplo: azcopy list https://contoso.blob.core.windows.net).

Autorizar uma entidade de serviço

Essa é uma ótima opção se você planeja usar o AzCopy dentro de um script que é executado sem interação do usuário, especialmente quando executado no local. Se você planeja executar o AzCopy em VMs que são executadas no Azure, uma identidade de serviço gerenciada é mais fácil de administrar. Para saber mais, consulte a seção Autorizar uma identidade gerenciada deste artigo.

Você pode entrar em sua conta usando um segredo do cliente ou usando a senha de um certificado associado ao registro do aplicativo da sua entidade de serviço.

Para saber mais sobre a criação de uma entidade de serviço, confira Como usar o portal para criar um aplicativo e uma entidade de serviço do Microsoft Entra que podem acessar recursos.

Para saber mais sobre entidades de serviço em geral, consulte Objetos de aplicativo e de entidade de serviço no Microsoft Entra ID

Autorizar uma entidade de serviço usando um segredo do cliente

Digite o comando a seguir e pressione a tecla ENTER.

export AZCOPY_AUTO_LOGIN_TYPE=SPN
export AZCOPY_SPA_APPLICATION_ID=<application-id>
export AZCOPY_SPA_CLIENT_SECRET=<client-secret>
export AZCOPY_TENANT_ID=<tenant-id>

Substitua o espaço reservado <application-id> pela ID do aplicativo do registro do aplicativo da sua entidade de serviço. Substitua o espaço reservado <client-secret> pelo segredo do cliente. Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence. Para encontrar a ID do locatário, selecione Propriedades do locatário > ID do Locatário no portal do Azure.

Em seguida, execute qualquer comando azcopy (por exemplo: azcopy list https://contoso.blob.core.windows.net).

Autorizar uma entidade de serviço usando um certificado

Se preferir usar suas próprias credenciais para autorização, você poderá carregar um certificado para o registro do aplicativo e, em seguida, usar esse certificado para fazer logon.

Além de carregar seu certificado para o registro do aplicativo, você também precisará ter uma cópia do certificado salvo no computador ou na VM em que o AzCopy será executado. Essa cópia do certificado deve estar em formato .PFX ou .PEM e deve incluir a chave privada. A chave privada deve ser protegida por senha. Se você estiver usando o Windows e seu certificado existir somente em um repositório de certificados, certifique-se de exportar esse certificado para um arquivo PFX (incluindo a chave privada). Para obter diretrizes, consulte Export-PfxCertificate

Digite o comando a seguir e pressione a tecla ENTER.

export AZCOPY_AUTO_LOGIN_TYPE=SPN
export AZCOPY_SPA_APPLICATION_ID=<application-id>
export AZCOPY_SPA_CERT_PATH=<path-to-certificate-file>
export AZCOPY_SPA_CERT_PASSWORD=<certificate-password>
export AZCOPY_TENANT_ID=<tenant-id>

Substitua o espaço reservado <application-id> pela ID do aplicativo do registro do aplicativo da sua entidade de serviço. Substitua o espaço reservado <path-to-certificate-file> pelo caminho relativa ou totalmente qualificado para o arquivo de certificado. O AzCopy salva o caminho para esse certificado, mas não salva uma cópia do certificado. Portanto, certifique-se de manter esse certificado em vigor. Substitua o espaço reservado <certificate-password> pela senha do certificado. Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence. Para encontrar a ID do locatário, selecione Propriedades do locatário > ID do Locatário no portal do Azure.

Em seguida, execute qualquer comando azcopy (por exemplo: azcopy list https://contoso.blob.core.windows.net).

Autorizar usando o comando de logon do AzCopy

Como alternativa ao uso de variáveis na memória, você pode autorizar o acesso usando o comando de logon do AzCopy.

O comando de logon do AzCopy recupera um token OAuth e, em seguida, coloca esse token em um repositório secreto no seu sistema. Se o seu sistema operacional não tiver um repositório secreto, como um keyring do Linux, o comando de logon do AzCopy não funcionará porque não há lugar para posicionar o token.

Autorizar uma identidade de usuário (comando de logon do AzCopy)

Depois de verificar se a identidade do usuário recebeu o nível de autorização necessário, abra um prompt de comando, digite o comando a seguir e pressione a tecla ENTER.

azcopy login

Se você receber um erro, tente incluir a ID de locatário da organização à qual a conta de armazenamento pertence.

azcopy login --tenant-id=<tenant-id>

Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence. Para encontrar a ID do locatário, selecione Propriedades do locatário > ID do Locatário no portal do Azure.

Esse comando retorna um código de autenticação e a URL de um site. Abra o site, forneça o código e, em seguida, escolha o botão Avançar.

Uma janela de entrada será exibida. Nessa janela, entre em sua conta do Azure usando suas credenciais de conta do Azure. Depois de entrar com êxito, feche a janela do navegador e comece a usar o AzCopy.

Autorizar usando uma identidade gerenciada em todo o sistema (comando de logon do AzCopy)

Primeiro, verifique se você habilitou uma identidade gerenciada em todo o sistema em sua VM. Consulte Identidade Gerenciada atribuída pelo sistema.

Em seguida, no console de comando, digite o comando a seguir e pressione a tecla ENTER.

azcopy login --identity

Autorizar usando uma identidade gerenciada atribuída pelo usuário (comando de logon do AzCopy)

Primeiro, verifique se você habilitou uma identidade gerenciada atribuída pelo usuário em sua VM. Consulte Identidade gerenciada atribuída pelo usuário.

Em seguida, no console de comando, digite qualquer um dos comandos a seguir e pressione a tecla ENTER.

azcopy login --identity --identity-client-id "<client-id>"

Substitua o espaço reservado <client-id> pela ID do cliente da identidade gerenciada atribuída pelo usuário.

azcopy login --identity --identity-object-id "<object-id>"

Substitua o espaço reservado <object-id> pela ID do objeto da identidade gerenciada atribuída pelo usuário.

azcopy login --identity --identity-resource-id "<resource-id>"

Substitua o espaço reservado <resource-id> pela ID do recurso da identidade gerenciada atribuída pelo usuário.

Autorizar uma entidade de serviço (comando de logon do AzCopy)

Antes de executar um script, você precisa entrar interativamente pelo menos uma vez para que possa fornecer ao AzCopy as credenciais de sua entidade de serviço. Essas credenciais são armazenadas em um arquivo seguro e criptografado para que o script não precise fornecer essas informações confidenciais.

Você pode entrar em sua conta usando um segredo do cliente ou usando a senha de um certificado associado ao registro do aplicativo da sua entidade de serviço.

Para saber mais sobre a criação de uma entidade de serviço, confira Como usar o portal para criar um aplicativo e uma entidade de serviço do Microsoft Entra que podem acessar recursos.

Autorizar uma entidade de serviço usando um segredo do cliente (comando de logon do AzCopy)

Comece definindo a AZCOPY_SPA_CLIENT_SECRET variável de ambiente como o segredo do cliente do registro do aplicativo da sua entidade de serviço.

Este exemplo mostra como você pode fazer isso no PowerShell.

$env:AZCOPY_SPA_CLIENT_SECRET="$(Read-Host -prompt "Enter key")"

Em seguida, digite o comando a seguir e pressione a tecla ENTER.

azcopy login --service-principal  --application-id application-id --tenant-id=tenant-id

Substitua o espaço reservado <application-id> pela ID do aplicativo do registro do aplicativo da sua entidade de serviço. Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence. Para encontrar a ID do locatário, selecione Propriedades do locatário > ID do Locatário no portal do Azure.

Autorizar uma entidade de serviço usando um certificado (comando de logon do AzCopy)

Se preferir usar suas próprias credenciais para autorização, você poderá carregar um certificado para o registro do aplicativo e, em seguida, usar esse certificado para fazer logon.

Além de carregar seu certificado para o registro do aplicativo, você também precisará ter uma cópia do certificado salvo no computador ou na VM em que o AzCopy será executado. Essa cópia do certificado deve estar em formato .PFX ou .PEM e deve incluir a chave privada. A chave privada deve ser protegida por senha. Se você estiver usando o Windows e seu certificado existir somente em um repositório de certificados, certifique-se de exportar esse certificado para um arquivo PFX (incluindo a chave privada). Para obter diretrizes, consulte Export-PfxCertificate

Em seguida, defina a AZCOPY_SPA_CERT_PASSWORD variável de ambiente como a senha do certificado.

Este exemplo mostra como você pode executar essa tarefa no PowerShell.

$env:AZCOPY_SPA_CERT_PASSWORD="$(Read-Host -prompt "Enter key")"

Em seguida, digite o comando a seguir e pressione a tecla ENTER.

azcopy login --service-principal --application-id application-id --certificate-path <path-to-certificate-file> --tenant-id=<tenant-id>

Substitua o espaço reservado <application-id> pela ID do aplicativo do registro do aplicativo da sua entidade de serviço. Substitua o espaço reservado <path-to-certificate-file> pelo caminho relativa ou totalmente qualificado para o arquivo de certificado. O AzCopy salva o caminho para esse certificado, mas não salva uma cópia do certificado. Portanto, certifique-se de manter esse certificado em vigor. Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence. Para encontrar a ID do locatário, selecione Propriedades do locatário > ID do Locatário no portal do Azure.

Autorizar com a CLI do Azure

Se você entrar usando a CLI do Azure, ela obterá um token OAuth que o AzCopy pode usar para autorizar operações.

Para habilitar o AzCopy a usar esse token, digite o comando a seguir e pressione a tecla ENTER.

export AZCOPY_AUTO_LOGIN_TYPE=AZCLI

Para obter mais informações sobre como entrar com a CLI do Azure, consulte Entrar com a CLIdo Azure.

Autorizar com o Azure PowerShell

Se você entrar usando o Azure PowerShell, o Azure PowerShell obterá um token OAuth que o AzCopy pode usar para autorizar operações.

Para habilitar o AzCopy a usar esse token, digite o comando a seguir e pressione a tecla ENTER.

$Env:AZCOPY_AUTO_LOGIN_TYPE="PSCRED"

Para obter mais informações sobre como entrar com o Azure PowerShell, confira Entrar com o Azure PowerShell.

Próximas etapas

• Para obter mais informações sobre o AzCopy, consulte Introdução ao AzCopy

• Se você tiver dúvidas, problemas ou comentários gerais, envie-os na página do GitHub.