Inicializar aplicativos cliente

  • 3 minutos

Com o MSAL.NET 3. x, a maneira recomendada para criar uma instância de um aplicativo é usando os contrutores de aplicativo: PublicClientApplicationBuilder e ConfidentialClientApplicationBuilder. Eles oferecem um mecanismo poderoso para configurar o aplicativo a partir do código ou de um arquivo de configuração, ou até mesmo misturando as duas abordagens.

Antes de inicializar um aplicativo, primeiro você precisa registrá-lo para que possa ser integrado à plataforma de identidade da Microsoft. Após o registro, talvez você precise das seguintes informações (que podem ser encontradas no portal do Azure):

  • ID do aplicativo (cliente) – É uma cadeia de caracteres que representa um GUID.
  • ID de diretório (locatário) – Fornece recursos de IAM (gerenciamento de identidade e acesso) para aplicativos e recursos usados pela sua organização. Ela pode especificar se você está escrevendo um aplicativo de linha de negócios somente para a sua organização (também chamado de aplicativo de locatário único).
  • A URL do provedor de identidade (chamada de instância) e o público-alvo de entrada para o seu aplicativo. Esses dois parâmetros são coletivamente conhecidos como autoridade.
  • Credenciais do cliente – que podem assumir a forma de um segredo de aplicativo (cadeia de caracteres de segredo do cliente) ou de um certificado (do tipo X509Certificate2) se for um aplicativo cliente confidencial.
  • Para aplicativos Web e, às vezes, para aplicativos cliente públicos (em particular quando seu aplicativo precisa usar um agente), você também terá definido o URI de redirecionamento em que o provedor de identidade entrará em contato com o seu aplicativo com os tokens de segurança.

Inicializar aplicativos cliente públicos e confidenciais a partir do código

O código a seguir instancia um aplicativo cliente público, usuários de entrada na nuvem pública do Microsoft Azure, com suas contas corporativas e de estudante, ou suas contas pessoais da Microsoft.

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

Da mesma forma, o código a seguir instancia um aplicativo confidencial (um aplicativo Web localizado em https://myapp.azurewebsites.net) manipulando 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();

Modificadores de Construtor

Nos snippets de código que usam construtores de aplicativos, vários métodos .With podem ser aplicados como modificadores (por exemplo, .WithAuthority e .WithRedirectUri).

  • Modificador .WithAuthority: O modificador .WithAuthority define a autoridade padrão do aplicativo como uma autoridade do Microsoft Entra, com a possibilidade de escolher o Azure Cloud, o público-alvo, o locatário (ID do locatário ou nome de domínio) ou fornecer diretamente o URI de autoridade.

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

  • Modificador .WithRedirectUri: o modificador .WithRedirectUri substitui o URI de redirecionamento padrão.

    IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(client_id)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenant_id)
    .WithRedirectUri("http://localhost")
    .Build();

Modificadores comuns a aplicativos cliente públicos e confidenciais

A tabela a seguir lista alguns dos modificadores que você pode definir em um cliente confidencial ou público.

Modificador Descrição
.WithAuthority() Define a autoridade padrão do aplicativo para uma autoridade do Microsoft Entra, com a possibilidade de escolher o Azure Cloud, o público-alvo, o locatário (ID do locatário ou nome de domínio) ou fornecer diretamente o URI de autoridade.
.WithTenantId(string tenantId) Substitui a ID do locatário ou a descrição do locatário.
.WithClientId(string) Substitui a ID do cliente.
.WithRedirectUri(string redirectUri) Substitui o URI de redirecionamento padrão. Isso é útil para cenários que exigem um agente.
.WithComponent(string) Define o nome da biblioteca usando MSAL.NET (para motivos de telemetria).
.WithDebugLoggingCallback() Se chamado, o aplicativo chamará Debug.Write simplesmente habilitando rastreamentos de depuração.
.WithLogging() Se chamado, o aplicativo fará um retorno de chamada com rastreamentos de depuração.
.WithTelemetry(TelemetryCallback telemetryCallback) Define o delegado usado para enviar telemetria.

Modificadores específicos para aplicativos cliente confidenciais

Os modificadores específicos para um construtor de aplicativos cliente confidencial podem ser encontrados na classe ConfidentialClientApplicationBuilder. 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.