Use identidade gerenciada em nível de banco de dados com Banco de Dados SQL do Azure (prévia)

Aplica-se a:Banco de Dados SQL do Azure

A identidade gerenciada em nível de banco de dados concede a um banco de dados individual no Banco de Dados SQL do Azure sua própria identidade gerenciada atribuída pelo usuário (UAMI). Um banco de dados que tenha isso se autentica no Armazenamento do Azure como ele mesmo, em vez de como o servidor lógico que o hospeda.

Sem uma identidade em nível de banco de dados, todo banco de dados em um servidor lógico compartilha a identidade gerenciada desse servidor, então todos acessam o mesmo armazenamento. Uma identidade em nível de banco de dados restringe esse acesso a um único banco de dados, então você pode conceder a cada banco apenas o armazenamento que ele precisa.

Você seleciona a identidade em uma credencial com escopo de banco de dados, a mesma credencial que consultas de virtualização de dados usam para ler arquivos Parquet, CSV e Delta do Armazenamento de Blobs do Azure ou Azure Data Lake Storage (ADLS) Gen2. Escolha entre dois valores de identidade de credencial:

Identidade de credencial Use-o quando
DATABASE MANAGED IDENTITY A conta de armazenamento está no mesmo tenant Microsoft Entra do banco de dados.
DATABASE FEDERATED CLIENT IDENTITY A conta de armazenamento está em um tenant diferente, acessado por meio de uma credencial de identidade federada (FIC).

Note

Como uma versão prévia do recurso, a tecnologia apresentada neste artigo está sujeita aos Termos de uso complementares para versões prévias do Microsoft Azure.

Prerequisites

  • Um Banco de Dados SQL do Azure em um servidor lógico. Todos os níveis de serviço e todas as regiões do Azure suportam esse recurso.
  • Uma identidade gerenciada atribuída pelo usuário na mesma assinatura. Para contextualizar, veja Identidades gerenciadas no Microsoft Entra para SQL do Azure.
  • Permissão para atribuir funções à conta de armazenamento alvo, como Proprietário ou Administrador de Acesso ao Usuário.
  • Uma conta Armazenamento de Blobs do Azure ou ADLS Gen2 contendo os arquivos que você deseja consultar.

Importante

Um banco de dados pode ter apenas uma identidade gerenciada atribuída pelo usuário no nível do banco de dados, ao contrário de um servidor lógico, que pode ter várias. Planeje a identidade para cada banco de dados antes de atribuí-la.

Se o banco de dados usa chaves gerenciadas pelo cliente no nível do banco de dados, ele já possui uma identidade no nível do banco de dados e, para chaves entre tenants, um ID federado de cliente. Esse recurso usa as mesmas duas configurações. Permita o acesso ao armazenamento à identidade ou aplicativo existente em vez de atribuir novos. Se você atribuir uma identidade ou um aplicativo diferente, primeiro dê acesso à chave de criptografia. Caso contrário, a atualização pode falhar ou o banco de dados pode perder acesso à sua chave.

Escolher o mesmo locatário ou entre locatários

Ambos os walkthroughs criam uma credencial com escopo de banco de dados e consultam dados externos. Eles diferem em como a identidade chega à conta de armazenamento.

Use uma identidade em nível de banco de dados no mesmo tenant

Passo 1: criar uma identidade gerida atribuída pelo utilizador

Crie a identidade e anote tanto seu ID de Recurso quanto seu ID de Objeto (principal). Você precisa do ID de Recurso para atribuir a identidade ao banco de dados. Você precisa do ID do Objeto (principal) apenas para o walkthrough entre locatários, onde ele identifica o sujeito da credencial de identidade federada.

az identity create \
    --name <identity-name> \
    --resource-group <resource-group> \
    --location <region>

Para outros métodos, veja Gerenciar identidades gerenciadas atribuídas pelo usuário.

Passo 2: Atribuir a identidade ao banco de dados

Atribua o UAMI ao banco de dados, não ao servidor lógico. Essa atribuição utiliza o mesmo mecanismo da criptografia transparente de dados (TDE) em nível de banco de dados com chaves gerenciadas pelo cliente, descritas em Chaves gerenciadas pelo cliente no nível do banco de dados. Para o conjunto completo de métodos de atribuição, veja Obter ou definir uma identidade gerenciada para um banco de dados.

Para atribuir a identidade no portal Azure:

  1. Vá ao seu banco de dados SQL.
  2. Em Segurança, selecione Identidade.
  3. Em Identidade Gerenciada Atribuída pelo Usuário, selecione Adicionar.
  4. Selecione a identidade que você criou e depois selecione Adicionar.
  5. Clique em Salvar.

Para atribuir a identidade com a CLI do Azure, use az sql db update:

az sql db update \
    --resource-group <resource-group> \
    --server <server-name> \
    --name <database-name> \
    --assign-identity \
    --user-assigned-identity-id <identity-resource-id>

Para atribuí-lo usando o PowerShell, use Set-AzSqlDatabase:

Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId>

A identidade ID do recurso se parece com /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>. Encontre em Propriedades na identidade gerenciada no portal Azure.

Passo 3: Conceda acesso à identidade ao armazenamento

Dê à identidade gerenciada acesso de leitura à conta de armazenamento:

  1. Acesse a conta de armazenamento.
  2. Selecione Controle de Acesso (IAM).
  3. Selecione Adicionar>Adicionar atribuição de função.
  4. Selecione a função Leitor de Dados de Blob de Armazenamento e então selecione Próximo.
  5. Em Atribuir acesso a, selecione Identidade Gerenciada.
  6. Selecione Selecionar membros, escolha sua identidade gerenciada atribuída pelo usuário e então selecione Selecionar.
  7. Selecione Examinar + atribuir.

Para acesso mais detalhado no ADLS Gen2, defina listas de controle de acesso (ACLs) em diretórios específicos em vez de atribuir um papel no nível da conta. Para mais informações, veja listas de controle de acesso no Azure Data Lake Storage.

Passo 4: Crie a credencial com escopo de banco de dados

Conecte-se ao seu banco de dados de usuários, não master, e crie a credencial:

CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';

Essa credencial não precisa de segredo nem de chave mestra de banco de dados. O mecanismo resolve a identidade atribuída ao banco de dados no momento da consulta.

O equivalente em nível de servidor usa um valor de identidade diferente. Comparar:

-- Server-level identity: every database on the logical server shares this access
CREATE DATABASE SCOPED CREDENTIAL MyServerIdentityCred
WITH IDENTITY = 'MANAGED IDENTITY';

-- Database-level identity: only this database has this access
CREATE DATABASE SCOPED CREDENTIAL MyDBIdentityCred
WITH IDENTITY = 'DATABASE MANAGED IDENTITY';

Para a sintaxe completa, veja CREATE DATABASE SCOPED CREDENTIAL.

Passo 5: Crie a fonte de dados externa

Crie uma fonte de dados externa que aponte para seu contêiner e anexe a credencial. Use o prefixo que corresponde ao tipo de armazenamento:

Tipo de armazenamento Prefixo de localização
Armazenamento de Blobs do Azure abs://
ADLS Gen2 adls:// 
CREATE EXTERNAL DATA SOURCE MyExternalStorage
WITH (
    LOCATION = 'abs://<container>@<storage-account>.blob.core.windows.net',
    CREDENTIAL = MyDBIdentityCred
);

Passo 6: Consultar os dados

Consulte os arquivos de forma ad hoc com OPENROWSET:

SELECT TOP 100 *
FROM OPENROWSET(
    BULK 'sales/2026/*.parquet',
    DATA_SOURCE = 'MyExternalStorage',
    FORMAT = 'parquet'
) AS externalData;

Ou defina uma tabela externa para consultas repetidas:

CREATE EXTERNAL FILE FORMAT ParquetFormat
WITH (FORMAT_TYPE = PARQUET);

CREATE EXTERNAL TABLE dbo.Sales
(
    OrderId int,
    OrderDate date,
    Amount decimal(10, 2)
)
WITH (
    LOCATION = 'sales/2026/',
    DATA_SOURCE = MyExternalStorage,
    FILE_FORMAT = ParquetFormat
);

SELECT TOP 100 * FROM dbo.Sales;

Use uma identidade de cliente federada entre os locatários

Use este caminho quando seu banco de dados estiver em um tenant e a conta de armazenamento em outro. Um registro de aplicativo multilocatário carrega a confiança entre eles: o UAMI do banco de dados é a entidade da credencial de identidade federada nesse aplicativo, e o locatário de armazenamento concede o acesso à entidade de serviço do aplicativo aos dados.

O padrão corresponde às chaves gerenciadas pelo cliente entre locatários para criptografia de dados transparente, então a configuração parece familiar se você já usa esse recurso.

Passo 1: Registrar uma aplicação multitenant

No tenant que contém o banco de dados, registre uma aplicação multitenant no Microsoft Entra ID e anote seu ID de aplicação (cliente).

Para obter mais informações, consulte Registrar um aplicativo na plataforma de identidade da Microsoft.

Passo 2: Adicionar uma credencial de identidade federada

Adicione uma credencial de identidade federada a esse aplicativo para que confie na identidade gerenciada atribuída ao usuário do banco de dados. O aplicativo e a identidade gerenciada devem pertencer ao mesmo tenant do Microsoft Entra.

  1. No registro do aplicativo, selecione Certificados & Segredos>Credenciais federadas>Adicionar credencial.
  2. Para o cenário de credencial federada, selecione Identidade Gerenciada.
  3. Selecione a identidade gerenciada que você criou na Etapa 1 do walkthrough do mesmo locatário.
  4. Verifique se o Emissor preenchido automaticamente identifica o locatário. Para a nuvem pública do Azure, o emissor é https://login.microsoftonline.com/<tenant-id>/v2.0.
  5. Certifique-se de que a Audiência seja api://AzureADTokenExchange, o valor para a nuvem pública do Azure.
  6. Insira um nome único para a credencial e depois salve-a.

O sujeito da credencial é o ID de Objeto (principal) da identidade gerenciada, não seu ID de cliente. Se você configurar a credencial manualmente, copie a ID do Objeto (entidade) exata, porque a entidade diferencia maiúsculas de minúsculas. O Microsoft Entra ID aceita valores incorretos de emissor, entidade ou audiência quando você salva a credencial, mas a troca de tokens falha depois.

Para mais informações, veja Configurar uma aplicação para confiar em uma identidade gerenciada.

No tenant que detém a conta de armazenamento:

  1. Um administrador concede consentimento ao aplicativo multilocatário, que cria um service principal nesse locatário.
  2. Atribua a função Storage Blob Data Reader a esse service principal na conta de armazenamento. Siga o Passo 3: Conceda à identidade acesso ao armazenamento, mas para Atribuir acesso, selecione Usuário, grupo ou principal de serviço e, em seguida, selecione o principal de serviço do aplicativo.

Passo 4: Defina o ID do cliente federado no banco de dados

No tenant que contém o banco de dados, atribua a identidade gerenciada atribuída pelo usuário ao banco de dados e defina o ID da Aplicação (cliente) do Passo 1 como o ID Federado do Cliente:

  1. Vá ao seu banco de dados SQL.
  2. Em Segurança, selecione Identidade.
  3. Em Identidade Gerenciada Atribuída pelo Usuário, verifique se a identidade da Etapa 1 do walkthrough do mesmo tenant está listada. Se não estiver, selecione Adicionar, selecione a identidade digital e depois selecione Adicionar.
  4. Em identidade federada do cliente, selecione o aplicativo e depois selecione Salvar.

Para configurá-lo com a CLI do Azure:

az sql db update \
    --resource-group <resource-group> \
    --server <server-name> \
    --name <database-name> \
    --assign-identity \
    --user-assigned-identity-id <identity-resource-id> \
    --federated-client-id <application-client-id>

Para configurá-lo com PowerShell:

Set-AzSqlDatabase -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -DatabaseName <DatabaseName> -AssignIdentity -UserAssignedIdentityId <UserAssignedIdentityId> -FederatedClientId <ApplicationClientId>

Passo 5: Crie a credencial e faça a consulta

CREATE DATABASE SCOPED CREDENTIAL MyCrossTenantCred
WITH IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY';

CREATE EXTERNAL DATA SOURCE PartnerStorage
WITH (
    LOCATION = 'adls://<container>@<storage-account>.dfs.core.windows.net',
    CREDENTIAL = MyCrossTenantCred
);

Depois, crie uma tabela externa ou execute OPENROWSET em PartnerStorage exatamente como no Passo 6: Consultar os dados.

Comparar identidades em nível de servidor e de banco de dados

Característica Identidade gerenciada em nível de servidor Identidade gerenciada em nível de banco de dados
Escopo de identidade Servidor lógico Banco de dados único
Sintaxe de credenciais IDENTITY = 'MANAGED IDENTITY' IDENTITY = 'DATABASE MANAGED IDENTITY'
Acesso de armazenamento entre locatários Sem suporte. Use uma assinatura de acesso compartilhado (SAS) em vez disso ID de cliente federado definido no banco de dados, usado com IDENTITY = 'DATABASE FEDERATED CLIENT IDENTITY'
Granularidade do RBAC de armazenamento Uma identidade para cada banco de dados no servidor Uma identidade por banco de dados
Escopo de exposição Cada banco de dados no servidor compartilha o acesso Limitado a um único banco de dados
Tipos de identidade Atribuído pelo sistema ou atribuído pelo usuário Somente atribuído pelo usuário
Chave mestra do banco de dados necessária No No

Ambos os tipos de credenciais podem coexistir no mesmo servidor lógico e dentro de seus bancos de dados. Escolha a credencial que melhor se encaixa nas suas necessidades de segurança.

Geo-replicação e failover

Você atribui a identidade a um banco de dados, então cada réplica carrega sua própria atribuição. Configure a secundária geográfica da mesma forma que a primária antes de fazer failover:

  • Atribua a mesma identidade gerenciada atribuída pelo usuário que o principal usa ao banco de dados secundário.
  • Conceda a essa identidade o mesmo acesso de armazenamento descrito na Etapa 3: Permitir acesso à identidade para armazenamento.
  • Para acesso entre locatários, defina a mesma identidade de cliente federado no banco de dados secundário.

Quando você configura ambas as réplicas dessa forma, consultas que usam credenciais com escopo de banco de dados continuam funcionando após um failover. O requisito corresponde às chaves gerenciadas pelo cliente em nível de banco de dados, que também precisam da identidade em cada réplica.

A mesma configuração se aplica tanto à geo-replicação ativa quanto aos grupos de failover.

Limitations

  • Apenas Banco de Dados SQL do Azure. Instância Gerenciada de SQL do Azure, SQL Server e Azure Synapse Analytics não suportam essas identidades de credenciais.
  • Apenas autenticação de saída. Esse recurso não altera a forma como usuários e aplicativos se autenticam no banco de dados.
  • Não é suportado no master banco de datos. Crie a credencial em um banco de dados de usuários.
  • Apenas identidades gerenciadas atribuídas pelo usuário. Uma identidade gerenciada atribuída pelo sistema tem escopo no servidor lógico, então não pode atuar como uma identidade em nível de banco de dados.
  • Uma identidade gerenciada atribuída pelo usuário por banco de dados.
  • Esta prévia cobre apenas virtualização de dados: CREATE EXTERNAL TABLE e OPENROWSET com DATA_SOURCE. Outros recursos de saída, como sp_invoke_external_rest_endpoint, não estão dentro do escopo.

Troubleshoot

Criar uma credencial com escopo de banco de dados não confirma se a identidade do banco de dados pode obter um token ou acessar armazenamento. Erros aparecem depois, quando você cria uma fonte de dados externa ou executa uma consulta que usa a credencial.

Identidade do banco de dados não configurada (erro 15858)

Você pode criar uma credencial com IDENTITY = 'DATABASE MANAGED IDENTITY' antes de atribuir uma identidade gerenciada atribuída pelo usuário ao banco de dados. Se uma consulta então usa a credencial e o banco de dados não tem uma identidade com a qual obter um token, a consulta falha com o erro 15858:

Cannot obtain a Microsoft Entra ID token to access storage. Error message: 'Azure SQL Server or Database identity is not configured. Please follow the steps in "Assign a Microsoft Entra managed identity to your Azure SQL" (https://aka.ms/SQLDBMSI)'.

Atribua uma identidade gerenciada atribuída pelo usuário ao banco de dados, conforme descrito na Etapa 2, dê acesso à conta de armazenamento e então tente novamente a consulta. Atribuir uma identidade apenas ao servidor lógico não configura uma identidade em nível de banco de dados. Se a atribuição de banco de dados estiver configurada e o erro persistir, entre em contato com o Suporte da Microsoft para investigar o provisionamento de identidade de banco de dados.

Note

Trace flag 4675 e a etapa de exclusão e recriação no Backup e restauração para URL usando identidades gerenciadas se aplicam ao SQL Server em VMs do Azure. Eles não se aplicam à identidade gerenciada em nível de banco de dados no Banco de Dados SQL do Azure.

Credencial não pode ser encontrada ou referenciada (erro 46516)

Quando você cria uma fonte de dados externa, o Banco de Dados SQL do Azure verifica se a credencial existe no banco de dados atual e se você tem permissão para referenciá-la. Se qualquer uma das verificações falhar, você recebe o erro 46516:

The specified credential cannot be found or the user does not have permission to perform this action.

Crie a credencial no banco de dados que contém a fonte externa de dados, verifique o nome da credencial e certifique-se de que você tem permissão para referenciar a credencial.

Falha na aquisição de tokens (erro 15858)

Quando o banco de dados não consegue obter um token Microsoft Entra e o provedor de token retorna um motivo, o erro 15858 inclui esse motivo:

Cannot obtain a Microsoft Entra ID token to access storage. Error message: '<details>'.

Use a mensagem de erro aninhada para descobrir por que a solicitação do token falhou. Para acesso entre locatários, verifique a aplicação, o consentimento do administrador no locatário de armazenamento e a credencial de identidade federada, conforme descrito em Configurar uma aplicação para confiar em uma identidade gerenciada.

Para ler dados externos, a identidade também precisa de uma função de dados de armazenamento. Para fins de acesso no mesmo locatário, conceda ao Leitor de Dados de Blob de Armazenamento, no contêiner ou na conta de armazenamento, à identidade gerenciada atribuída ao usuário do banco de dados. Para acesso entre locatários, conceda-o ao principal de serviço da aplicação no tenant de armazenamento. Para obter mais informações, consulte Atribuir uma função do Azure para acesso aos dados de blob.

Arquivo não existe ou não pode ser acessado (erro 4860)

Quando um arquivo está faltando ou não pode ser lido, você recebe o erro 4860:

Cannot bulk load. The file "<path>" does not exist or you don't have file access rights. See https://go.microsoft.com/fwlink/?LinkId=2374938 for more information.

Verifique se o arquivo existe no local configurado. Depois, verifique se a identidade usada pela requisição pode acessá-la, por meio de uma função de dados de armazenamento ou, para ADLS Gen2, listas de controle de acesso (ACLs) no caminho.

O acesso à rede está bloqueado (erros 42121 e 16539)

Quando o servidor lógico está associado a um perímetro de segurança de rede que não permite tráfego de saída para a conta de armazenamento, você recebe o erro 42121:

The operation could not be completed because attempts to connect were denied by the configured Network Security Perimeter.

Adicione uma regra de acesso de saída para o nome do host da conta de armazenamento ao perfil do perímetro, ou associe a conta de armazenamento ao mesmo perímetro. Para mais informações, veja Perímetro de Segurança de Rede para Banco de Dados SQL do Azure.

Quando a rede de saída é restrita no servidor lógico e a conta de armazenamento não está nas regras de firewall de saída do servidor, você recebe o erro 16539:

Operation failed since the external data source '<external-data-source>' has underlying storage account that is not in the list of Outbound Firewall Rules on the server. Please add this storage account to the list of Outbound Firewall Rules on your server and retry the operation.

Adicione uma regra de firewall de saída para o nome exato do host de armazenamento na localização da fonte de dados externa. Para mais informações, veja Regras de firewall Outbound para Banco de Dados SQL do Azure e Azure Synapse Analytics.

A configuração entre locatários está ausente ou incorreta (erros 16561 e 16562)

Uma consulta entre locatários pode falhar com qualquer um desses erros, ou com o erro 4860:

External table '<table-name>' is not accessible because content of directory cannot be listed.

External table '<table-name>' is not accessible because location does not exist or it is used by another process.

Esses erros significam que a consulta não conseguiu acessar os arquivos. A identidade pode não ter o papel de armazenamento necessário, o acesso à rede pode estar bloqueado, o local de armazenamento pode não ser resolvido, ou o token pode ser do tenant errado. Para corrigi-lo:

  • Conceda a função apropriada de dados de armazenamento.
  • Permita acesso de rede à conta de armazenamento.
  • Inclua o contêiner na localização externa da fonte de dados.
  • Use DATABASE FEDERATED CLIENT IDENTITY, e defina o ID Federado do Cliente no banco de dados, conforme descrito na Etapa 4.
  • Confirme se a entidade da credencial de identidade federada corresponde exatamente à ID de Objeto (entidade) da identidade gerenciada.

Consultas falham após um failover

Se as consultas falharem com erros de token ou autorização após um failover, a nova primária pode não ter a mesma identidade gerenciada atribuída pelo usuário que a primária original usou. Ou essa identidade pode não ter uma atribuição de função na conta de armazenamento. Atribua a mesma identidade a ambas as réplicas e conceda acesso ao armazenamento, conforme descrito em Geo-replicação e failover.

Perguntas frequentes

Credenciais em nível de servidor e banco de dados podem coexistir no mesmo servidor?

Sim, no mesmo servidor lógico e no mesmo banco de dados. O valor de IDENTITY de cada credencial determina qual identidade uma consulta usa: MANAGED IDENTITY usa a identidade do servidor, e DATABASE MANAGED IDENTITY usa a identidade do banco de dados.

Posso usar uma identidade gerenciada atribuída ao sistema?

Não. Uma identidade gerenciada atribuída ao sistema pertence ao servidor lógico, então você não pode escopá-la em um único banco de dados. Use uma identidade gerenciada atribuída pelo usuário.

Quais níveis de serviço e regiões suportam essa prévia?

Todos os níveis de serviço do Banco de Dados SQL do Azure, em todas as regiões do Azure.

Preciso de uma chave mestra de banco de dados?

Não. DATABASE MANAGED IDENTITY e DATABASE FEDERATED CLIENT IDENTITY não aceitam um segredo; então, não é necessário ter uma chave mestra.

Esse recurso funciona com sp_invoke_external_rest_endpoint?

Não nesta prévia. A versão prévia aborda a virtualização de dados.

Conteúdo relacionado

  • Última atualização em