Opções de configuração de aplicativo

Artigo
11/14/2023

Para autenticar e adquirir tokens, inicialize um novo aplicativo cliente público ou confidencial em seu código. É possível definir várias opções de configuração ao inicializar o aplicativo cliente na Biblioteca de Autenticação da Microsoft (MSAL). Essas opções se enquadram em dois grupos:

Opções de registro, incluindo:
- Autoridade (composta pela instância do provedor de identidade e pelo público de entrada para o aplicativo, e possivelmente pela ID do locatário)
- ID do Cliente
- URI de redirecionamento
- Segredo do cliente (para aplicativos cliente confidenciais)
Opções de log, incluindo nível de log, controle de dados pessoais e o nome do componente usando a biblioteca

Authority

A autoridade é uma URL que indica um diretório do qual o MSAL pode solicitar tokens.

As autoridades comuns são:

URLs de autoridade comum	Quando usar
`https://login.microsoftonline.com/<tenant>/`	Conectar somente usuários de uma organização específica. O `<tenant>` na URL é a ID do locatário do locatário do Microsoft Entra (um GUID) ou seu domínio de locatário.
`https://login.microsoftonline.com/common/`	Conectar usuários de contas corporativas ou de estudante ou contas pessoais da Microsoft
`https://login.microsoftonline.com/organizations/`	Conectar usuários com contas corporativas e de estudante.
`https://login.microsoftonline.com/consumers/`	Conectar usuários somente com a MSA (contas pessoais da Microsoft).

A autoridade que especificada no código precisa ser consistente com os Tipos de conta com suporte especificados para o aplicativo em Registros de aplicativo no portal do Azure.

A autoridade pode ser:

Uma autoridade de nuvem do Microsoft Entra.
Uma autoridade B2C do Azure AD. Consultar Especificações de B2C.
Uma autoridade do AD FS (Serviços de Federação do Active Directory). Consulte Suporte ao AD FS.

As autoridades de nuvem do Microsoft Entra têm duas partes:

A instância do provedor de identidade
O público para entrar no aplicativo

A instância e o público podem ser concatenados e fornecidos como a URL da autoridade. Este diagrama mostra como a URL da autoridade é composta:

Como a URL da autoridade é composta

Instância da nuvem

A instância é usada para especificar se o aplicativo está assinando usuários da nuvem pública do Azure ou de nuvens nacionais. Usando o MSAL no código, é possível definir a instância de nuvem do Azure usando uma enumeração ou passando a URL para a instância de nuvem nacional como o membro Instance.

OMSAL.NET gerará uma exceção explícita se Instance and AzureCloudInstance forem especificadas.

Se não for especificada uma instância, o aplicativo será direcionado para a instância de nuvem pública do Azure (a instância de URL https://login.onmicrosoftonline.com).

Público do aplicativo

O público depende das necessidades de negócios para o aplicativo:

Um desenvolvedor de LOB (linha de negócios), provavelmente produzirá um aplicativo de locatário único que será usado somente na organização. Nesse caso, especifique a organização por sua ID de locatário (a ID de sua instância do Microsoft Entra) ou por um nome de domínio associado à instância do Microsoft Entra.
Um ISV talvez queira conectar usuários com suas contas corporativas e de estudante em qualquer organização ou em algumas organizações (aplicativo multilocatário). Mas talvez também se queira fazer com que os usuários entrem com suas contas pessoais da Microsoft.

Como especificar o público no código/configuração

Usando o MSAL em seu código, especifique o público usando um dos seguintes valores:

A enumeração de audiência de autoridade do Microsoft Entra
A ID do locatário, que pode ser:
- Um GUID (o ID da sua instância do Microsoft Entra), para aplicativos de locatário único
- Um nome de domínio associado à instância do Microsoft Entra (também para aplicativos de locatário único)
Um desses espaços reservados como uma ID de locatário no lugar da enumeração de audiência de autoridade do Microsoft Entra:
- organizations para aplicativo multilocatário
- consumers para conectar usuários somente com contas pessoais
- common para conectar usuários de contas corporativas ou de estudante ou contas pessoais da Microsoft

O MSAL gerará uma exceção significativa se forem especificados o público da autoridade do Microsoft Entra e a ID do locatário.

É recomendável especificar um público-alvo, pois muitos locatários e os aplicativos implantados neles terão usuários convidados. Se seu aplicativo tiver usuários externos, é melhor evitar os pontos de extremidade de common e organization. Se você não especificar um público-alvo, seu aplicativo segmentará o Microsoft Entra e as contas Microsoft pessoais como um público-alvo e se comportará como se common tivesse sido especificado.

Público efetivo

O público efetivo para o aplicativo será o mínimo (se houver uma interseção) do público que definido no aplicativo e o público especificado no registro do aplicativo. Na verdade, a experiência de Registros de aplicativo permite especificar o público (os tipos de conta com suporte) para o aplicativo. Para obter mais informações, confira Início Rápido: Registrar um aplicativo na plataforma de identidade da Microsoft.

Atualmente, a única maneira de obter um aplicativo para conectar usuários com apenas contas pessoais da Microsoft é definir essas duas configurações:

Defina o público de registro do aplicativo como Work and school accounts and personal accounts.
Defina o público no código/configuração como AadAuthorityAudience.PersonalMicrosoftAccount (ou TenantID = "consumidores").

ID do Cliente

A ID do cliente é a ID exclusiva do aplicativo (cliente) atribuída ao aplicativo pelo Microsoft Entra ID quando o aplicativo foi registrado. Você pode encontrar a ID do Aplicativo (Cliente) na página Visão Geral do aplicativo em Identidade>Aplicativos> Aplicativos empresariais.

URI de redirecionamento

O URI de redirecionamento é o URI para o qual o provedor de identidade enviará os tokens de segurança.

URI de redirecionamento para aplicativos cliente públicos

Se for um desenvolvedor de aplicativo cliente público que está usando o MSAL:

É recomendável o uso de .WithDefaultRedirectUri() em aplicativos da área de trabalho ou da UWP (Plataforma Universal do Windows) (MSAL.NET 4.1+). O método .WithDefaultRedirectUri() definirá a propriedade URI de redirecionamento do aplicativo cliente público para o URI de redirecionamento recomendado padrão para aplicativos cliente públicos.

Plataforma	URI de redirecionamento
Aplicativo de desktop (.NET Framework)	`https://login.microsoftonline.com/common/oauth2/nativeclient`
UWP	valor de `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`. Isso habilita o SSO (logon único) com o navegador definindo o valor como o resultado de WebAuthenticationBroker. GetCurrentApplicationCallbackUri () que precisa ser registrado
.NET	`https://localhost` permite que o usuário use o navegador do sistema para autenticação interativa, pois o .NET não tem uma interface do usuário para a exibição da Web inserida no momento.

Não é necessário adicionar um URI de redirecionamento se um aplicativo for criado com Xamarin Android e iOS que não dá suporte ao URI de redirecionamento do agente. Ele é definido automaticamente como msal{ClientId}://auth para o Xamarin Android e iOS.
Configurar o URI de redirecionamento em Registros de aplicativo:

É possível substituir o URI de redirecionamento usando a propriedade RedirectUri (por exemplo, se são usados agentes). Aqui estão alguns exemplos de URIs de redirecionamento para esse cenário:

RedirectUriOnAndroid = "msauth-5a434691-ccb2-4fd1-b97b-b64bcfbc03fc://com.microsoft.identity.client.sample";
RedirectUriOnIos = $"msauth.{Bundle.ID}://auth";

Para obter mais informações do iOS, consulte Migrar aplicativos iOS que usam Microsoft Authenticator de ADAL.NET para MSAL.Net e Aproveitar o agente no iOS. Para obter mais informações do Android, consulte Autenticação orientada no Android.

URI de redirecionamento para aplicativos cliente confidenciais

Para aplicativos Web, o URI de redirecionamento (ou URL de resposta) é o URI que o Microsoft Entra ID usará para enviar o token de volta para o aplicativo. O URI pode ser a URL do aplicativo Web/API Web se o aplicativo confidencial for um deles. O URI de redirecionamento precisa ser registrado no registro do aplicativo. O registro é especialmente importante quando é implantado um aplicativo testado inicialmente de forma local. Em seguida, é necessário adicionar a URL de resposta do aplicativo implantado no portal de registro de aplicativo.

Para aplicativos de daemon, não é necessário especificar um URI de redirecionamento.

Segredo do cliente

Esta opção especifica o segredo do cliente para o aplicativo cliente confidencial. O segredo do cliente (senha de aplicativo) é fornecido pelo portal de registro de aplicativo ou fornecido ao Microsoft Entra ID durante o registro do aplicativo com o PowerShell do Microsoft Entra ID, o PowerShell AzureRM ou a CLI do Azure.

Log

Para ajudar em cenários de solução de problemas de falha de depuração e autenticação, o MSAL fornece suporte de log interno. O registro em log em cada biblioteca é abordada nos seguintes artigos:

Próximas etapas

Saiba mais sobre como Criar uma instância de aplicativos cliente usando o MSAL.net e Instanciar aplicativos cliente usando MSAL.js.