Inicializar aplicativos cliente

3 minutos

Com o 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, ou de um arquivo de configuração, ou mesmo misturando ambas as abordagens.

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

ID do aplicativo (cliente) - Esta é uma cadeia de caracteres que representa um GUID.
ID de diretório (locatário) - Fornece recursos de gerenciamento de identidade e acesso (IAM) para aplicativos e recursos usados pela sua organização. Ele pode especificar se você está escrevendo um aplicativo de linha de negócios exclusivamente para 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 de entrada do seu aplicativo. Estes 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 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 broker), você precisa definir o URI de Redirecionamento onde o provedor de identidade entrará em contato com seu aplicativo com os tokens de segurança.

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

O código a seguir instancia um aplicativo cliente público, entrando usuários 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) 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();

Modificadores do construtor

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

.WithAuthority modificador: o .WithAuthority modificador define a autoridade padrão do aplicativo como uma autoridade do Microsoft Entra, com a possibilidade de escolher a Nuvem do Azure, a audiência, o locatário (ID do locatário ou nome de domínio) ou fornecer diretamente o URI da autoridade.
```
IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
    .Build();
```

.WithRedirectUri modificador: o .WithRedirectUri modificador 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 abaixo lista alguns dos modificadores que você pode definir em um cliente público ou confidencial.

Modificador	Description
`.WithAuthority()`	Define a autoridade padrão do aplicativo como uma autoridade do Microsoft Entra, com a possibilidade de escolher a Nuvem do Azure, a audiência, o locatário (ID do locatário ou nome de domínio) ou fornecer diretamente o URI da 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 corretor.
`.WithComponent(string)`	Define o nome da biblioteca usando MSAL.NET (por motivos de telemetria).
`.WithDebugLoggingCallback()`	Se chamado, o aplicativo chama `Debug.Write` simplesmente habilitando rastreamentos de depuração.
`.WithLogging()`	Se chamado, o aplicativo chama 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 de 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 lançará uma exceção significativa.

Inicializar aplicativos cliente

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

Modificadores do construtor

Modificadores comuns a aplicativos cliente públicos e confidenciais

Modificadores específicos para aplicativos cliente confidenciais

Comentários