Configuração de Login do Entra ID

O Power Portals Pro faz login com os usuários na Microsoft por meio do provedor padrão AddMicrosoftAccount da ASP.NET Core, que exige um registro de aplicativo no Microsoft Entra ID. O registro é o que informa à Entra que seu portal pode pedir logins, para onde pode enviar os usuários de volta e com quais credenciais ele irá se provar. Esta página percorre todas as propriedades das quais o portal realmente depende.

Este não é o aplicativo de conexão Dataverse

Dois registros separados estão envolvidos em um portal típico, e confundi-los é um erro comum na primeira execução. O aplicativo de conexão Dataverse é um principal de serviço que lê e escreve dados enquanto o próprio portal e suas credenciais ficam sob D365:ClientId / D365:ClientSecret. O registro descrito nesta página é apenas para logar usuários, e suas credenciais ficam em Authentication:Microsoft:ClientId / ClientSecret. Use dois registros — eles precisam de propriedades diferentes e têm raio de explosão muito diferente se forem vazados.

1. Registrar a Inscrição

Crie o registro no centro de administração do Microsoft Entra. Você precisa pelo menos do papel de Desenvolvedor de Aplicações no tenant.

1. Faça login no centro de administração do Entra e, se você pertencer a mais de um inquilino, use o ícone de Configurações para mudar para o inquilino que deve ser dono do registro. Um registro no aplicativo não pode ser movido entre inquilinos depois.
2. Navegue até Entra ID > Inscrições no aplicativo e selecione Novo registro.
3. Insira um Nome, por Contoso Portal Sign-Inexemplo. Os usuários veem esse nome na tela de consentimento, então faça algo que eles reconheçam como seu portal. Ele pode ser alterado depois.
4. Em Tipos de Conta Suportados, escolha o público que corresponde ao seu portal — veja a tabela abaixo. Esta é a propriedade que decide quem pode fazer login.
5. Selecione Registrar.
6. Na página de Visão Geral , copie o ID da aplicação (cliente). Esse valor se torna Authentication:Microsoft:ClientId.

Escolhendo Tipos de Conta Suportados

Essa configuração é a porta principal do portal. Escolha a opção mais estreita que ainda cubra todos que precisam fazer login:

Nota

O provedor ASP.NET Core Microsoft sempre autoriza contra o endpoint multi-audiência /common/ , então a configuração de Tipos de Conta Suportados do registro — não o código do seu aplicativo — é o que realmente aceita ou rejeita uma determinada conta. Se uma conta for recusada com AADSTS50020, o registro é mais restrito do que o público que você pretendia.

2. Adicionar o URI de Redirecionamento

Após um login bem-sucedido, o Entra envia o usuário de volta ao seu portal pelo caminho de retorno do provedor, que é /signin-microsoft. O Entra redireciona apenas para endereços registrados antecipadamente, então cada host onde seu portal roda precisa de sua própria entrada.

1. Abra Autenticação em Gerenciar, depois selecione Adicionar uma plataforma.
2. Escolha a plataforma Web — não a aplicação de página única. O servidor do portal realiza a troca de tokens usando o segredo do cliente, e isso permanece verdadeiro para hosts Blazor WebAssembly e React, onde o login ainda é feito do lado do servidor.
3. Insira o endereço do seu portal seguido por /signin-microsoft.
4. Repita para cada ambiente. A URL de desenvolvimento de launchSettings.json cada host implantado precisa de seu próprio URI de redirecionamento. Eles podem compartilhar um registro, ou você pode manter um registro separado por ambiente.

Importante

O URI de redirecionamento deve corresponder exatamente ao que o portal envia — esquema, host, porta e caminho. https://localhost:7228/signin-microsoft e https://localhost:7228/signin-microsoft/ não são o mesmo endereço, nem duas portas diferentes. Entra exige https para tudo, exceto localhost.

Se o portal rodar atrás de um proxy reverso, balanceador de carga ou entrada de contêiner que termina o TLS, configure o middleware de cabeçalhos encaminhados ASP.NET Core. Sem isso, o app acredita que a requisição chegou via HTTP simples e constrói um http:// URI de redirecionamento, que não corresponde ao registrado https:// .

3. Criar um Segredo de Cliente

O segredo é como seu portal prova que é realmente o aplicativo registrado quando troca o código de autorização por um token.

1. Abra Certificados e segredos em Gerenciar e selecione a aba Segredos do Cliente .
2. Selecione o segredo do novo cliente, dê uma descrição que nomeie o ambiente (por exemplo portal-production), e escolha um prazo de expiração.
3. Copie imediatamente a coluna Valor — não o ID Secreto. O valor é mostrado apenas uma vez, e ele se torna Authentication:Microsoft:ClientSecret.

Importante

Os segredos do cliente expiram, e 24 meses é o máximo. Quando um expira, todo login da Microsoft falha AADSTS7000215 até ser substituído, então acompanhe a data de expiração e rodíce antes dela. Para produção, credenciais de certificado ou credenciais de identidade federadas evitam completamente o problema do segredo que expira.

4. Verificar permissões da API

Um novo registro é concedido automaticamente no Microsoft Graph User.Read (delegado), e essa é a única permissão que o fluxo de login precisa. O provedor solicita o https://graph.microsoft.com/user.read escopo e lê o perfil do usuário logado de https://graph.microsoft.com/v1.0/me. Se alguém removeu essa permissão, adicione-a novamente sob permissões da API. Conceder consentimento de administrador é opcional na maioria dos tenants da força de trabalho, mas evita mostrar a cada usuário um prompt de consentimento no primeiro login; em inquilinos externos é obrigatório.

O Power Portals Pro lê o seguinte desse perfil ao vincular ou criar um usuário do portal:

Nota

A mail propriedade fica vazia para contas que não têm caixa de correio Exchange, caso em que o provedor volta a userPrincipalName. Um UPN nem sempre é um endereço de e-mail roteável — contas de convidados em particular possuem UPNs com formato semelhante user_contoso.com#EXT#@yourtenant.onmicrosoft.com — então, se seu portal corresponde aos usuários por e-mail, espere que essas contas não coincidam com um contato existente.

Adicionar as alegações de verificação por e-mail

O endereço de uma conta de trabalho ou escola é um diretório que o administrador do inquilino pode configurar para qualquer coisa, então, por padrão, o portal envia um e-mail de confirmação no primeiro login, em vez de confiar nele. A Entra pode atestar o endereço no token de ID, e o portal o trata como verificado quando isso acontece: quando verified_primary_email ou verified_secondary_email o lista, ou quando xms_edov diz que seu domínio é um que o próprio inquilino do usuário verificou. A Entra só envia essas reivindicações quando o registro as solicita:

1. Abra o registro e selecione Configuração de token.
2. Selecione + Adicionar reivindicação opcional, escolha o tipo de token ID , marque email, xms_edov, verified_primary_email e verified_secondary_emailselecione Adicionar. Quando solicitado, ative a permissão do Microsoft Graph email , que as reivindicações precisam. É uma permissão básica de login à qual os usuários podem consentir; em um tenant que só permite que administradores consentam com apps, um administrador aprova junto com o restante do app.

Ou adicione-os à optionalClaims seção do manifesto do registro e adicione a permissão delegada email do Microsoft Graph sob permissões da API:

Importante

Adicione-os ao token ID , não ao token de acesso. O portal os lê do token ID que a Microsoft retorna no login; as reivindicações do token de acesso só chegam a uma API que esse registro expõe, que o registro de login não possui. O servidor create_signin_app_registration MCP adiciona eles para você.

5. Armazene o ID do Cliente e o Segredo

O portal lê ambos os valores da configuração na seção Authentication:Microsoft . No desenvolvimento, mantenha-os em segredos de usuário em vez de appsettings.json nunca chegarem ao controle de versão:

Ou da linha de comando, no diretório do projeto servidor:

Dica

Em ambientes hospedados, forneça as mesmas chaves que as variáveis de ambiente ou de um armazenamento secreto. Variáveis de ambiente usam um duplo sublinhado em vez do dois-pontos — Authentication__Microsoft__ClientId e Authentication__Microsoft__ClientSecret — porque o separador dos dois-pontos não é portátil entre plataformas.

6. Habilitar o Provedor em Program.cs

Registre o provedor junto com o restante da sua configuração de autenticação no projeto Program.csde servidor:

O modelo de projeto escreve essa chamada para você quando você seleciona o Usuários Internos ou Ambos o público, ou quando opta pelo login da Microsoft para usuários Externos. Se você gerou o projeto sem ele, a mesma chamada é enviada para comentar em Program.cs — descomenta e forneça os dois valores de configuração.

7. Faça login e verifique

Execute o portal e abra a página de login. Um botão Microsoft agora aparece entre as opções de login. Na primeira vez que uma conta faz login, o portal vincula a identidade Microsoft a um usuário do portal — correspondendo a um contato existente por e-mail quando possível, caso contrário guiando o visitante pelo cadastro com o nome e o e-mail do perfil pré-preenchidos.

Se a conta também existir como Dataverse systemuser, a sessão pode rodar como esse usuário interno em vez de como contato. Esse comportamento não precisa de configuração extra no registro do app: Veja o Login do SystemUser

Diferenciando organizações

Com um registro multi-inquilino, pessoas de muitas organizações fazem login no mesmo portal. Cada login da Microsoft carrega seu id de inquilino Entra na sessão como a PortalClaimTypes.TenantId reivindicação, lido no User.GetTenantId() servidor e reportado como tenantId por GET /api/auth/me. Use-o para vincular uma sessão a uma organização, por exemplo, para verificar se alguém que reivindica um assento pertence ao inquilino que comprou. É a forma confiável de fazer isso: o ID do inquilino vem de um token assinado pela Microsoft, enquanto o endereço em uma conta de trabalho ou escola é o que o administrador daquela organização digitou.

Sessões assinadas de outra forma não têm tenant: contas locais, outros provedores e sessões personificadas, então um contato impersonável não pode passar por membro da organização do administrador.

Importante

Toda conta pessoal da Microsoft reporta o mesmo locatário, 9188040d-6c67-4c5b-b112-36a304b66dad (MicrosoftAccountEmailVerification.PersonalAccountTenantId). Ela não identifica nenhuma organização. Recuse-a onde quer que o inquilino represente um, ou toda conta pessoal conte como membro da mesma organização.

Solução de problemas

• AADSTS50011 — redirecionar incompatibilidade de URI. O endereço enviado pelo portal não está registrado. Compare o URI no erro com as entradas da plataforma Web caractere por caractere, incluindo a porta e a ausência de uma barra final.
• AADSTS7000215 — cliente inválido. Normalmente o ID do Segredo foi copiado em vez do Valor do segredo, ou o segredo expirou. Crie um novo segredo e atualize a configuração.
• AADSTS50020 — conta de usuário do provedor de identidade não existe no tenant. O login da conta está fora dos tipos de conta suportados pelo registro. Amplie a configuração para cobrir esse público.
• A ida e volta de login cai em http://. O portal está atrás de um proxy TLS-terminador sem middleware de cabeçalhos encaminhados configurado, então está gerando URIs de redirecionamento inseguros.
• Sem e-mail na nova conta. A conta Microsoft não tem caixa de correio e foi usada userPrincipalName em seu lugar. Veja a nota no passo 4.
• Todo login no trabalho ou escola recebe um e-mail de confirmação. O token de identificação não carrega nenhuma das reivindicações de verificação por e-mail. Verifique se eles estão no tipo de token de identificação em configuração de token, não apenas no token de acesso — veja Adicionar as reivindicações de verificação por e-mail na etapa 4.