Biblioteca de clientes de Autenticação de Aplicativo para .NET – versão 1.6.0

Para autenticar nos serviços do Azure com a entidade de serviço, você precisa de uma credencial do Azure Active Directory (Azure AD), um segredo compartilhado ou um certificado.

O gerenciamento dessas credenciais pode ser difícil. É tentador agrupar credenciais em um aplicativo, incluindo-as em arquivos de origem ou de configuração. O Microsoft.Azure.Services.AppAuthentication para a biblioteca .NET simplifica esse problema. Ele usa as credenciais do desenvolvedor para autenticação durante o desenvolvimento local. Quando a solução é implantada posteriormente no Azure, a biblioteca alterna automaticamente para as credenciais do aplicativo. O uso de credenciais de desenvolvedor durante o desenvolvimento local é mais seguro porque você não precisa criar credenciais Azure AD ou compartilhar credenciais entre desenvolvedores.

A Microsoft.Azure.Services.AppAuthentication biblioteca gerencia a autenticação automaticamente, o que, por sua vez, permite que você se concentre em sua solução, em vez de suas credenciais. Ele dá suporte ao desenvolvimento local com o Microsoft Visual Studio, a CLI do Azure ou a Autenticação Integrada Azure AD. Quando implantada em um recurso do Azure que oferece suporte a uma identidade gerenciada, a biblioteca usa automaticamente as identidades gerenciadas para recursos do Azure. Nenhuma alteração de configuração ou de código é necessária. A biblioteca também dá suporte ao uso direto de Azure AD credenciais de cliente quando uma identidade gerenciada não está disponível ou quando o contexto de segurança do desenvolvedor não pode ser determinado durante o desenvolvimento local.

Código-fonte | Pacote (nuget) | Documentação do Azure Active Directory

Pré-requisitos

• Visual Studio 2019 ou Visual Studio 2017 v15.5.

• A extensão de Autenticação de Aplicativo para Visual Studio, disponível como uma extensão separada para o Visual Studio 2017 Atualização 5 e agrupada com o produto na Atualização 6 e posterior. Com a Atualização 6 ou posterior, você pode verificar a instalação da extensão de Autenticação de Aplicativo selecionando Ferramentas de Desenvolvimento do Azure de dentro do instalador do Visual Studio.

Usando a biblioteca

Para aplicativos .NET, a maneira mais simples de trabalhar com uma identidade gerenciada é por meio do pacote Microsoft.Azure.Services.AppAuthentication. Estas são algumas dicas para começar:

1. Selecione FerramentasGerenciador > dePacotes> NuGetGerenciar Pacotes NuGet para solução para adicionar referências aos pacotes NuGet Microsoft.Azure.Services.AppAuthentication e Microsoft.Azure.KeyVault ao seu projeto.

2. Use AzureServiceTokenProvider para simplificar a solicitação de tokens de acesso para seus clientes do Azure, como os exemplos abaixo:

   using Microsoft.Azure.Services.AppAuthentication;
   using Microsoft.Azure.KeyVault;
   using System.Data.SqlClient
   
   // Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
   var azureServiceTokenProvider = new AzureServiceTokenProvider();
   var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));
   
   // Request an access token for SqlConnection
   sqlConnection = new SqlConnection(YourConnectionString)) 
   { 
       sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
       sqlConnection.Open(); 
   } 
   

A classe thread-safe AzureServiceTokenProvider armazena o token em cache na memória e o recupera de Azure AD pouco antes da expiração. Isso significa que você nunca precisa marcar a expiração do token antes de chamar o GetAccessTokenAsync método .

O método GetAccessTokenAsync exige um identificador de recurso. Para saber mais sobre os serviços do Microsoft Azure, confira O que são identidades gerenciadas para recursos do Azure.

Autenticação de desenvolvimento local

Para desenvolvimento local, há dois cenários de autenticação principais: autenticação nos serviços do Azure e autenticação em serviços personalizados.

Autenticação nos serviços do Azure

Os computadores locais não dão suporte a identidades gerenciadas para recursos do Azure. Como resultado, a biblioteca Microsoft.Azure.Services.AppAuthentication usa suas credenciais de desenvolvedor para ser executada no ambiente de desenvolvimento local. Quando a solução é implantada no Azure, a biblioteca usa uma identidade gerenciada para mudar para um fluxo de concessão de credenciais do cliente do OAuth 2.0. Essa abordagem significa que você pode testar o mesmo código local e remotamente sem se preocupar.

Para o desenvolvimento local, o AzureServiceTokenProvider busca tokens usando o Visual Studio, a CLI (interface de linha de comando) do Azure ou a Autenticação Integrada do Azure AD. Cada opção é tentada na sequência e a biblioteca usa a primeira opção bem-sucedida. Se nenhuma opção funcionar, uma exceção AzureServiceTokenProviderException será gerada com informações detalhadas.

Autenticando com o Visual Studio

Para autenticar usando o Visual Studio:

1. Entre no Visual Studio e useas Opções de Ferramentas> para abrir Opções.

2. Selecione Autenticação de Serviço do Azure, escolha uma conta para desenvolvimento local e selecione OK.

Se você tiver problemas ao usar o Visual Studio, como erros que envolvem o arquivo do provedor de token, examine cuidadosamente as etapas anteriores.

Talvez seja necessário autenticar novamente o token de desenvolvedor. Para fazer isso, selecione Opções de Ferramentas> e, em seguida, selecione Autenticação de Serviço do Azure. Procure um link autenticar novamente na conta selecionada. Selecione-o para autenticar.

Autenticando com a CLI do Azure

Para usar a CLI do Azure para desenvolvimento local, verifique se você tem a versão da CLI do Azure v2.0.12 ou posterior.

Para usar a CLI do Azure:

1. Pesquise a CLI do Azure na Barra de Tarefas do Windows para abrir o Prompt de Comando do Microsoft Azure.

2. Entre no portal do Azure: az login para entrar no Azure.

3. Verifique o acesso inserindo az account get-access-token --resource https://vault.azure.net. Se você receber um erro, marcar que a versão certa da CLI do Azure está instalada corretamente.

   Se a CLI do Azure não estiver instalada no diretório padrão, você poderá receber um relatório de erros que AzureServiceTokenProvider não consegue encontrar o caminho para a CLI do Azure. Use a variável de ambiente AzureCLIPath para definir a pasta de instalação da CLI do Azure. AzureServiceTokenProvider adiciona o diretório especificado na variável de ambiente AzureCLIPath à variável de ambiente Path, quando necessário.

4. Se você estiver conectado à CLI do Azure usando várias contas ou sua conta tiver acesso a várias assinaturas, você precisará especificar a assinatura a ser usada. Insira o comando az account set --subscription .

Esse comando gera a saída apenas em caso de falha. Para verificar as configurações da conta atual, insira o comando az account list.

Autenticação com autenticação Azure AD

Para usar a autenticação do Azure AD, verifique se:

• Seu Active Directory local sincroniza com Azure AD. Para obter mais informações, consulte O que é a identidade híbrida com o Azure Active Directory?.

• Seu código está em execução em um computador ingressado no domínio.

Autenticação em serviços personalizados

Quando um serviço chama os serviços do Azure, as etapas anteriores funcionam porque os serviços do Azure permitem o acesso a usuários e aplicativos.

Ao criar um serviço que chama um serviço personalizado, use as credenciais do cliente do Azure AD para autenticação de desenvolvimento local. Há duas opções:

• Use uma entidade de serviço para entrar no Azure:

  1. Crie uma entidade de serviço. Para obter mais informações, consulte Criar uma entidade de serviço do Azure com CLI do Azure .

  2. Use a CLI do Azure para entrar com o seguinte comando:

     az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
     

     Como a entidade de serviço pode não ter acesso a uma assinatura, use o argumento --allow-no-subscriptions.

• Use variáveis de ambiente para especificar detalhes da entidade de serviço. Para obter mais informações, consulte Executando o aplicativo usando uma entidade de serviço.

Depois de entrar no Azure, AzureServiceTokenProvider o usa a entidade de serviço para recuperar um token para desenvolvimento local.

Essa abordagem se aplica apenas ao desenvolvimento local. Quando a solução é implantada no Azure, a biblioteca muda uma identidade gerenciada com propósito de autenticação.

Executando o aplicativo usando identidade gerenciada ou identidade atribuída pelo usuário

Quando você executa o código em um Serviço de Aplicativo do Azure ou em uma VM do Azure com uma identidade gerenciada habilitada, a biblioteca usa automaticamente a identidade gerenciada. Nenhuma alteração de código é necessária, mas a identidade gerenciada deve ter permissões para os recursos que tentará acessar. Por exemplo, as políticas de acesso são necessárias para que uma identidade gerenciada acesse todos os segredos em um cofre de chaves.

Como alternativa, você pode se autenticar com uma identidade atribuída pelo usuário. Para obter mais informações sobre identidades atribuídas pelo usuário, consulte Sobre identidades gerenciadas para recursos do Azure. Para autenticar com uma identidade atribuída pelo usuário, você precisa especificar a ID do cliente da identidade atribuída pelo usuário na cadeia de conexão. A cadeia de conexão é especificada no Suporte à Cadeia de Conexão.

Executando o aplicativo usando uma Entidade de Serviço

Pode ser necessário criar uma credencial do Cliente do Azure AD para autenticar. Essa situação pode ocorrer nos seguintes exemplos:

• O código é executado em um ambiente de desenvolvimento local, mas não na identidade do desenvolvedor. O Service Fabric, por exemplo, usa a conta NetworkService para o desenvolvimento local.

• O código é executado em um ambiente de desenvolvimento local e você se autentica em um serviço personalizado e, portanto, não pode usar sua identidade de desenvolvedor.

• Seu código está em execução em um recurso de computação do Azure que ainda não dá suporte a identidades gerenciadas para recursos do Azure, como Lote do Azure.

Há três métodos principais de usar uma Entidade de Serviço para executar seu aplicativo. Para usar qualquer um deles, primeiro você deve criar uma entidade de serviço. Para obter mais informações, consulte Criar uma entidade de serviço do Azure com CLI do Azure .

Usar um certificado no repositório de chaves local para entrar no Azure AD

1. Crie um certificado de entidade de serviço usando o comando az ad sp create-for-rbac da CLI do Azure .

   az ad sp create-for-rbac --create-cert
   

   Esse comando cria um arquivo .pem (chave privada) armazenado no diretório base. Converta o arquivo .pem em um certificado PFX usando o comando :

   openssl pkcs12 -export -in test.pem -out test.pfx
   

2. Defina uma variável de ambiente chamada AzureServicesAuthConnectionString com o seguinte valor:

   RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
         CertificateStoreLocation={CertificateStore}
   

   Substitua {AppId}, {TenantId} e {Thumbprint} pelos valores gerados na Etapa 1. Substitua {CertificateStore} por LocalMachine' ou CurrentUser, com base em seu plano de implantação.

3. Execute o aplicativo.

Usar uma credencial de segredo compartilhado para entrar no Azure AD

1. Crie um certificado de entidade de serviço com uma senha usando o comando az ad sp create-for-rbac da CLI do Azure com o parâmetro --sdk-auth.

   az ad sp create-for-rbac --sdk-auth
   

2. Defina uma variável de ambiente chamada AzureServicesAuthConnectionString com o seguinte valor:

   RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
   

   Substitua {AppId}, {TenantId} e {ClientSecret} pelos valores gerados na Etapa 1.

3. Execute o aplicativo.

Depois que tudo estiver configurado corretamente, nenhuma alteração de código adicional será necessária. O AzureServiceTokenProvider usa a variável de ambiente e o certificado para se autenticar no Azure AD.

Usar um certificado no Key Vault para entrar no Azure AD

Essa opção permite armazenar o certificado do cliente de uma entidade de serviço no Key Vault e usá-lo para autenticação da entidade de serviço. Você pode usar essa opção para os seguintes cenários:

• Autenticação local, em que você deseja autenticar usando uma entidade de serviço explícita e deseja manter a credencial da entidade de serviço com segurança em um cofre de chaves. A conta de desenvolvedor deve ter acesso ao cofre de chaves.

• Autenticação do Azure em que você deseja usar credenciais explícitas e deseja manter a credencial da entidade de serviço com segurança em um cofre de chaves. Você pode usar essa opção para um cenário entre locatários. A identidade gerenciada deve ter acesso ao cofre de chaves.

A identidade gerenciada ou a identidade do desenvolvedor devem ter permissão para recuperar o certificado do cliente do Key Vault. A biblioteca AppAuthentication usa o certificado recuperado como credencial de cliente da entidade de serviço.

Para usar um certificado de cliente para autenticação de entidade de serviço:

1. Crie um certificado de entidade de serviço e armazene-o automaticamente em seu Key Vault. Use o comando az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment da CLI do Azure:

   az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
   

   O identificador de certificado será uma URL no formato https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

2. Substitua {KeyVaultCertificateSecretIdentifier} nesta cadeia de conexão pelo identificador de certificado:

   RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
   

   Por exemplo, se o cofre de chaves fosse chamado myKeyVault e você criasse um certificado chamado myCert, o identificador de certificado seria:

   RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
   

Suporte à cadeia de conexão

Por padrão, AzureServiceTokenProvider tenta os seguintes métodos de autenticação, em ordem, para recuperar um token:

• Uma identidade gerenciada para recursos do Azure
• Autenticação do Visual Studio
• Autenticação com a CLI do Azure
• Autenticação integrada do Windows

Para controlar o processo, use uma cadeia de conexão passada para o construtor AzureServiceTokenProvider ou especificada na variável de ambiente AzureServicesAuthConnectionString. Há suporte para as seguintes opções:

Exemplos

Para ver a Microsoft.Azure.Services.AppAuthentication biblioteca em ação, consulte os exemplos de código a seguir.

• Usar uma identidade gerenciada para recuperar um segredo do Azure Key Vault em runtime

• Implante de forma programática um modelo do Azure Resource Manager de uma VM do Azure com uma identidade gerenciada.

• Use uma amostra do .NET Core e uma identidade gerenciada para chamar os serviços do Azure de uma VM Linux do Azure.

Solução de problemas de AppAuthentication

Problemas comuns durante o desenvolvimento local

A CLI do Azure não está instalada, você não está conectado ou não tem a versão mais recente

Execute az account get-access-token para ver se a CLI do Azure mostra um token para você. Se ele disser que nenhum programa desse tipo foi encontrado, instale a versão mais recente da CLI do Azure. Talvez você receba uma solicitação para entrar.

O AzureServiceTokenProvider não consegue encontrar o caminho para a CLI do Azure

O AzureServiceTokenProvider procura a CLI do Azure em seus locais de instalação padrão. Se não conseguir localizar a CLI do Azure, defina a variável de ambiente AzureCLIPath para a pasta de instalação da CLI do Azure. AzureServiceTokenProvider adicionará a variável de ambiente à variável de ambiente Path.

Você está conectado à CLI do Azure usando várias contas, a mesma conta tem acesso a assinaturas em vários locatários ou você recebe um erro acesso negado ao tentar fazer chamadas durante o desenvolvimento local

Usando a CLI do Azure, defina a assinatura padrão como uma que tenha a conta que você deseja usar. A assinatura deve estar no mesmo locatário que o recurso que você deseja acessar: az account set --subscription [subscription-id]. Se nenhuma saída for vista, ela terá êxito. Verifique se a conta correta agora é o padrão usando az account list.

Problemas comuns entre ambientes

Acesso não autorizado, acesso negado, proibido ou erro semelhante

O principal usado não tem acesso ao recurso que está tentando acessar. Conceda à sua conta de usuário ou ao "Colaborador" do MSI do Serviço de Aplicativo acesso a um recurso. Qual delas depende se você está executando o exemplo em seu computador local ou implantado no Azure em seu Serviço de Aplicativo. Alguns recursos, como cofres de chaves, também têm suas próprias políticas de acesso que você usa para conceder acesso a entidades de segurança, como usuários, aplicativos e grupos.

Problemas comuns quando implantados no Serviço de Aplicativo do Azure

A identidade gerenciada não está configurada no Serviço de Aplicativo

Verifique se as variáveis de ambiente MSI_ENDPOINT e MSI_SECRET existem usando o console de depuração do Kudu. Se essas variáveis de ambiente não existirem, a Identidade Gerenciada não estará habilitada no Serviço de Aplicativo.

Problemas comuns quando implantados localmente com o IIS

Não é possível recuperar tokens ao depurar o aplicativo no IIS

Por padrão, o AppAuth é executado em um contexto de usuário diferente no IIS. É por isso que ele não tem acesso para usar sua identidade de desenvolvedor para recuperar tokens de acesso. Você pode configurar o IIS para ser executado com o contexto do usuário com as duas etapas a seguir:

• Configure o Pool de Aplicativos para que o aplicativo Web seja executado como sua conta de usuário atual. Confira mais informações aqui

• Configure "setProfileEnvironment" como "True". Veja mais informações aqui.

  • Vá para %windir%\System32\inetsrv\config\applicationHost.config
  • Pesquise "setProfileEnvironment". Se estiver definido como "False", altere-o para "True". Se não estiver presente, adicione-o como um atributo ao elemento processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) e defina-o como "True".

• Aprenda sobre identidades gerenciadas dos recursos do Azure.

• Saiba mais sobre os cenários de autenticação do Azure AD.