Microsoft Entra ID
O formulário da conexão Microsoft Entra ID, o app registration do tenant, as permissões do Graph, as mensagens do check e o harness login.
Toda organização no Microsoft 365 já tem um tenant do Entra. O Xokepoint usa um app registration desse tenant para três trabalhos: ler usuários e grupos pelo Microsoft Graph, autenticar pessoas a partir de um harness de código e servir de audience dos tokens do Entra que um serviço seu troca por tokens de agente. O administrador digita os três valores uma vez só.
Connection
- Connection name e Enable connection, como nas outras conexões.
Microsoft Entra app
O formulário guia em quatro passos, cada um com o link do guia da Microsoft:
- Register an app no Microsoft Entra admin center: Identity, Applications, App registrations, New registration, com "Accounts in this organizational directory only". No Overview do app, copie o Application (client) ID e o Directory (tenant) ID. Guia da Microsoft: registrar um aplicativo
- Create a client secret: Certificates & secrets, Client secrets, New client secret. Copie o Value na hora, porque o Entra mostra o valor uma única vez; o Secret ID não funciona. Todo secret tem data de validade: crie o próximo antes dela. Guia da Microsoft: adicionar um client secret
- Add the Graph permissions: API permissions, Add a permission, Microsoft Graph, Application permissions, depois
User.Read.AlleGroupMember.Read.All, e Grant admin consent. Só um Global Administrator ou um Privileged Role Administrator concede esse consentimento. As duas permissões são só de leitura. Guia da Microsoft: conceder admin consent - Paste the values nos três campos abaixo dos passos.
| Campo | O que preencher |
|---|---|
| Directory (tenant) ID | O GUID da sua organização. common, organizations, consumers e o tenant das contas pessoais da Microsoft são recusados. Onde achar o tenant ID |
| Application (client) ID | O GUID do app. Atende o diretório e o harness login |
| Client secret value | Guardado cifrado e nunca exibido de novo. Change troca o valor. Um tenant ID ou client ID novo pede o secret desse app |
Uma pessoa é identificada pelo object ID do tenant, o mesmo valor no token, no harness login e no Microsoft Graph. Trocar o nome ou o e-mail não muda esse identificador.
Convidados (guests), pessoas de outras organizações convidadas para o seu tenant, não aparecem na lista e não usam o Xokepoint.
Check connection
Check connection lê os metadados e as chaves de assinatura do tenant, obtém um token do Microsoft Graph com o secret, lê um usuário, lê os grupos e lê os grupos de uma pessoa. Cada mensagem aponta o passo que corrige o problema:
| Mensagem | Correção |
|---|---|
| Microsoft Entra does not know this tenant ID | Copie o Directory (tenant) ID do Overview do app |
| This application is not in the tenant | Confira o client ID e o tenant ID |
| Microsoft Entra rejected the secret | Cole o Value do secret, não o Secret ID |
| The client secret expired | Crie um secret novo (passo 2) |
| The app can not read users | Inclua User.Read.All e conceda o admin consent (passo 3) |
| The app can not read groups | Inclua GroupMember.Read.All e conceda o admin consent (passo 3). O harness login precisa dela |
| Microsoft Entra does not let the app read the groups of a person | Inclua Directory.Read.All e conceda o admin consent |
Request authentication
- Issuer URL: acompanha o tenant ID,
https://login.microsoftonline.com/<tenant ID>/v2.0. - Accepted audiences: o client ID e
api://<client ID>por padrão. Add audience inclui mais uma.
As audiences só importam quando um serviço seu troca um token do Entra de uma pessoa por um token de agente. Para isso, abra Expose an API no app, defina o Application ID URI (o padrão é api://<client ID>) e crie um scope; o serviço então pede ao Entra um token desse scope. Guia da Microsoft: expor uma API
O Xokepoint aceita access tokens v1.0 e v2.0, então o manifesto do app fica como o Entra cria. O token precisa ser de uma pessoa do tenant: um ID token, um token sem usuário (app-only) e um token de outro tenant são recusados.
Harness login
As pessoas entram a partir de um harness de código com a conta de trabalho da Microsoft (Harness login). O client de login é o mesmo app, então a seção tem só Allow harness login e a Redirect URI. Registre a redirect URI no app em Authentication, Add a platform, Web. Guia da Microsoft: adicionar uma redirect URI
A cada login, o Xokepoint lê os grupos da pessoa no Microsoft Graph com GroupMember.Read.All. Grupos de segurança e grupos do Microsoft 365, inclusive times do Teams, podem ser escolhidos num agente. Grupos aninhados não são seguidos: a pessoa precisa ser membro direto de um grupo escolhido.
Troca de tenant
Se você trocar o tenant ID de uma conexão salva, as pessoas associadas antes pertencem ao tenant anterior e perdem o acesso. O Xokepoint não bloqueia a troca.