Biblioteca de clientes da Autenticação Agenciada de Identidade do Azure para .NET – versão 1.0.0

A biblioteca estende a biblioteca Azure.Identity para fornecer suporte ao agente de autenticação. Ele inclui as dependências necessárias e fornece a InteractiveBrowserCredentialBrokerOptions classe . Essa classe de opções pode ser usada para criar um InteractiveBrowserCredential capaz de usar o agente de autenticação do sistema em vez do navegador do sistema quando disponível.

Código-fonte | Pacote (nuget) | Documentação | de referência da APIdocumentação da ID do Microsoft Entra

Introdução

Instalar o pacote

Instale a biblioteca de clientes da Identidade do Azure para .NET com o NuGet:

dotnet add package Azure.Identity.Broker

Pré-requisitos

• A biblioteca Azure.Identity é uma dependência do Azure.Identity.Broker.

Autenticar o cliente

Principais conceitos

Esse pacote permite o suporte do agente de autenticação por meio InteractiveBrowserCredentialBrokerOptionsde , em combinação com InteractiveBrowserCredential no Azure.Identity pacote.

Identificadores da janela pai

Ao autenticar interativamente por meio InteractiveBrowserCredential do construído com o InteractiveBrowserCredentialBrokerOptions, um identificador de janela pai é necessário para garantir que a caixa de diálogo de autenticação seja mostrada corretamente na janela de solicitação. No contexto de interfaces gráficas do usuário em dispositivos, um identificador de janela é um identificador exclusivo que o sistema operacional atribui a cada janela. Para o sistema operacional Windows, esse identificador é um valor inteiro que serve como uma referência a uma janela específica.

Passagem da conta Microsoft (MSA)

As MSA (contas da Microsoft) são contas pessoais criadas pelos usuários para acessar os serviços da Microsoft. A passagem msa é uma configuração herdada que permite que os usuários obtenham tokens para recursos que normalmente não aceitam logons MSA. Esse recurso só está disponível para aplicativos de primeira parte. Os usuários que se autenticam com um aplicativo configurado para usar a passagem MSA podem definir a InteractiveBrowserCredentialBrokerOptions.IsLegacyMsaPassthroughEnabled propriedade para true permitir que essas contas pessoais sejam listadas pelo WAM.

URIs de redirecionamento

Microsoft Entra aplicativos dependem de URIs de redirecionamento para determinar para onde enviar a resposta de autenticação após o logon de um usuário. Para habilitar a autenticação agenciada por meio do WAM, um URI de redirecionamento correspondente ao seguinte padrão deve ser registrado no aplicativo:

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Exemplos

Configurando o InteractiveBrowserCredential para usar o agente de autenticação do sistema

Este exemplo demonstra a configuração do InteractiveBrowserCredential com o tipo InteractiveBrowserCredentialBrokerOptions de opções especializadas para habilitar a autenticação agenciada.

IntPtr parentWindowHandle = GetForegroundWindow();

// Create an interactive browser credential which will use the system authentication broker
var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle));

// Use the credential to authenticate a secret client
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Solução de problemas

Consulte o guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Tratamento de erros

Erros decorrentes da autenticação podem ser gerados em qualquer método de cliente de serviço que faça uma solicitação para o serviço. Isso ocorre porque a primeira vez que o token é solicitado da credencial é na primeira chamada para o serviço, e qualquer chamada subsequente pode precisar atualizar o token. Para distinguir essas falhas de falhas nas classes de identidade do Azure cliente de serviço, gere o AuthenticationFailedException com detalhes para a origem do erro na mensagem de exceção, bem como possivelmente a mensagem de erro. Dependendo do aplicativo, esses erros podem ou não ser recuperáveis.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

Para obter mais detalhes sobre como lidar com erros decorrentes de solicitações com falha para Microsoft Entra ID ou pontos de extremidade de identidade gerenciada, consulte a documentação da ID do Microsoft Entra sobre códigos de erro de autorização.

Registro em log

A biblioteca de Identidade do Azure fornece os mesmos recursos de registro em log que o restante do SDK do Azure.

A maneira mais simples de ver os logs para ajudar a depurar problemas de autenticação é habilitar o log do console.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Todas as credenciais podem ser configuradas com opções de diagnóstico da mesma forma que outros clientes no SDK.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions()
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

CUIDADO: solicitações e respostas na biblioteca de identidades do Azure contêm informações confidenciais. A precaução deve ser tomada para proteger os logs ao personalizar a saída para evitar comprometer a segurança da conta.

Acesso thread-safe

Garantimos que todos os métodos de instância de credencial sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de credencial seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções | do clienteAcessando a resposta | Diagnostics | Zombando | Tempo de vida do cliente

Próximas etapas

Bibliotecas de clientes que dão suporte à autenticação com a Identidade do Azure

Muitas das bibliotecas de clientes listadas aqui dão suporte à autenticação com TokenCredential e à biblioteca de identidade do Azure. Lá, você também encontrará links nos quais poderá saber mais sobre o uso deles, incluindo documentação e exemplos adicionais.

Problemas conhecidos

No momento, essa biblioteca não dá suporte a cenários relacionados ao serviço AAD B2C .

Atualmente, problemas abertos para a biblioteca Azure.Identity podem ser encontrados aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.