Conecte a Microsoft e o Google

Como uma conexão funciona

• Provedor e modo. provider é microsoft ou google. mode é own_app, seu próprio aplicativo do Microsoft Entra ou conta de serviço do Google, ou screenrig_app, o aplicativo do screenRIG, que um administrador do Microsoft 365 ou o titular de uma conta do Google aprova.
• Status. Uma conexão fica em pending_consent até que alguém aprove o aplicativo do screenRIG. Ela fica ready enquanto tiver credenciais que a última tentativa não recusou, e error quando a Microsoft ou o Google as recusou: last_error diz por quê, e um sucesso posterior a leva de volta a ready. Uma limitação de taxa ou uma queda não muda nada.
• Segredos permanecem selados. Um segredo, uma chave ou um token de atualização nunca é mostrado de novo. Uma leitura mostra se há um guardado e uma dica: os quatro últimos caracteres de um segredo de cliente da Microsoft ou o endereço de uma conta de serviço do Google.
• Teste. Um teste faz login e guarda o resultado. No Microsoft, ele também lista as permissões de aplicativo do Graph que o token obtido carrega.
• Altere. Alterar as credenciais do seu próprio aplicativo leva a conexão de volta a ready e limpa o último erro. Uma conexão no modo aplicativo do screenRIG só pode ser renomeada: peça um novo link de consentimento para mudar quem a aprovou.
• Exclua. A exclusão é recusada (resource_conflict) enquanto uma fonte, uma conexão do Power BI ou uma conta de sincronização de mídia ler por meio da conexão. Ela não encerra o lado do fornecedor: o tenant mantém o aplicativo do screenRIG até que um administrador o remova, e uma conta do Google mantém sua concessão até que seu titular a revogue.
• Limite. Uma organização tem até 50 conexões em todos os seus projetos.

Seu próprio aplicativo ou o do screenRIG

Microsoft

Seu próprio aplicativo

Registre um aplicativo no centro de administração do Microsoft Entra, adicione um segredo de cliente (copie o valor dele, não o ID), dê ao aplicativo as permissões de aplicativo abaixo e conceda o consentimento do administrador. Crie a conexão com o ID do diretório ou o domínio primário como config.tenant_id (common, organizations e consumers são recusados), o ID do aplicativo como config.client_id e o valor do segredo de cliente como secret.

O aplicativo do screenRIG, com consentimento do administrador

Crie a conexão no modo screenrig_app, sem configurações e sem segredo. A resposta traz consent_url, um link de uso único válido por 24 horas. Envie-o a um administrador do Microsoft 365 e a mais ninguém: ele é a credencial desse único consentimento.

1. O administrador abre o link e aprova o aplicativo do screenRIG para o tenant.
2. O Microsoft volta ao screenRIG, que pede ao administrador que faça login nesse tenant. A conexão registra o tenant em que o login foi feito, nunca um que uma solicitação apenas afirme.
3. O screenRIG faz login uma vez no tenant com a permissão que recebeu. A conexão passa a ready.

Um link funciona uma vez. Um link mais novo, um consentimento concluído ou uma exclusão encerra um mais antigo, e você pode pedir um novo link a qualquer momento: para renovar uma conexão que passou a error, ou para associar outro tenant. Se o administrador recusar ou o login não for concluído, a conexão registra consent_denied ou consent_failed (com o código AADSTS da Microsoft) e mantém o consentimento pendente, de modo que o mesmo link pode ser aberto de novo. Uma conexão que já funciona nunca é degradada por um segundo consentimento recusado. Se o tenant remover o aplicativo do screenRIG, a conexão indica consent_revoked: peça a um administrador que aprove de novo.

A aprovação vale por tenant. Depois que um administrador aprova o aplicativo do screenRIG, qualquer pessoa que consiga fazer login no tenant pode conectá-lo a um projeto próprio, então restrinja o que o aplicativo pode ler, como abaixo. Excluir o aplicativo empresarial no Microsoft Entra encerra o acesso de todos os projetos.

O que o aplicativo pode ler

Um teste de conexão lista quais destas permissões o token carrega. Ele avisa quando só Sites.Selected está presente, porque cada site ainda precisa da sua concessão, e falha quando nenhuma está.

Google

Seu próprio aplicativo

Crie uma conta de serviço no Google Cloud, ative a API do Google Calendar e baixe a chave JSON dela (no máximo 16 KiB). Entregue à conexão o arquivo inteiro como secret: o screenRIG o verifica ao salvar. Depois compartilhe cada agenda de sala com o endereço da conta de serviço, ou ative a delegação em todo o domínio para a conta no console de administração com o escopo https://www.googleapis.com/auth/calendar.events.readonly e informe um subject na fonte.

O aplicativo do screenRIG

O link de consentimento abre a página de consentimento do Google. O titular da conta concede acesso somente leitura aos eventos da agenda (o escopo calendar.events.readonly, com openid e email para que o screenRIG saiba qual conta aprovou). Se a pessoa desmarcar a permissão da agenda, o consentimento falha. Uma fonte lê as agendas que essa conta pode ver, então a conta precisa ver cada agenda de sala que a fonte lista, e uma fonte de uma conexão assim não pode informar um subject. Quando o Google deixa de honrar a concessão, a conexão indica reconnect_required: peça um novo link.

Usar uma conexão

• Fontes de salas de reunião. Defina connection_id em uma fonte microsoft365 ou google_calendar no lugar de tenant, client_id e client_secret, ou de service_account_key. Os dois modos servem. As credenciais embutidas continuam funcionando, mas não podem ser combinadas com connection_id.
• Sincronização de mídia do SharePoint e do OneDrive. Uma conta de sincronização do Microsoft 365 aceita connection_id no lugar de tenant_id, client_id e secret.
• Power BI. Uma conexão do Power BI aceita o connection_id de uma conexão da Microsoft no modo own_app, no lugar do próprio tenant, ID de cliente e segredo. A Microsoft não descreve um aplicativo de outro tenant gerando tokens de incorporação no tenant de um cliente, então o aplicativo do screenRIG é recusado para o Power BI. Um administrador do Power BI ainda precisa ativar as configurações de entidade de serviço e adicionar o aplicativo a cada workspace.

Uma fonte cuja conexão está ausente, aguardando aprovação ou é do outro provedor indica config_invalid. Quando a Microsoft ou o Google recusa o login, a fonte indica auth_failed e a conexão passa a error.

Criar uma

Crie uma conexão no dashboard ou com POST /api/connections. Para seu próprio aplicativo da Microsoft:

{
  "provider": "microsoft",
  "mode": "own_app",
  "name": "Contoso rooms",
  "config": {"tenant_id": "contoso.com", "client_id": "CLIENT_ID"},
  "secret": "CLIENT_SECRET_VALUE"
}

Para o aplicativo do screenRIG, sem configurações e sem segredo:

{"provider": "google", "mode": "screenrig_app", "name": "Campus rooms"}

A resposta à segunda traz consent_url e consent_expires_at: envie o link à pessoa que aprova. POST /api/connections/ID/connect cria um novo link, e POST /api/connections/ID/test faz login e guarda o resultado. Mantenha os segredos no arquivo da solicitação, não na linha de comando.

connection_app_not_configured significa que o servidor não tem aplicativo do screenRIG para esse provedor: crie a conexão com seu próprio aplicativo. connection_limit_reached significa que a organização tem 50: exclua uma que nada lê, ou reutilize uma conexão existente.

Relacionado

• Fontes de dados: as fontes de salas que usam uma conexão.
• Referência da API: todas as rotas de conexão.
• Login único: como as pessoas fazem login. Uma conexão serve para trabalho que roda sem ninguém conectado.