Integrações — Credenciais e Permissões Exigidas do Cliente

🔴 NÃO PUBLICAR NO WORDPRESS. Este documento é interno.

Ele está dentro da árvore de documentação de clientes por conveniência de consulta, e não é um tutorial de cliente. O conteúdo inclui orientação comercial interna (“não ofereça ao cliente”, “não prometa cobertura de Slack”), a lista de integrações fora do ar e a seção de lacunas conhecidas do produto. Publicar isso expõe roadmap e fragilidades.

A versão para o cliente está em 05. Integrações › Guias por provedor, um documento por provedor, escrito a partir daqui mas sem as partes internas. Os princípios gerais (somente leitura, nenhum dado de conteúdo, credencial cifrada, permissão faltando nunca reprova) estão no tutorial Integrações – Para que servem e como os testes usam os dados, que é público.

Mantido intacto porque é a melhor fonte de verdade que existe sobre permissões mínimas. Se as exigências mudarem no código, atualize aqui primeiro.

—

Referência interna para o time de onboarding e suporte: o que cada integração ativa da plataforma exige do cliente, qual a permissão mínima, e a frase pronta que pode ser enviada ao cliente sem adaptação.

Levantado a partir do código em 2026-08-24 (`apps/customer/src/app/[locale]/integrations/[provider]/page.tsx` para os campos, `apps/worker/src/checks//` para as chamadas de API reais). Nenhuma dessas exigências estava documentada antes — não existe lista de permissões no produto, no catálogo ou na UI.

Princípios que valem para todas as integrações

• Somente leitura. Nenhuma verificação da Imara escreve, altera ou apaga qualquer coisa no ambiente do cliente. A única exceção é a AWS, onde `iam:GenerateCredentialReport` dispara a geração de um relatório (a própria AWS classifica essa ação como não-leitura).
• Nenhum dado de conteúdo é lido. As verificações leem *configuração* — não leem objetos de bucket, registros de banco, e-mails, mensagens nem segredos armazenados.
• Credenciais são cifradas em repouso antes de serem gravadas, e nunca aparecem em log ou em resposta de API.
• Permissão faltando nunca gera reprovação. Quando o token não alcança um recurso, a verificação vira `NOT_RUN` ou `MANUAL` com a mensagem do motivo — nunca um `FAIL` inventado. Se o cliente cortar permissões, o efeito é perda de cobertura, não queda de score.
• Sempre prefira uma credencial de serviço dedicada, não a chave pessoal de um administrador. Isso mantém o rastro de auditoria limpo e permite revogar o acesso da Imara sem afetar ninguém.

—

Infraestrutura de nuvem

AWS

Campos no Imara: Access Key ID · Secret Access Key · Região (opcional, padrão `us-east-1`)

Permissão mínima: políticas gerenciadas `SecurityAudit` + `ViewOnlyAccess`, mais uma política inline com `iam:GenerateCredentialReport`.

Frase para o cliente:

Crie um usuário IAM com acesso programático, anexe as políticas gerenciadas `SecurityAudit` e `ViewOnlyAccess` mais uma política inline permitindo `iam:GenerateCredentialReport`, e nos envie o Access Key ID, o Secret Access Key e a região principal do seu ambiente.

Atenção

• São 320 operações de leitura em 70 serviços (IAM, EC2, S3, RDS, KMS, CloudTrail, GuardDuty, SecurityHub, SageMaker, Bedrock, WAF, Organizations e outros). Por isso duas políticas gerenciadas em vez de uma lista manual.
• `SecurityAudit` sozinha não cobre SageMaker, Bedrock, Macie, Inspector2, Transfer, Route 53 Domains e Global Accelerator — daí o `ViewOnlyAccess`.
• `ReadOnlyAccess` também funcionaria, mas concede leitura de dados (conteúdo de S3, itens do DynamoDB) que a Imara nunca usa. A própria plataforma tem uma verificação que sinaliza `ReadOnlyAccess` concedida a terceiros como achado.
• A integração não suporta assumir role com ExternalId — só chave estática de usuário IAM. Se o cliente exigir cross-account role, hoje não temos esse caminho.
• A região informada define onde as verificações regionais rodam. Ambiente multi-região tem cobertura apenas da região configurada.

Azure

Campos no Imara: Tenant ID · Client ID · Client Secret · Subscription ID

Permissão mínima: funções `Reader` e `Security Reader` na assinatura + permissões de aplicativo do Microsoft Graph `Directory.Read.All`, `Policy.Read.All`, `Application.Read.All`, `AuditLog.Read.All`, todas com consentimento do administrador.

Frase para o cliente:

Crie um App Registration no Entra ID, atribua a ele as funções `Reader` e `Security Reader` na assinatura, conceda as permissões de aplicativo do Microsoft Graph `Directory.Read.All`, `Policy.Read.All`, `Application.Read.All` e `AuditLog.Read.All` com consentimento do administrador, e nos envie Tenant ID, Client ID, Client Secret e Subscription ID.

Atenção

• O formulário marca Subscription ID como opcional, mas ele é obrigatório: sem ele todas as verificações de ARM (storage, SQL, VM, Key Vault, Defender) falham na validação de credencial. Sempre peça os quatro campos.
• As verificações de MFA por usuário leem `signInActivity` e o relatório de registro de métodos de autenticação — isso exige `AuditLog.Read.All` e licença Entra ID P1/P2. Sem licença, essas verificações ficam `NOT_RUN`.
• `Security Reader` é o que habilita as verificações do Defender for Cloud.

Google Cloud

Campos no Imara: Project ID · Chave JSON da service account

Permissão mínima: `roles/viewer` + `roles/iam.securityReviewer` no projeto.

Frase para o cliente:

Crie uma service account no projeto, conceda a ela os papéis `roles/viewer` e `roles/iam.securityReviewer`, gere uma chave JSON e nos envie o Project ID junto com o conteúdo do arquivo JSON.

Atenção

• Cobertura de um único projeto por integração. Cliente com vários projetos precisa de uma integração por projeto.
• Uma verificação legada de MFA consulta o Admin Directory do Workspace. Ela só funciona se a service account também tiver delegação em todo o domínio — sem isso fica `NOT_RUN`. Para cobertura de identidade, use a integração Google Workspace.

Oracle Cloud

Campos no Imara: OCID da Tenancy · OCID do Usuário · Fingerprint · Região · Chave privada (PEM) · Passphrase (opcional)

Permissão mínima: grupo IAM com a política `Allow group to read all-resources in tenancy`.

Frase para o cliente:

Crie um usuário IAM dentro de um grupo que tenha a política `Allow group to read all-resources in tenancy`, gere um par de chaves de API para esse usuário e nos envie o OCID da tenancy, o OCID do usuário, o fingerprint, a região de origem e a chave privada em formato PEM.

Atenção — as verificações percorrem regiões e compartimentos; a política precisa estar na *tenancy*, não em um compartimento isolado, ou a cobertura fica parcial.

—

Desenvolvimento e DevOps

GitHub

Campos no Imara: Token · Organização (opcional)

Permissão mínima: Personal Access Token (classic) com `read:org`, `repo` e `read:audit_log`, criado por um owner da organização.

Frase para o cliente:

Como owner da organização, gere um Personal Access Token (classic) com os escopos `read:org`, `repo` e `read:audit_log`, e nos envie o token junto com o nome da organização.

Atenção

• Ler proteção de branch e alertas de vulnerabilidade exige permissão de admin no repositório — um token de membro comum retorna 403 e essas verificações ficam `NOT_RUN`. Daí a exigência de owner.
• O escopo `repo` é necessário para alcançar repositórios privados. Em organização 100% pública, `public_repo` basta.
• A API de audit log só existe em GitHub Enterprise Cloud. Fora dele, a verificação de log de auditoria orienta a conferência manual.
• Existe também o caminho de instalar o GitHub App da Imara na organização, que dispensa PAT e não expira. Prefira esse caminho quando o cliente aceitar.

GitLab

Campos no Imara: Token · URL da instância (opcional) · Group ID (opcional) · Project ID (opcional)

Permissão mínima: Personal Access Token com escopo `read_api`, em conta com papel Owner no grupo.

Frase para o cliente:

Gere um Personal Access Token com o escopo `read_api` em uma conta que tenha papel Owner no grupo, e nos envie o token, o ID do grupo e — se for GitLab self-managed — a URL da sua instância.

Atenção — o Group ID é marcado como opcional mas é indispensável: sem ele as verificações de MFA e de controle de acesso ficam `NOT_RUN`. Peça sempre.

Heroku

Campos no Imara: API Key

Permissão mínima: Authorization Token de usuário com papel admin no time.

Frase para o cliente:

Gere um Authorization Token (API key) em uma conta com papel de admin no time Heroku e nos envie a chave.

Atenção — verificações de conta corporativa (`/enterprise-accounts`) só respondem em Heroku Enterprise; fora dele ficam `MANUAL`.

Render

Campos no Imara: API Key

Permissão mínima: API Key de usuário com papel Admin no workspace.

Frase para o cliente:

Crie uma API Key nas configurações da sua conta Render, usando um usuário com papel Admin no workspace, e nos envie a chave.

Atenção — o acesso ao log de auditoria exige plano Pro ou superior; em planos abaixo a verificação fica `MANUAL`.

—

Banco de dados e dados

MongoDB Atlas

Campos no Imara: Public Key · Private Key · Project (Group) ID

Permissão mínima: API Key de organização com papel Organization Read Only, adicionada ao projeto como Project Read Only.

Frase para o cliente:

Crie uma API Key na organização Atlas com o papel Organization Read Only, adicione essa chave ao projeto com o papel Project Read Only, libere o IP de saída da Imara na API Access List e nos envie a Public Key, a Private Key e o Project ID.

Atenção — a Atlas exige allowlist de IP para chamadas de API. Sem liberar o IP do worker da Imara, todas as verificações falham na autenticação. Confirme o IP atual com o time de infraestrutura antes de enviar a frase.

Snowflake

Campos no Imara: Account · Usuário · Senha · Warehouse (opcional) · Role (opcional)

Permissão mínima: papel de monitoramento dedicado com `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` e `MONITOR ON ACCOUNT`. Não é necessário ACCOUNTADMIN.

Frase para o cliente:

Crie um usuário de serviço com um papel de monitoramento que tenha `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` e `MONITOR ON ACCOUNT`, e nos envie o identificador da conta, o usuário, a senha, o warehouse e o nome do papel.

Atenção — `SHOW GRANTS OF ROLE ACCOUNTADMIN` e `SHOW SECURITY INTEGRATIONS` podem exigir `MANAGE GRANTS`; sem isso essas duas verificações ficam `MANUAL` em vez de reprovar.

Supabase

Campos no Imara: Access Token · Slug da organização (opcional) · Project Ref (opcional)

Permissão mínima: Personal Access Token de usuário Owner da organização.

Frase para o cliente:

Gere um Personal Access Token na conta de um Owner da organização Supabase e nos envie o token, o slug da organização e o Project Ref do projeto que devemos monitorar.

Atenção — slug e project ref aparecem como opcionais, mas cada um habilita um bloco de verificações: sem o slug, as de organização ficam `MANUAL`; sem o project ref, as de projeto são puladas.

—

Produtividade e colaboração

Google Workspace

Campos no Imara: Domínio · E-mail do admin · Chave JSON da service account

Permissão mínima: service account com delegação em todo o domínio, autorizada no Admin Console para seis escopos de leitura, impersonando um super admin.

Frase para o cliente:

Crie uma service account com delegação em todo o domínio, autorize o Client ID dela no Admin Console para os escopos `admin.directory.user.readonly`, `admin.directory.domain.readonly`, `admin.directory.customer.readonly`, `admin.directory.orgunit.readonly`, `admin.directory.rolemanagement.readonly` e `cloud-identity.policies.readonly`, e nos envie o domínio, o e-mail de um super administrador e a chave JSON.

Atenção — o e-mail do admin aparece como opcional no formulário, mas é o sujeito da delegação. Sem ele as APIs de Directory recusam a chamada e nenhuma verificação de Workspace roda.

Slack

Campos no Imara: Bot Token · Workspace ID (opcional)

Permissão mínima: um bot token válido. `auth.test` não exige escopo adicional.

Frase para o cliente:

Crie um Slack app no seu workspace, instale-o e nos envie o Bot User OAuth Token (começa com `xoxb-`).

Atenção — hoje só uma verificação está implementada (conectividade / revisão de configuração). As demais dependem de Enterprise Grid e ainda não existem. Não prometa cobertura de compliance de Slack ao cliente.

—

Identidade e SSO

Okta

Campos no Imara: Domínio da org · API Token

Permissão mínima: API Token (SSWS) criado por um Read-Only Administrator.

Frase para o cliente:

Crie um API Token em uma conta com o papel Read-Only Administrator e nos envie o domínio da sua org Okta (ex.: `empresa.okta.com`) e o token.

Atenção — alguns recursos (configurações de apps de primeira parte, inventário de API tokens) só respondem a Super Administrator. Com Read-Only Admin essas verificações ficam `NOT_RUN`, não `FAIL`. Se o cliente quiser cobertura total, precisa de Super Admin.

—

Gerenciadores de senha

1Password

Campos no Imara: API Token · URL da Events API (opcional)

Permissão mínima: token da Events API com acesso a *Audit events* e *Sign-in attempts*.

Frase para o cliente:

No 1Password Business, crie um token da Events API com acesso a Audit events e Sign-in attempts, e nos envie o token junto com a URL da Events API da sua região (ex.: `https://events.1password.com`).

Atenção — a URL padrão é a dos EUA. Cliente em tenant europeu ou canadense precisa informar a URL regional, senão o token não autentica.

Bitwarden

Campos no Imara: Client ID · Client Secret

Permissão mínima: API Key da organização (não a pessoal), que autentica no escopo `api.organization`.

Frase para o cliente:

No Bitwarden, acesse Settings → Organization info → View API Key na sua organização e nos envie o `client_id` e o `client_secret` exibidos.

Atenção — é a chave da organização, não a do usuário. A chave pessoal falha na autenticação.

Dashlane

Campos no Imara: API Key

Permissão mínima: chave da Team API, gerada no console de administração.

Frase para o cliente:

No console de administração do Dashlane Business, gere uma chave da API de time (Team API) e nos envie a chave.

—

CDN e segurança

Cloudflare

Campos no Imara: API Token · Account ID (opcional)

Permissão mínima: API Token com leitura em Zone, Zone Settings, DNS e Firewall Services (todas as zonas) + Account Settings: Read e Audit Logs: Read.

Frase para o cliente:

Crie um API Token no Cloudflare com permissões de leitura em Zone, Zone Settings, DNS e Firewall Services aplicadas a todas as zonas, mais Account Settings: Read e Audit Logs: Read, e nos envie o token e o Account ID.

Atenção — sem o Account ID a verificação de log de auditoria não roda (os endpoints de auditoria são escopados por conta). Peça sempre os dois.

—

CRM e vendas

HubSpot

Campos no Imara: Access Token

Permissão mínima: Private App com os escopos `settings.users.read` e `crm.objects.contacts.read`.

Frase para o cliente:

Crie um Private App no HubSpot com os escopos `settings.users.read` e `crm.objects.contacts.read` e nos envie o Access Token gerado.

Atenção — `settings.users.read` é restrito a planos pagos e o log de auditoria exige Enterprise. Em plano gratuito a verificação de administradores fica `MANUAL`.

Salesforce

Campos no Imara: Instance URL · Client ID · Client Secret · Refresh Token

Permissão mínima: Connected App com escopos `api` e `refresh_token`; usuário de integração com `API Enabled` e `View Setup and Configuration`.

Frase para o cliente:

Crie um Connected App com os escopos `api` e `refresh_token`, use um usuário de integração com as permissões `API Enabled` e `View Setup and Configuration`, e nos envie a Instance URL, o Consumer Key, o Consumer Secret e o Refresh Token.

Atenção — sem `View Setup and Configuration` a leitura do `SetupAuditTrail` é recusada e a verificação de trilha de auditoria fica `MANUAL`.

—

Integrações fora do ar (não ofereça ao cliente)

Estão no código mas não estão marcadas como disponíveis no catálogo:

Lacunas conhecidas do produto

1. Nada disso aparece na plataforma. A tela de conexão de cada integração não lista permissão exigida — só um link para a documentação genérica do fornecedor. Cliente sem orientação erra a permissão e a integração conecta mas não produz evidência.
2. Campos marcados como opcionais que são obrigatórios na prática — Azure `subscriptionId`, GitLab `groupId`, Google Workspace `adminEmail`, Cloudflare `accountId`, Supabase `organizationSlug`/`projectRef`. Vale corrigir o formulário ou, no mínimo, o texto de apoio.
3. AWS sem caminho de role cross-account. Só chave estática. Cliente com política interna proibindo chave de longa duração não consegue conectar.
4. Slack praticamente vazio. Uma verificação implementada. Convém remover do catálogo ou rotular claramente até haver cobertura real.