Registro de auditoría de cambios de rol

Cada vez que un rol es creado, un permiso es alternado, o un usuario es asignado a un rol o unidad organizacional diferente, GCM escribe una fila en org_audit_log con el actor, la acción, la entidad afectada y la marca de tiempo. El catálogo de roles es una de las superficies más sensibles en la plataforma — otorgar members.delete a la persona equivocada puede borrar años de historia — así que tratamos su registro de cambios como una característica de primera clase, no una herramienta de depuración.

Dónde encontrarlo

Abre Configuración → Registros de Datos. La página muestra cada entrada reciente en tu espacio de trabajo, con filtros para tipo de acción, correo del actor y rango de fechas. Para reducir a eventos relacionados con roles, escribe role en el filtro Acción — verás role.created, role.deleted, role_permission.toggled, user_role.assigned, user_role.revoked, user_unit.assigned y user_unit.revoked. Cada fila enlaza al usuario o rol afectado para que puedas saltar directamente al registro fuente.

TIP

Los Registros de Datos requieren config.manage. Los administradores y cualquier rol personalizado que otorgue esa llave pueden abrirlos; Leaders y Viewers no pueden. Esto es intencional — el rastro de auditoría es la última línea de defensa contra un infiltrado, así que no queremos que sea visible para las mismas personas cuyas acciones registra.

Qué se registra

Cada escritura que toca las tablas RBAC v2 emite una entrada de auditoría. La llave de acción te dice qué pasó, las columnas de entidad te dicen quién o qué fue afectado, y el JSONB de metadatos lleva el detalle antes/después.

Acción	Cuándo se activa	Carga de metadatos
role.created	Un nuevo rol es insertado en roles_v2	name, key, description, is_system
role.deleted	Un rol personalizado es removido	name, key, permissions_count
role_permission.toggled	Un interruptor en la matriz de permisos es movido	role_id, permission_key, new_state (granted/revoked)
user_role.assigned	Un rol es agregado a un usuario	user_id, role_id, role_name
user_role.revoked	Un rol es removido de un usuario	user_id, role_id, role_name
user_unit.assigned	Un usuario es limitado a una unidad organizacional	user_id, org_unit_id, org_unit_name
user_unit.revoked	Un alcance es limpiado	user_id, org_unit_id, org_unit_name
user.created	Un nuevo inicio de sesión es aprovisionado	user_id, email, initial_roles
user.suspended	El interruptor de activo se apaga	user_id, email
user.reactivated	El interruptor de activo se vuelve a encender	user_id, email
user.password_reset	Un admin forza un reseteo de contraseña	user_id, email

Cada entrada también lleva actor_id (el usuario que realizó la acción), actor_email (desnormalizado para búsqueda rápida incluso si el actor es eliminado después), created_at (UTC, mostrado en la zona horaria de tu org en la UI), y organization_id (a qué espacio de trabajo pertenece el cambio).

Cómo leer una fila

La vista predeterminada muestra: marca de tiempo, actor, acción, entidad. Haz clic en cualquier fila para expandir los metadatos. La vista expandida es la carga JSONB formateada como una tabla clave/valor — así que una entrada role_permission.toggled podría mostrar:

role_id:        e7c3a... (Worship Leader)
permission_key: events.edit
new_state:      granted

Combinado con la marca de tiempo y el correo del actor, eso es suficiente para reconstruir exactamente qué cambió. Si detectas un otorgamiento que no esperabas, puedes revertirlo manualmente (abre Roles y Permisos y mueve el interruptor de vuelta) o contactar al actor por contexto.

Retención

Las entradas del registro de auditoría se mantienen indefinidamente durante toda la vida del espacio de trabajo. Sobreviven eliminaciones de roles, eliminaciones de usuarios e incluso eliminaciones suaves de org — lo único que las purga es una eliminación dura del espacio de trabajo, que nuestro equipo realiza solo por solicitud firmada.

Esto significa que tu rastro de auditoría cubre toda tu historia con la plataforma, lo que importa para revisiones de cumplimiento y forenses post-incidente. No te preocupes por el desorden; la página de registros de datos pagina agresivamente y el filtro es rápido.

Registrar desde edge functions

Las operaciones sensibles activadas por edge functions — por ejemplo, un flujo de trabajo que auto-asigna miembros a un líder — también emiten entradas de auditoría. La edge function llama a log(ctx, action, entity) desde _shared/caller-context.ts, que escribe la fila con la identidad del invocador, no del service role. Así que incluso los cambios automatizados aparecen bajo el usuario que activó el flujo de trabajo, con una etiqueta de metadatos indicando que fue impulsado por flujo de trabajo.

Por eso ocasionalmente verás entradas system en la columna del actor: son las raras limpiezas impulsadas por cron (por ejemplo, expirar un token de invitación) donde no existe un actor humano. Esas están claramente etiquetadas.

Investigaciones comunes

Algunos patrones que recorremos con clientes:

• "¿Quién le dio a Sarah members.delete?" — filtra Acción = role_permission.toggled, luego busca en la carga de metadatos por members.delete. El resultado muestra cada rol al que se le ha otorgado o revocado esa llave, quién lo movió, y cuándo.
• "¿Por qué John puede ver los miembros de Sede Este?" — filtra Acción = user_unit.assigned, busca el user_id de John. La lista muestra cada alcance que se le ha asignado con marcas de tiempo.
• "¿Alguien eliminó un rol este mes?" — filtra Acción = role.deleted, rango de fechas = mes actual. Si la respuesta es sí, la carga de metadatos preserva el nombre y llave del rol para que puedas recrearlo.

Exportar

Haz clic en el botón Exportar en la esquina superior derecha de Registros de Datos para descargar la vista filtrada actual como CSV. La exportación incluye todas las columnas que ves más el JSONB de metadatos crudo, útil para revisión forense en una hoja de cálculo o para entregar a un auditor.

Siguiente

• Recuperar un usuario bloqueado — cuando el registro de auditoría muestra un error que necesitas deshacer.
• Otorgar permisos — a qué corresponden los interruptores en la matriz.
• Registro de auditoría de platform admin — el registro equivalente para eventos de impersonación ejecutados por el equipo de GCM.