Compartilhar via

Tutorial: Como conectar um aplicativo de Serviço de Aplicativo ao Banco de Dados SQL em nome do usuário conectado

  • Artigo

Este tutorial mostra como habilitar a autenticação internaem um aplicativo do Serviço de Aplicativo usando o provedor de autenticação do Microsoft Entra e, em seguida, estendê-la conectando-a a um banco de dados SQL do Azure de back-end representando o usuário conectado (também conhecido como o fluxo em nome de). Essa é uma abordagem de conectividade mais avançada para o Tutorial: acessar dados com identidade gerenciada e tem as seguintes vantagens em cenários corporativos:

  • Elimina os segredos de conexão para serviços de back-end, assim como a abordagem de identidade gerenciada.
  • Fornece ao banco de dados de back-end (ou qualquer outro serviço do Azure) mais controle sobre a quem ou quanto de acesso conceder aos seus dados e funcionalidades.
  • Permite que o aplicativo adapte sua apresentação de dados para o usuário conectado.

Neste tutorial, você adiciona a autenticação do Microsoft Entra ao aplicativo Web de exemplo implantado em um dos seguintes tutoriais:

Quando você terminar, seu aplicativo de exemplo autenticará os usuários conectados ao Banco de Dados SQL com segurança em nome do usuário conectado.

Diagrama de arquitetura para o cenário do tutorial.

Observação

As etapas abordadas neste tutorial são compatíveis com as versões a seguir:

  • .NET Framework 4.8 e superiores
  • .NET 6.0 e superior

O que você aprenderá:

  • Habilitar a autenticação interna para o Banco de Dados SQL do Azure.
  • Desabilitar outras opções de autenticação no Banco de Dados SQL do Azure
  • Habilitar autenticação do Serviço de Aplicativo
  • Usar o Microsoft Entra ID como um provedor de identidade
  • Acessar o Banco de Dados SQL do Azure em nome do usuário do Microsoft Entra conectado

Observação

A autenticação do Microsoft Entra é diferente da autenticação integrada do Windows no Active Directory (AD DS) local. O AD DS e o Microsoft Entra ID usam protocolos de autenticação completamente diferentes. Para saber mais, confira Sincronização com escopo do Microsoft Entra Domain Services.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Este artigo continua de onde você parou em qualquer um dos seguintes tutoriais:

Caso ainda não o tenha feito, primeiro siga um dos dois tutoriais. Como alternativa, você pode adaptar as etapas ao seu próprio aplicativo .NET com o Banco de Dados SQL.

Prepare seu ambiente para a CLI do Azure.

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell. Captura de tela que mostra um exemplo de Experimente para o Azure Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador. Botão para iniciar o Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure. Captura de tela que mostra o botão Cloud Shell no portal do Azure

Para usar o Azure Cloud Shell:

  1. Inicie o Cloud Shell.

  2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.

  3. Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.

  4. Pressione Enter para executar o código ou comando.

1. Configurar o servidor de banco de dados com a autenticação do Microsoft Entra

Primeiro, habilite a autenticação do Microsoft Entra no Banco de Dados SQL, atribuindo um usuário do Microsoft Entra como o administrador do servidor. Esse usuário é diferente da conta Microsoft usada para inscrição na assinatura do Azure. Esse usuário precisa ser criado, importado, sincronizado ou convidado por você para o Microsoft Entra ID. Para obter mais informações sobre os usuários permitidos do Microsoft Entra, consulte os Recursos e limitações do Microsoft Entra no Banco de Dados SQL.

  1. Se o locatário do Microsoft Entra ainda não tiver um usuário, crie um seguindo as etapas em Adicionar ou excluir usuários usando o Microsoft Entra ID.

  2. Localize a ID do objeto do usuário do Microsoft Entra usando a az ad user list e substitua <user-principal-name>. O resultado é salvo em uma variável.

    azureaduser=$(az ad user list --filter "userPrincipalName eq '<user-principal-name>'" --query [].id --output tsv)

    Dica

    Para visualizar a lista de todos os nomes de entidade de segurança do usuário no Microsoft Entra ID, execute az ad user list --query [].userPrincipalName.

  3. Adicione o usuário do Microsoft Entra como um administrador do Active Directory usando o comando az sql server ad-admin create no Cloud Shell. No comando a seguir, substitua <server-name> pelo nome do servidor do Banco de Dados SQL (sem o sufixo .database.windows.net).

    az sql server ad-admin create --resource-group <group-name> --server-name <server-name> --display-name ADMIN --object-id $azureaduser

  4. Restringir a autenticação do servidor de banco de dados à autenticação do Active Directory. Esta etapa desabilita efetivamente a autenticação do SQL.

    az sql server ad-only-auth enable --resource-group <group-name> --name <server-name>

Para obter mais informações sobre como adicionar um administrador do Active Directory, consulte Provisionar um administrador do Microsoft Entra (Banco de Dados SQL).

2. Habilite a autenticação de usuário para seu aplicativo

Habilite a autenticação com o Microsoft Entra ID como o provedor de identidade. Para obter mais informações, consulte Configurar a autenticação do Microsoft Entra no seu aplicativo dos Serviços de Aplicativos.

  1. No menu do portal do Azure, selecione Grupos de recursos ou pesquise e selecione Grupos de recursos em qualquer página.

  2. Em grupos de recursos, encontre e selecione o grupo de recursos e, em seguida, selecione o seu aplicativo.

  3. No menu à esquerda do aplicativo, selecione Autenticação e clique em Adicionar provedor de identidade.

  4. Na página Adicionar um provedor de identidade, selecione Microsoft como o Provedor de identidade para conectar identidades da Microsoft e do Microsoft Entra.

  5. Aceite as configurações padrão e selecione Adicionar.

    Captura de tela mostrando a página Adicionar o provedor de identidade.

Dica

Se você encontrar erros e reconfigurar as configurações de autenticação do aplicativo, é possível que os tokens no repositório de tokens não sejam regenerados com as novas configurações. Para fazer com que os tokens sejam regenerados, saia e entre novamente no aplicativo. Uma maneira fácil de fazer isso é usar o navegador em modo privado e fechar e reabrir o navegador em modo privado depois de alterar as configurações nos aplicativos.

3. Configure a representação do usuário para o Banco de Dados SQL

Atualmente, seu aplicativo do Azure se conecta ao Banco de Dados SQL e usa a autenticação SQL (nome de usuário e senha) gerenciada como configurações de aplicativo. Nesta etapa, você concede ao aplicativo permissões para acessar o Banco de Dados SQL em nome do usuário do Microsoft Entra conectado.

  1. Na página Autenticação do aplicativo, selecione o nome do aplicativo em Provedor de identidade. Este registro de aplicativo foi gerado automaticamente para você. Selecione Permissões da API no menu à esquerda.

  2. Selecione Adicionar uma permissão e, em seguida, selecione APIs que a minha organização usa .

  3. Digite Banco de Dados SQL do Azure na caixa de pesquisa e selecione o resultado.

  4. Na página Solicitar permissões de API para o Banco de Dados SQL do Azure, selecione Permissões delegadas e user_impersonation e, em seguida, selecione Adicionar permissões.

    Captura de tela da página Solicitar permissões de API que mostra as permissões Delegadas, user_impersonation e o botão Adicionar permissão selecionado.

4. Configure o Serviço de Aplicativo para retornar um token de acesso utilizável

O registro do aplicativo no Microsoft Entra ID agora tem as permissões necessárias para se conectar ao Banco de Dados SQL representando o usuário conectado. Em seguida, configure seu aplicativo de Serviço de Aplicativo para fornecer um token de acesso utilizável.

No Cloud Shell, execute os comandos a seguir no aplicativo para adicionar o parâmetro scope à configuração de autenticação identityProviders.azureActiveDirectory.login.loginParameters. Ele usa [jq] para processamento JSON, que já está instalado no Cloud Shell.

authSettings=$(az webapp auth show --resource-group <group-name> --name <app-name>)
authSettings=$(echo "$authSettings" | jq '.properties' | jq '.identityProviders.azureActiveDirectory.login += {"loginParameters":["scope=openid profile email offline_access https://database.windows.net/user_impersonation"]}')
az webapp auth set --resource-group <group-name> --name <app-name> --body "$authSettings"

Os comandos adicionam efetivamente uma propriedade loginParameters com escopos personalizados adicionais. Confira uma explicação dos escopos solicitados:

  • openid, profile e email já são solicitados pelo Serviço de Aplicativo por padrão. Para obter informações, confira Escopos do OpenID Connect.
  • https://database.windows.net/user_impersonationrefere-se ao Banco de Dados SQL do Azure. É o escopo que fornece um token JWT que inclui o Banco de Dados SQL como um público-alvo do token.
  • offline_access é incluído aqui para conveniência (caso você queira atualizar os tokens).

Dica

Para configurar os escopos necessários usando uma interface da Web, confira as etapas da Microsoft em Atualizar tokens de autenticação.

Os aplicativos estão configurados. O aplicativo agora pode gerar um token que o Banco de Dados SQL aceite.

5. Use o token de acesso no código do aplicativo

As etapas que você segue para o seu projeto dependem de você estar usando o Entity Framework (padrão para ASP.NET) ou o Entity Framework Core (padrão para ASP.NET Core).

  1. No Visual Studio, abra o Console do Gerenciador de Pacotes e atualize o Entity Framework:

    Update-Package EntityFramework

  2. No objeto DbContext (em Models/MyDbContext.cs), adicione o código a seguir ao construtor padrão.

    var conn = (System.Data.SqlClient.SqlConnection)Database.Connection;
conn.AccessToken = System.Web.HttpContext.Current.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];

Observação

O código adiciona o token de acesso fornecido pela autenticação do Serviço de Aplicativo ao objeto de conexão.

Essa alteração de código não funciona localmente. Para obter mais informações, consulte Como depurar localmente ao usar a autenticação do Serviço de Aplicativo?.

6. Publique suas alterações

  1. Se você veio do Tutorial: Como criar um aplicativo ASP.NET no Azure com o Banco de Dados SQL, defina uma cadeia de conexão no Serviço de Aplicativo usando a autenticação SQL, com um nome de usuário e senha. Use o comando a seguir para remover os segredos de conexão, mas substitua <group-name>, <app-name>, <db-server-name> e <db-name> pelo seu próprio.

    az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings MyDbConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"

  2. Publique suas alterações no Visual Studio. No Gerenciador de Soluções, clique com botão direito no projeto DotNetAppSqlD e selecione Publicar.

    Captura de tela mostrando como publicar a partir do Gerenciador de Soluções no Visual Studio.

  3. Na página de publicação, selecione Publicar.

Quando a nova página da Web mostrar sua lista de tarefas pendentes, seu aplicativo estará se conectando ao banco de dados em nome do usuário do Microsoft Entra conectado.

Aplicativo do Azure após Migração do Code First

Agora, você pode editar a lista de tarefas pendentes como fazia antes.

7. Limpar os recursos

Nas etapas anteriores, você criou os recursos do Azure em um grupo de recursos. Se você acha que não precisará desses recursos no futuro, exclua o grupo de recursos executando o seguinte comando no Cloud Shell:

az group delete --name <group-name>

Esse comando pode demorar um pouco para ser executado.

Perguntas frequentes

Por que recebo um erro Login failed for user '<token-identified principal>'.?

As causas mais comuns desse erro são:

Como fazer para adicionar outros usuários ou grupos do Microsoft Entra no Banco de Dados SQL do Azure?

  1. Conecte-se ao servidor de banco de dados, como com sqlcmd ou SSMS.

  2. Crie usuários independentes mapeados para as identidades do Microsoft Entra na documentação do Banco de Dados SQL.

    O exemplo Transact-SQL a seguir adiciona uma identidade do Microsoft Entra para o SQL Server e fornece algumas funções de banco de dados:

    CREATE USER [<user-or-group-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<user-or-group-name>];
ALTER ROLE db_datawriter ADD MEMBER [<user-or-group-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<user-or-group-name>];
GO

Como depurar localmente ao usar a autenticação do Serviço de Aplicativo?

Como a autenticação do Serviço de Aplicativo é um recurso do Azure, não é possível que o mesmo código funcione em seu ambiente local. Ao contrário do aplicativo em execução no Azure, seu código local não se beneficia do middleware de autenticação do Serviço de Aplicativo. Você tem algumas alternativas:

  • Conecte-se a Banco de Dados SQL do seu ambiente local com Active Directory Interactive. O fluxo de autenticação não conecta o usuário ao próprio aplicativo, mas se conecta ao banco de dados de back-end com o usuário conectado e permite que você teste a autorização do banco de dados localmente.
  • Copie manualmente o token de acesso de https://<app-name>.azurewebsites.net/.auth/me para seu código, no lugar do cabeçalho da solicitação X-MS-TOKEN-AAD-ACCESS-TOKEN.
  • Se você implantar por meio do Visual Studio, use a depuração remota do aplicativo Serviço de Aplicativo.

O que acontece quando os tokens de acesso expiram?

O token de acesso expira após algum tempo. Para obter informações sobre como atualizar seus tokens de acesso sem exigir que os usuários autentiquem novamente no aplicativo, confira Atualizar tokens do provedor de identidade.

Próximas etapas

O que você aprendeu:

  • Habilitar a autenticação interna para o Banco de Dados SQL do Azure.
  • Desabilitar outras opções de autenticação no Banco de Dados SQL do Azure
  • Habilitar autenticação do Serviço de Aplicativo
  • Usar o Microsoft Entra ID como um provedor de identidade
  • Acessar o Banco de Dados SQL do Azure em nome do usuário do Microsoft Entra conectado

Mapear um nome DNS personalizado existente para o Serviço de Aplicativo do Azure

Tutorial: acessar o Microsoft Graph de um aplicativo ;NET protegido como o aplicativo

Tutorial: Isolar a comunicação de back-end com a integração da Rede Virtual