Registro de auditoria de mudanças de função

Toda vez que uma função é criada, uma permissão é alternada, ou um usuário é atribuído a uma função ou unidade organizacional diferente, o GCM grava uma linha em org_audit_log com o ator, a ação, a entidade afetada e o carimbo de hora. O catálogo de funções é uma das superfícies mais sensíveis da plataforma — conceder members.delete à pessoa errada pode apagar anos de histórico — então tratamos seu log de mudanças como um recurso de primeira classe, não como uma ferramenta de depuração.

Onde encontrá-lo

Abra Configurações → Logs de Dados. A página mostra cada entrada recente em todo o seu espaço de trabalho, com filtros para tipo de ação, e-mail do ator e intervalo de datas. Para restringir a eventos relacionados a funções, digite role no filtro Ação — você verá role.created, role.deleted, role_permission.toggled, user_role.assigned, user_role.revoked, user_unit.assigned e user_unit.revoked. Cada linha leva ao usuário ou função afetada para você pular direto para o cadastro de origem.

TIP

Os Logs de Dados exigem config.manage. Administradores e qualquer função personalizada que conceda essa chave podem abrir; Leaders e Viewers não podem. Isso é intencional — a trilha de auditoria é a última linha de defesa contra um insider, então não queremos que ela seja visível para as mesmas pessoas cujas ações ela registra.

O que é registrado

Cada escrita que toca as tabelas RBAC v2 emite uma entrada de auditoria. A chave da ação te diz o que aconteceu, as colunas de entidade te dizem quem ou o que foi afetado, e o JSONB de metadados carrega o detalhe antes/depois.

Ação	Quando dispara	Payload de metadados
role.created	Uma nova função é inserida em roles_v2	name, key, description, is_system
role.deleted	Uma função personalizada é removida	name, key, permissions_count
role_permission.toggled	Um interruptor na matriz de permissões é acionado	role_id, permission_key, new_state (granted/revoked)
user_role.assigned	Uma função é adicionada a um usuário	user_id, role_id, role_name
user_role.revoked	Uma função é removida de um usuário	user_id, role_id, role_name
user_unit.assigned	Um usuário é limitado a uma unidade organizacional	user_id, org_unit_id, org_unit_name
user_unit.revoked	Um escopo é limpo	user_id, org_unit_id, org_unit_name
user.created	Um novo login é provisionado	user_id, email, initial_roles
user.suspended	O botão de ativo é desligado	user_id, email
user.reactivated	O botão de ativo é religado	user_id, email
user.password_reset	Um admin força redefinição de senha	user_id, email

Cada entrada também carrega actor_id (o usuário que realizou a ação), actor_email (desnormalizado para busca rápida mesmo se o ator for posteriormente excluído), created_at (UTC, exibido no fuso horário da sua organização na UI) e organization_id (a qual espaço de trabalho a mudança pertence).

Como ler uma linha

A visualização padrão mostra: carimbo de hora, ator, ação, entidade. Clique em qualquer linha para expandir os metadados. A visualização expandida é o payload JSONB formatado como uma tabela de chave/valor — então uma entrada role_permission.toggled pode mostrar:

role_id:        e7c3a... (Líder de Louvor)
permission_key: events.edit
new_state:      granted

Combinado com o carimbo de hora e o e-mail do ator, isso é o suficiente para reconstruir exatamente o que mudou. Se você vir uma concessão que não esperava, pode revertê-la manualmente (abra Funções e Permissões e acione o interruptor de volta) ou contatar o ator pelo contexto.

Retenção

Entradas do registro de auditoria são mantidas indefinidamente pelo tempo de vida do espaço de trabalho. Sobrevivem a exclusões de função, exclusões de usuário e até soft-deletes de organização — a única coisa que as purga é uma exclusão definitiva do espaço de trabalho, que nossa equipe realiza apenas por requisição assinada.

Isso significa que sua trilha de auditoria cobre todo seu histórico com a plataforma, o que importa para revisões de conformidade e forense pós-incidente. Não se preocupe com a desordem; a página de logs de dados pagina agressivamente e o filtro é rápido.

Registro a partir de edge functions

Operações sensíveis disparadas por edge functions — por exemplo, um workflow que atribui automaticamente membros a um líder — também emitem entradas de auditoria. A edge function chama log(ctx, action, entity) de _shared/caller-context.ts, que grava a linha com a identidade do chamador, não do service role. Então mesmo mudanças automatizadas aparecem sob o usuário que disparou o workflow, com uma tag de metadados indicando que foi conduzida por workflow.

É por isso que ocasionalmente você verá entradas system na coluna ator: são as raras limpezas conduzidas por cron (ex.: expirar um token de convite) onde nenhum ator humano existe. Essas são claramente marcadas.

Investigações comuns

Alguns padrões pelos quais conduzimos clientes:

• "Quem deu a Sara members.delete?" — filtre Ação = role_permission.toggled, depois busque no payload de metadados por members.delete. O resultado mostra cada função que já foi concedida ou revogada com essa chave, quem a acionou e quando.
• "Por que João consegue ver os membros da Filial Leste?" — filtre Ação = user_unit.assigned, busque pelo user_id de João. A lista mostra cada escopo já anexado a ele com carimbos de hora.
• "Alguém excluiu uma função este mês?" — filtre Ação = role.deleted, intervalo de datas = mês atual. Se a resposta for sim, o payload de metadados preserva o nome e a chave da função para você recriá-la.

Exportando

Clique no botão Exportar no canto superior direito de Logs de Dados para baixar a visualização filtrada atual como CSV. A exportação inclui todas as colunas que você vê mais o JSONB de metadados bruto, útil para revisão forense em uma planilha ou para entregar a um auditor.

Próximo

• Recuperando um usuário bloqueado — quando o registro de auditoria mostra um erro que você precisa desfazer.
• Concedendo permissões — a que os interruptores na matriz correspondem.
• Registro de auditoria do platform admin — o log equivalente para eventos de impersonificação executados pela equipe GCM.