Biblioteca de cliente de Autenticação de Aplicações para .NET – versão 1.6.0

Artigo
04/03/2023

Nota

Microsoft.Azure.Services.AppAuthentication foi descontinuado e já não é suportado ou mantido. É substituído pela biblioteca de cliente da Identidade do Azure disponível para .NET, Java, TypeScript e Python. Pode encontrar informações sobre como migrar para Azure Identityaqui: AppAuthentication to Azure.Identity Migration Guidance (Orientação de Migração de AppAuthentication para Azure.Identity Migration).

Para autenticar nos serviços do Azure com o principal de serviço, precisa de uma credencial do Azure Active Directory (Azure AD), um segredo partilhado ou um certificado.

A gestão destas credenciais pode ser difícil. É tentador agrupar credenciais numa aplicação ao incluí-las em ficheiros de origem ou de configuração. A Microsoft.Azure.Services.AppAuthentication biblioteca para .NET simplifica este problema. Utiliza as credenciais do programador para autenticar durante o desenvolvimento local. Quando a solução for posteriormente implementada no Azure, a biblioteca muda automaticamente para as credenciais da aplicação. A utilização de credenciais de programador durante o desenvolvimento local é mais segura porque não precisa de criar credenciais de Azure AD nem de partilhar credenciais entre programadores.

A Microsoft.Azure.Services.AppAuthentication biblioteca gere automaticamente a autenticação, o que, por sua vez, lhe permite concentrar-se na sua solução, em vez das suas credenciais. Suporta o desenvolvimento local com o Microsoft Visual Studio, a CLI do Azure ou a Autenticação Integrada Azure AD. Quando implementada num recurso do Azure que suporta uma identidade gerida, a biblioteca utiliza automaticamente identidades geridas para recursos do Azure. Não são necessárias alterações de código ou de configuração. A biblioteca também suporta a utilização direta de credenciais de cliente Azure AD quando uma identidade gerida não está disponível ou quando o contexto de segurança do programador 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 Aplicações para Visual Studio, disponível como uma extensão separada para a Atualização 5 do Visual Studio 2017 e agrupada com o produto na Atualização 6 e posterior. Com a Atualização 6 ou posterior, pode verificar a instalação da extensão de Autenticação de Aplicações ao selecionar ferramentas de Desenvolvimento do Azure no instalador do Visual Studio.

Utilizar a biblioteca

Para aplicações .NET, a forma mais simples de trabalhar com uma identidade gerida é através do Microsoft.Azure.Services.AppAuthentication pacote. Eis como começar:

Selecione Ferramentas> Gestor > dePacotes NuGetGerir Pacotes NuGet para Solução para adicionar referências aos pacotes NuGet Microsoft.Azure.Services.AppAuthentication e Microsoft.Azure.KeyVault ao seu projeto.

Utilize o AzureServiceTokenProvider para simplificar o pedido de tokens de acesso para os 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 segura AzureServiceTokenProvider para threads coloca o token em cache na memória e obtém-no de Azure AD pouco antes da expiração. Isto significa que nunca precisa de verificar a expiração do token antes de chamar o GetAccessTokenAsync método .

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

Autenticação de desenvolvimento local

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

Autenticar nos Serviços do Azure

As máquinas locais não suportam identidades geridas para recursos do Azure. Como resultado, a biblioteca utiliza as Microsoft.Azure.Services.AppAuthentication suas credenciais de programador para ser executada no seu ambiente de desenvolvimento local. Quando a solução é implementada no Azure, a biblioteca utiliza uma identidade gerida para mudar para um fluxo de concessão de credenciais de cliente OAuth 2.0. Esta abordagem significa que pode testar o mesmo código local e remotamente sem preocupações.

Para desenvolvimento local, AzureServiceTokenProvider obtém tokens com o Visual Studio, a interface de linha de comandos (CLI) do Azure ou Azure AD Autenticação Integrada. Cada opção é experimentada sequencialmente e a biblioteca utiliza a primeira opção com êxito. Se nenhuma opção funcionar, é emitida uma exceção AzureServiceTokenProviderException com informações detalhadas.

Autenticar com o Visual Studio

Para autenticar com o Visual Studio:

Inicie sessão no Visual Studio e utilize as Opções das Ferramentas> para abrir as Opções.
Selecione Autenticação do Serviço do Azure, escolha uma conta para desenvolvimento local e selecione OK.

Se tiver problemas ao utilizar o Visual Studio, como erros que envolvem o ficheiro do fornecedor de tokens, reveja cuidadosamente os passos anteriores.

Poderá ter de voltar a autenticar o token de programador. Para tal, selecioneOpções de Ferramentas> e, em seguida, selecione Autenticação do Serviço do Azure. Procure uma ligação Autenticar novamente na conta selecionada. Selecione-o para autenticar.

Autenticar com a CLI do Azure

Para utilizar a CLI do Azure para desenvolvimento local, certifique-se de que tem a versão da CLI do Azure v2.0.12 ou posterior.

Para utilizar a CLI do Azure:

Procure a CLI do Azure na Barra de Tarefas do Windows para abrir a Linha de Comandos do Microsoft Azure.
Inicie sessão no portal do Azure: az login para iniciar sessão no Azure.
Verifique o acesso ao introduzir az account get-access-token --resource https://vault.azure.net. Se receber um erro, verifique se a versão correta da CLI do Azure está corretamente instalada.

Se a CLI do Azure não estiver instalada no diretório predefinido, poderá receber um relatório de erros que AzureServiceTokenProvider não consegue encontrar o caminho para a CLI do Azure. Utilize a variável de ambiente do AzureCLIPath para definir a pasta de instalação da CLI do Azure. AzureServiceTokenProvider adiciona o diretório especificado na variável de ambiente do AzureCLIPath à variável de ambiente Caminho quando necessário.
Se tiver sessão iniciada na CLI do Azure com várias contas ou se a sua conta tiver acesso a várias subscrições, terá de especificar a subscrição a utilizar. Introduza o comando az account set --subscription .

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

Autenticar com a autenticação Azure AD

Para utilizar Azure AD autenticação, verifique se:

O seu Active Directory no local sincroniza com Azure AD. Para obter mais informações, veja O que é a identidade híbrida com o Azure Active Directory?.
O código está em execução num computador associado a um domínio.

Autenticar em serviços personalizados

Quando um serviço chama os serviços do Azure, os passos anteriores funcionam porque os serviços do Azure permitem o acesso a utilizadores e aplicações.

Ao criar um serviço que chama um serviço personalizado, utilize Azure AD credenciais de cliente para autenticação de desenvolvimento local. Existem duas opções:

Utilize um principal de serviço para iniciar sessão no Azure:
1. Criar um principal de serviço. Para obter mais informações, veja Criar um principal de serviço do Azure com a CLI do Azure.
2. Utilize a CLI do Azure para iniciar sessão com o seguinte comando:
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  Uma vez que o principal de serviço pode não ter acesso a uma subscrição, utilize o --allow-no-subscriptions argumento .
Utilize variáveis de ambiente para especificar os detalhes do principal de serviço. Para obter mais informações, veja Executar a aplicação com um principal de serviço.

Depois de iniciar sessão no Azure, AzureServiceTokenProvider utiliza o principal de serviço para obter um token para desenvolvimento local.

Esta abordagem aplica-se apenas ao desenvolvimento local. Quando a sua solução é implementada no Azure, a biblioteca muda para uma identidade gerida para autenticação.

Executar a aplicação com a identidade gerida ou a identidade atribuída pelo utilizador

Quando executa o código num Serviço de Aplicações do Azure ou numa VM do Azure com uma identidade gerida ativada, a biblioteca utiliza automaticamente a identidade gerida. Não são necessárias alterações de código, mas a identidade gerida tem de ter permissões para os recursos a que tentará aceder. Por exemplo, são necessárias políticas de acesso para que uma identidade gerida aceda a segredos num cofre de chaves.

Em alternativa, pode autenticar com uma identidade atribuída pelo utilizador. Para obter mais informações sobre identidades atribuídas pelo utilizador, veja About Managed Identities for Azure resources (Acerca das Identidades Geridas dos recursos do Azure). Para autenticar com uma identidade atribuída pelo utilizador, tem de especificar o ID de Cliente da identidade atribuída pelo utilizador na cadeia de ligação. A cadeia de ligação é especificada no Suporte de Cadeia de Ligação.

Executar a aplicação com um Principal de Serviço

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

O código é executado num ambiente de desenvolvimento local, mas não na identidade do programador. O Service Fabric, por exemplo, utiliza a conta NetworkService para desenvolvimento local.
O código é executado num ambiente de desenvolvimento local e autentica-se num serviço personalizado, pelo que não pode utilizar a identidade do programador.
O código está em execução num recurso de computação do Azure que ainda não suporta identidades geridas para recursos do Azure, como Azure Batch.

Existem três métodos principais de utilização de um Principal de Serviço para executar a sua aplicação. Para utilizar qualquer um deles, primeiro tem de criar um principal de serviço. Para obter mais informações, veja Criar um principal de serviço do Azure com a CLI do Azure.

Utilizar um certificado no keystore local para iniciar sessão no Azure AD

Crie um certificado de principal de serviço com o comando az ad sp create-for-rbac da CLI do Azure .
```
az ad sp create-for-rbac --create-cert
```
Este comando cria um ficheiro .pem (chave privada) armazenado no diretório raiz. Converta o ficheiro .pem num certificado PFX com o comando :
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
Defina uma variável de ambiente com o nome AzureServicesAuthConnectionString para o seguinte valor:
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
Substitua {AppId}, {TenantId} e {Thumbprint} pelos valores gerados no Passo 1. Substitua {CertificateStore} por LocalMachine' ou CurrentUser, com base no seu plano de implementação.
Execute a aplicação.

Utilizar uma credencial de segredo partilhado para iniciar sessão no Azure AD

Crie um certificado do principal de serviço com uma palavra-passe com 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
```
Defina uma variável de ambiente com o nome AzureServicesAuthConnectionString para o seguinte valor:
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
Substitua {AppId}, {TenantId} e {ClientSecret} pelos valores gerados no Passo 1.
Execute a aplicação.

Depois de tudo estar configurado corretamente, não são necessárias mais alterações de código. AzureServiceTokenProviderutiliza a variável de ambiente e o certificado para autenticar no Azure AD.

Utilizar um certificado no Key Vault para iniciar sessão no Azure AD

Esta opção permite-lhe armazenar o certificado de cliente de um principal de serviço no Key Vault e utilizá-lo para autenticação do principal de serviço. Pode utilizar esta opção para os seguintes cenários:

Autenticação local, onde pretende autenticar com um principal de serviço explícito e pretende manter a credencial do principal de serviço segura num cofre de chaves. A conta de programador tem de ter acesso ao cofre de chaves.
Autenticação do Azure onde pretende utilizar credenciais explícitas e quer manter a credencial do principal de serviço segura num cofre de chaves. Pode utilizar esta opção para um cenário entre inquilinos. A identidade gerida tem de ter acesso ao cofre de chaves.

A identidade gerida ou a identidade do programador têm de ter permissão para obter o certificado de cliente do Key Vault. A biblioteca AppAuthentication utiliza o certificado obtido como credencial de cliente do principal de serviço.

Para utilizar um certificado de cliente para autenticação do principal de serviço:

Crie um certificado de principal de serviço e armazene-o automaticamente no seu Key Vault. Utilize a CLI do Azure az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment command:
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
O identificador do certificado será um URL no formato https://<keyvaultname>.vault.azure.net/secrets/<certificatename>
Substitua {KeyVaultCertificateSecretIdentifier} nesta cadeia de ligação pelo identificador do certificado:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
```
Por exemplo, se o seu cofre de chaves se chamasse myKeyVault e criasse um certificado chamado myCert, o identificador do certificado seria:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
```

Suporte de Cadeia de Ligação

Por predefinição, AzureServiceTokenProvider tenta os seguintes métodos de autenticação para obter um token:

Uma identidade gerida para recursos do Azure
Autenticação do Visual Studio
Autenticação da CLI do Azure
Autenticação integrada do Windows

Para controlar o processo, utilize uma cadeia de ligação transmitida ao AzureServiceTokenProvider construtor ou especificada na variável de ambiente AzureServicesAuthConnectionString . São suportadas as seguintes opções:

Opção cadeia de ligação	Scenario	Comentários
`RunAs=Developer;DeveloperTool=AzureCli`	Desenvolvimento local	`AzureServiceTokenProvider` utiliza o AzureCli para obter o token.
`RunAs=Developer;DeveloperTool=VisualStudio`	Desenvolvimento local	`AzureServiceTokenProvider` utiliza o Visual Studio para obter o token.
`RunAs=CurrentUser`	Desenvolvimento local	Não suportado no .NET Core. `AzureServiceTokenProvider`utiliza Azure AD Autenticação Integrada para obter o token.
`RunAs=App`	Identidades geridas para os recursos do Azure	`AzureServiceTokenProvider` utiliza uma identidade gerida para obter o token.
`RunAs=App;AppId={ClientId of user-assigned identity}`	Identidade atribuída pelo utilizador para recursos do Azure	`AzureServiceTokenProvider` utiliza uma identidade atribuída pelo utilizador para obter o token.
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	Autenticação de serviços personalizados	`KeyVaultCertificateSecretIdentifier` é o identificador secreto do certificado.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	Service principal (Principal de serviço)	`AzureServiceTokenProvider`utiliza o certificado para obter o token do Azure AD.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	Service principal (Principal de serviço)	`AzureServiceTokenProvider`utiliza o certificado para obter o token do Azure AD
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	Service principal (Principal de serviço)	`AzureServiceTokenProvider`utiliza o segredo para obter o token do Azure AD.

Amostras

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

Resolução de Problemas de AppAuthentication

Problemas comuns durante o desenvolvimento local

A CLI do Azure não está instalada, não tem sessão iniciada 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 si. Se indicar que esse programa não foi encontrado, instale a versão mais recente da CLI do Azure. Ser-lhe-á pedido que inicie sessão.

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

O AzureServiceTokenProvider procura a CLI do Azure nas localizações de instalação predefinidas. Se não conseguir encontrar a CLI do Azure, defina a variável de ambiente AzureCLIPath para a pasta de instalação da CLI do Azure. O AzureServiceTokenProvider adicionará a variável de ambiente à variável de ambiente Caminho.

Tem sessão iniciada na CLI do Azure com várias contas, a mesma conta tem acesso a subscrições em vários inquilinos ou obtém um erro de Acesso Negado ao tentar efetuar chamadas durante o desenvolvimento local

Com a CLI do Azure, defina a subscrição predefinida para uma que tenha a conta que pretende utilizar. A subscrição tem de estar no mesmo inquilino que o recurso a que pretende aceder: az account set --subscription [subscription-id]. Se não for visualizada nenhuma saída, será bem-sucedida. Verifique se a conta correta é agora a predefinição com az account list.

Problemas comuns entre ambientes

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

O principal utilizado não tem acesso ao recurso que está a tentar aceder. Conceda à sua conta de utilizador ou ao "Contribuidor" MSI do Serviço de Aplicações acesso a um recurso. Qual depende se está a executar o exemplo no seu computador local ou implementado no Azure no seu Serviço de Aplicações. Alguns recursos, como cofres de chaves, também têm as suas próprias políticas de acesso que utiliza para conceder acesso a principais, como utilizadores, aplicações e grupos.

Problemas comuns quando implementados no Serviço de Aplicações do Azure

A identidade gerida não está configurada no Serviço de Aplicações

Verifique as variáveis de ambiente MSI_ENDPOINT e MSI_SECRET existem com a consola de depuração kudu. Se estas variáveis de ambiente não existirem, a Identidade Gerida não está ativada no Serviço de Aplicações.

Problemas comuns quando implementados localmente com o IIS

Não é possível obter tokens ao depurar a aplicação no IIS

Por predefinição, o AppAuth é executado num contexto de utilizador diferente no IIS. É por isso que não tem acesso para utilizar a sua identidade de programador para obter tokens de acesso. Pode configurar o IIS para ser executado com o contexto de utilizador com os dois passos seguintes:

Configure o Conjunto aplicacional para que a aplicação Web seja executada como a sua conta de utilizador atual. Veja mais informações aqui
Configure "setProfileEnvironment" para "True". Veja mais informações aqui.
- Ir para %windir%\System32\inetsrv\config\applicationHost.config
- Procure "setProfileEnvironment". Se estiver definido como "Falso", altere-o para "Verdadeiro". Se não estiver presente, adicione-o como um atributo ao elemento processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) e defina-o como "Verdadeiro".
Saiba mais sobre identidades geridas para recursos do Azure.
Saiba mais sobre Azure AD cenários de autenticação.

Partilhar via