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):

  • A ID do cliente (uma string que representa um GUID)
  • A URL do provedor de identidade (chamada de instância) e o público-alvo de entrada para seu aplicativo. Esses dois parâmetros são coletivamente conhecidos como autoridade.
  • A ID do locatário se você estiver escrevendo um aplicativo de linha de negócios somente para sua organização (também chamado de aplicativo de locatário único).
  • O segredo do aplicativo (cadeia de caracteres secreta do cliente) ou 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 redirectUri 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.

    var clientApp = PublicClientApplicationBuilder.Create(client_id)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenant_id)
    .Build();

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

    var clientApp = 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 que você pode definir em um construtor de aplicativos cliente confidencial são:

Modificador Descrição
.WithCertificate(X509Certificate2 certificate) Define o certificado que identifica o aplicativo com o Microsoft Entra ID.
.WithClientSecret(string clientSecret) Define o segredo do cliente (senha do aplicativo) que identifica o aplicativo com o Microsoft Entra ID.