Inicializar aplicações cliente usando MSAL.NET

Este artigo descreve a inicialização de aplicações cliente pública e cliente confidencial utilizando a Biblioteca de Autenticação da Microsoft for .NET (MSAL.NET). Para saber mais sobre os tipos de aplicações de cliente, consulte Aplicações de cliente público e de cliente confidencial.

Com o MSAL.NET 3.x, a forma recomendada de instanciar uma aplicação é usando os construtores de aplicações: PublicClientApplicationBuilder e ConfidentialClientApplicationBuilder. Oferecem um mecanismo poderoso para configurar a aplicação a partir do código, de um ficheiro de configuração ou até mesmo misturando ambas as abordagens.

Pré-requisitos

Antes de inicializar uma aplicação, primeiro precisa de a registar para que a sua aplicação possa ser integrada com a plataforma de identidades da Microsoft. Consulte o Quickstart: Registe uma aplicação na plataforma de identidades da Microsoft para mais informações. Após o registo, precisará das seguintes informações, que podem ser encontradas na página de registo de aplicações no centro de administração Microsoft Entra.

  • ID da aplicação (cliente) - Esta é uma cadeia que representa um GUID.
  • ID de diretório (inquilino ) - Fornece capacidades de gestão de identidade e acesso (IAM) às aplicações e recursos utilizados pela sua organização. Pode indicar se está a escrever uma aplicação empresarial exclusivamente para a sua organização (também designada por aplicação de um único inquilino).
  • O URL do fornecedor de identidades (designado por instance) e o público de início de sessão da sua aplicação. Estes dois parâmetros são coletivamente conhecidos como a autoridade.
  • Credenciais de cliente – que podem assumir a forma de um segredo de aplicação (cadeia de segredos de cliente) ou certificado (do tipo X509Certificate2) se for uma aplicação cliente confidencial.
  • Para aplicações web e, por vezes, para aplicações cliente públicas (em particular quando a sua aplicação precisa de usar um broker), precisa de definir o URI de Redirecionamento para onde o fornecedor de identidade redirecionará a sua aplicação com os tokens de segurança.

Inicialização de aplicações

Existem muitas formas diferentes de instanciar aplicações clientes.

Inicialização de uma aplicação cliente pública a partir de código

O código seguinte cria uma instância de uma aplicação cliente pública, permitindo que os utilizadores iniciem sessão na cloud pública do Azure da Microsoft com as suas contas Microsoft profissionais, escolares ou pessoais.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Inicialização de uma aplicação cliente confidencial a partir de código

Da mesma forma, o código seguinte instancia uma aplicação confidencial (uma aplicação Web localizada em https://myapp.azurewebsites.net) que trata tokens de utilizadores na cloud pública Microsoft Azure, com as suas contas de trabalho e escola, ou as suas contas pessoais da Microsoft. A aplicação é identificada com o fornecedor de identidade ao partilhar um segredo do cliente:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

Em produção, no entanto, recomendam-se certificados, pois são mais seguros do que os segredos dos clientes. Podem ser criados e carregados no centro de administração Microsoft Entra. O código seria então o seguinte:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

Inicialização de uma aplicação cliente pública a partir das opções de configuração

O código seguinte instancia uma aplicação cliente pública a partir de um objeto de configuração, que pode ser preenchido programaticamente ou lido a partir de um ficheiro de configuração:

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

Inicialização de uma aplicação cliente confidencial a partir de opções de configuração

O mesmo tipo de padrão aplica-se a aplicações confidenciais de clientes. Também podes adicionar outros parâmetros usando .WithXXX modificadores. Este exemplo utiliza .WithCertificate.

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

Modificadores do Builder

Nos excertos de código usando construtores de aplicações, muitos .With métodos podem ser aplicados como modificadores (por exemplo, .WithCertificate e .WithRedirectUri).

Modificadores comuns a aplicações clientes públicas e confidenciais

Os modificadores que pode definir num cliente público ou no construtor de aplicações cliente confidencial encontram-se na classe AbstractApplicationBuilder<T>. Os diferentes métodos podem ser encontrados no SDK do Azure para documentação .NET.

Modificadores específicos para aplicações Xamarin.iOS

Os modificadores que pode definir num construtor de aplicações cliente pública no Xamarin.iOS são:

Modificador Description
.WithIosKeychainSecurityGroup() Apenas no Xamarin.iOS: Define o grupo de segurança do porta-chaves do iOS (para a persistência da cache).

Modificadores específicos para aplicações cliente confidenciais

Os modificadores específicos de um construtor de aplicações cliente confidencial podem ser encontrados na ConfidentialClientApplicationBuilder classe. Os diferentes métodos podem ser encontrados no SDK do Azure para documentação .NET.

Modificadores como .WithCertificate(X509Certificate2 certificate) e .WithClientSecret(string clientSecret) são mutuamente exclusivos. Se fornecer ambos, o MSAL oferece uma exceção significativa.

Exemplo de utilização de modificadores

Vamos supor que a sua aplicação é uma aplicação de negócio, destinada apenas à sua organização. Depois podes escrever:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

Programar para clouds nacionais simplificou-se, por isso, se quiser que a sua aplicação seja uma aplicação multi-inquilino numa cloud nacional, pode escrever, por exemplo:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

Existe também uma substituição para o ADFS (o MSAL.NET só suporta o ADFS 2019 ou posterior):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Por fim, se fores um programador Azure AD B2C, podes especificar o teu inquilino assim:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

Consulte também

Documentação de referência da API

Pacote no NuGet

Código fonte da biblioteca

Amostras de código

Passos seguintes

Depois de inicializar a aplicação cliente, a sua próxima tarefa é adicionar suporte para login do utilizador, acesso autorizado à API, ou ambos.

A nossa documentação de cenários de aplicação fornece orientações para iniciar sessão num utilizador e adquirir um token de acesso para aceder a uma API em nome desse utilizador:

  • Last updated on