Registrar um Aplicativo no Microsoft Graph

O pipeline de reuniões do Teams lê transcrições, gravações e artefatos relacionados no Microsoft Graph usando autenticação app-only (daemon) — sem login de usuário, sem consentimento interativo por reunião. Isso exige um registro de aplicativo no Azure AD com permissões de aplicativo consentidas por um administrador.

Este guia cobre:

1. Criar o registro do aplicativo
2. Criar um segredo de cliente
3. Conceder as permissões da API do Graph que o pipeline precisa
4. Dar o consentimento de administrador nessas permissões
5. (Opcional) Limitar o aplicativo a usuários específicos com uma Application Access Policy

Você precisa de direitos de administrador do tenant (ou de um administrador que conceda o consentimento no seu lugar) para concluir isto. Guarde os valores que você coletar — eles vão para o ~/.hermes/.env no final.

Pré-requisitos

• Um tenant do Microsoft 365 com Teams Premium ou licenças do Teams que produzam transcrições e gravações de reunião
• Acesso de administrador ao portal do Azure em entra.microsoft.com
• Um endpoint HTTPS acessível publicamente para as notificações de mudança do Graph (configurado depois, na etapa do listener de webhook)

Etapa 1: crie o registro do aplicativo

1. Entre em entra.microsoft.com como administrador do tenant.
2. Vá em Identity → Applications → App registrations.
3. Clique em New registration.
4. Preencha:
   • Name: Hermes Teams Meeting Pipeline (ou qualquer nome que você reconheça).
   • Supported account types: Accounts in this organizational directory only (Single tenant).
   • Redirect URI: deixe em branco — a autenticação app-only não precisa de uma.
5. Clique em Register.

Você vai cair na página de visão geral do aplicativo. Copie dois valores:

• Application (client) ID → MSGRAPH_CLIENT_ID
• Directory (tenant) ID → MSGRAPH_TENANT_ID

Etapa 2: crie um segredo de cliente

1. No menu à esquerda, abra Certificates & secrets.
2. Clique em New client secret.
3. Description: hermes-graph-secret. Expires: escolha um valor que combine com a sua política de rotação (6 a 24 meses é o normal).
4. Clique em Add.
5. Copie a coluna Value na hora — ela só aparece uma vez. Esse valor é o MSGRAPH_CLIENT_SECRET.

A coluna Secret ID não é o segredo. Você quer a coluna Value.

Etapa 3: conceda as permissões da API do Graph

O pipeline usa um conjunto mínimo viável de permissões de aplicativo. Adicione só o que você precisa; cada uma amplia o que o aplicativo consegue ler em todo o tenant.

1. No menu à esquerda, abra API permissions.
2. Clique em Add a permission → Microsoft Graph → Application permissions.
3. Adicione, da tabela abaixo, as permissões que correspondem ao que você quer que o pipeline faça.
4. Depois de adicionar, clique em Grant admin consent for <seu tenant>. A coluna Status deve virar um sinal verde em cada permissão.

Necessárias para resumos a partir da transcrição

Permissão	O que ela libera para o aplicativo
OnlineMeetings.Read.All	Ler metadados de reuniões online do Teams (assunto, participantes, URL de entrada).
OnlineMeetingTranscript.Read.All	Ler as transcrições de reunião geradas pelo Teams.

Necessárias para o plano B da gravação (quando não há transcrição)

Permissão	O que ela libera para o aplicativo
OnlineMeetingRecording.Read.All	Baixar gravações de reunião do Teams para processamento de STT offline.
CallRecords.Read.All	Resolver reuniões a partir dos registros de chamada quando só a URL de entrada é conhecida.

Necessárias para a entrega do resumo (só no modo Graph)

Se platforms.teams.extra.delivery_mode estiver como graph, o pipeline publica os resumos em um canal ou conversa do Teams pela API do Graph. Pule estas se você usar o modo de entrega incoming_webhook.

Permissão	O que ela libera para o aplicativo
ChannelMessage.Send	Publicar mensagens em canais do Teams em nome do aplicativo.
Chat.ReadWrite.All	Publicar mensagens em conversas individuais e de grupo (só se você definir chat_id como destino de entrega).

Não recomendadas

• OnlineMeetings.ReadWrite.All / Chat.ReadWrite sem o .All — mais amplas do que o pipeline precisa.
• Permissões delegadas — o pipeline usa o fluxo app-only (client credentials); permissões delegadas não funcionam sem login de usuário.

Etapa 4: (recomendado) limite o aplicativo com uma Application Access Policy

Por padrão, permissões de aplicativo como OnlineMeetings.Read.All dão ao aplicativo acesso a todas as reuniões do tenant. Para demonstrações com parceiros e tenants de desenvolvimento tudo bem; em produção você quase certamente quer restringir de quais usuários o aplicativo pode ler as reuniões.

A Microsoft oferece as Application Access Policies do Teams exatamente para isso. A política só existe via PowerShell; não há interface no portal.

Em um PowerShell de administrador com o módulo MicrosoftTeams instalado e conectado (Connect-MicrosoftTeams):

# Crie uma política restrita ao aplicativo do Hermes
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restringe o pipeline de reuniões do Hermes aos usuários da lista"

# Conceda a política aos usuários cujas reuniões o pipeline pode ler
Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "alice@exemplo.com"

Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "bruno@exemplo.com"

A propagação pode levar até 30 minutos depois da concessão. Verifique com:

Test-CsApplicationAccessPolicy -Identity "alice@exemplo.com" -AppId "<MSGRAPH_CLIENT_ID>"

Sem a política, as reuniões de qualquer usuário ficam legíveis — é isso que a permissão tecnicamente concede. Não pule esta etapa em um tenant de produção.

Etapa 5: escreva as credenciais no seu arquivo de ambiente

Coloque os três valores que você coletou no ~/.hermes/.env:

MSGRAPH_TENANT_ID=<id-do-diretorio-tenant>
MSGRAPH_CLIENT_ID=<id-do-aplicativo-cliente>
MSGRAPH_CLIENT_SECRET=<valor-do-segredo-de-cliente>

Ajuste as permissões do arquivo para que só você consiga ler o segredo:

chmod 600 ~/.hermes/.env

Etapa 6: verifique o fluxo de token

O Hermes traz um teste rápido de autenticação no Graph. A partir da sua instalação do Hermes:

python -c "
import asyncio
from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Token acquired, length:', len(token))
print(provider.inspect_token_health())
"

Uma execução bem-sucedida imprime um token longo e um dicionário de saúde mostrando cached: True e um expires_in_seconds perto de 3600. As falhas produzem um MicrosoftGraphTokenError com o código de erro do Azure — os mais comuns são:

Erro do Azure	Significado	Correção
AADSTS7000215: Invalid client secret	Valor do segredo errado ou expirado.	Gere um segredo novo na etapa 2; atualize o .env.
AADSTS700016: Application not found	MSGRAPH_CLIENT_ID errado ou tenant errado.	Confira se os valores da etapa 1 vieram do mesmo aplicativo.
AADSTS90002: Tenant not found	Erro de digitação no MSGRAPH_TENANT_ID.	Copie de novo o Directory (tenant) ID da visão geral do aplicativo.
insufficient_claims na hora da chamada (não na do token)	O token é obtido, mas o Graph devolve 401/403.	Você pulou o consentimento de administrador da etapa 3, ou adicionou permissões sem consentir de novo. Volte em API permissions e clique em Grant admin consent outra vez.

Rotacionar o segredo de cliente

Os segredos de cliente do Azure têm expiração rígida. Antes que o seu expire:

1. Crie um segundo segredo de cliente na etapa 2 sem apagar o primeiro.
2. Atualize o MSGRAPH_CLIENT_SECRET no ~/.hermes/.env com o novo valor.
3. Reinicie o gateway para que o novo segredo seja carregado: hermes gateway restart.
4. Verifique com o teste rápido acima.
5. Apague o segredo antigo no portal do Azure.

Próximos passos

Assim que as credenciais forem verificadas sem erro, siga com:

• Configuração do listener de webhook — suba a plataforma de gateway msgraph_webhook, que recebe as notificações de mudança do Graph.
• Configuração do pipeline — configure o runtime do pipeline de reuniões do Teams e a CLI de operação.
• Entrega de saída — leve os resumos de volta para um canal ou conversa do Teams.

Essas páginas chegam junto com os PRs que adicionam o runtime correspondente. Esta configuração de credenciais é um pré-requisito independente e pode ser feita com antecedência.

---