Inicializar aplicativos cliente usando MSAL.NET

Este artigo descreve a inicialização de aplicativos cliente públicos e clientes confidenciais usando o Biblioteca do Microsoft Authenticator para .NET (MSAL.NET). Para saber mais sobre os tipos de aplicativo cliente, consulte o cliente público e os aplicativos cliente confidenciais.

Com MSAL.NET 3.x, a maneira recomendada de instanciar um aplicativo é usando os construtores de aplicativos: PublicClientApplicationBuilder e ConfidentialClientApplicationBuilder. Eles oferecem um mecanismo poderoso para configurar o aplicativo a partir do código, um arquivo de configuração ou até mesmo combinando ambas as abordagens.

Pré-requisitos

Antes de inicializar um aplicativo, primeiro você precisa registrá-lo para que seu aplicativo possa ser integrado ao plataforma de identidade da Microsoft. Consulte o Início Rápido: registrar um aplicativo com o plataforma de identidade da Microsoft para obter mais informações. Após o registro, você precisará das informações a seguir, que podem ser encontradas na página de registro do aplicativo no centro de administração do Microsoft Entra.

  • ID do aplicativo (cliente) – essa é uma cadeia de caracteres que representa um GUID.
  • ID do diretório (locatário) – fornece recursos de IAM (gerenciamento de identidade e acesso) para aplicativos e recursos usados pela sua organização. Ele pode especificar se você está escrevendo um aplicativo de linha de negócios apenas para sua organização (também chamado de aplicativo de locatário único).
  • A URL do provedor de identidade (chamada de instance) e o público de login da sua aplicação. Esses dois parâmetros são coletivamente conhecidos como autoridade.
  • Credenciais do cliente - que podem assumir a forma de um segredo do aplicativo (cadeia de caracteres de segredo do cliente) ou certificado (do tipo X509Certificate2) se for um aplicativo cliente confidencial.
  • Para aplicativos Web e, às vezes, para aplicativos cliente público (em particular quando seu aplicativo precisa usar um broker), você precisa definir o URI de redirecionamento para a qual o provedor de identidade redirecionará de volta o seu aplicativo com os tokens de segurança.

Inicializando aplicativos

Há muitas maneiras diferentes de instanciar aplicativos cliente.

Inicializando um aplicativo cliente público por meio de código

O código a seguir cria uma instância de um aplicativo cliente público, conectando usuários na nuvem pública Microsoft Azure, com suas contas Microsoft corporativas, de estudante ou pessoais.

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

Inicializando uma aplicação cliente confidencial por meio do código

Da mesma forma, o código a seguir instancia um aplicativo confidencial (um aplicativo Web localizado em https://myapp.azurewebsites.net) que manipula tokens de usuários na nuvem pública do Microsoft Azure, com suas contas corporativas e de estudante ou suas contas pessoais da Microsoft. O aplicativo é identificado com o provedor de identidade compartilhando um segredo do cliente:

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

Na produção, no entanto, os certificados são recomendados, pois são mais seguros do que os segredos do cliente. Eles podem ser criados e carregados no centro de administração do Microsoft Entra. Em seguida, o código seria o seguinte:

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

Inicializando um aplicativo cliente público a partir de opções de configuração

O código a seguir cria uma instância de um aplicativo cliente público com base em um objeto de configuração, que pode ser preenchido programaticamente ou lido de um arquivo de configuração:

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

Inicializando um aplicativo cliente confidencial a partir de opções de configuração

O mesmo tipo de padrão se aplica a aplicativos cliente confidenciais. Você também pode adicionar outros parâmetros usando .WithXXX modificadores. Este exemplo usa .WithCertificate.

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

Modificadores do Builder

Nos snippets de código usando construtores de aplicativos, muitos .With métodos podem ser aplicados como modificadores (por exemplo, .WithCertificate e .WithRedirectUri).

Modificadores comuns a aplicativos cliente públicos e confidenciais

Os modificadores que você pode definir em um cliente público ou no construtor de aplicativos cliente confidencial podem ser encontrados na AbstractApplicationBuilder<T> classe. Os diferentes métodos podem ser encontrados na documentação do SDK do Azure para .NET.

Modificadores específicos para aplicativos Xamarin.iOS

Os modificadores que você pode definir em um construtor de aplicativos cliente público no Xamarin.iOS são:

Modificador Description
.WithIosKeychainSecurityGroup() somente Xamarin.iOS: define o grupo de segurança da cadeia de chaves do iOS (para a persistência do cache).

Modificadores específicos para aplicativos cliente confidenciais

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

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

Exemplo de uso de modificadores

Vamos supor que seu aplicativo seja um aplicativo de linha de negócios, que é apenas para sua organização. Em seguida, você pode escrever:

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

A programação para nuvens nacionais foi simplificada, portanto, se você quiser que seu aplicativo seja um aplicativo multilocatário em uma nuvem nacional, você pode escrever, por exemplo:

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

Também há uma substituição para o ADFS (MSAL.NET só dá suporte ao ADFS 2019 ou posterior):

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

Por fim, se você for um desenvolvedor do Azure AD B2C, poderá especificar seu locatário 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

Exemplos de código

Próximas Etapas 

Depois de inicializar o aplicativo cliente, sua próxima tarefa é adicionar suporte para entrada do usuário, acesso autorizado à API ou ambos.

Nossa documentação do cenário de aplicativo fornece diretrizes para entrar em um usuário e adquirir um token de acesso para acessar uma API em nome desse usuário:

  • Last updated on