Visão Geral
A arquitetura de seguranca do Matcher e construida em varias camadas. Toda requisicao de API passa por multiplos pontos de verificacao de seguranca antes de acessar seus dados.
Em seguida, a autenticacao verifica quem voce e:
- O isolamento de tenant garante que voce veja apenas seus proprios dados.
- O RBAC verifica se voce tem permissao para realizar a acao.
Protecao por camadas
| Camada | Protecao |
|---|---|
| Transporte | Criptografia TLS 1.2+ |
| Autenticacao | Tokens JWT via lib-auth |
| Isolamento de Tenant | Schema-por-tenant PostgreSQL |
| Autorizacao | Controle de acesso baseado em funcoes |
| Auditoria | Logs imutaveis somente-anexacao |
| Armazenamento | Criptografia em repouso |
Autenticacao
O Matcher usa a biblioteca compartilhada
lib-auth para autenticacao, suportando OAuth 2.0 e controle de acesso baseado em JWT.
Metodos de autenticacao suportados
| Metodo | Caso de Uso |
|---|---|
| OAuth 2.0 + JWT | Autenticacao de usuario via IdP |
| Client Credentials | Autenticacao servico-a-servico |
| API Keys | Acesso programatico |
Estrutura do token JWT
Headers obrigatorios
Todas as requisicoes de API devem incluir autenticacao:Validacao de token
O Matcher valida tokens em cada requisicao:- Verificacao de assinatura: Valida a assinatura JWT contra a chave publica
- Verificacao de expiracao: Rejeita tokens expirados
- Validacao do emissor: Confirma token de emissor confiavel
- Extracao de tenant: Extrai tenant_id para isolamento de schema
Autenticacao servico-a-servico
Para servicos backend integrando com o Matcher:Resposta
Autorizacao (RBAC)
O controle de acesso baseado em funcoes protege todos os endpoints da API. As permissoes sao granulares e seguem o padrao
dominio:recurso:acao.
Estrutura de permissao
ingestion:import:create- Criar importacoesmatching:job:run- Executar jobs de correspondenciaexception:item:resolve- Resolver excecoes
Lista completa de permissoes
Ingestao
| Permissao | Descricao |
|---|---|
ingestion:import:create | Fazer upload de arquivos de transacao |
ingestion:import:read | Visualizar status de importacao |
ingestion:import:cancel | Cancelar importacoes em andamento |
ingestion:source:create | Criar fontes de dados |
ingestion:source:read | Visualizar configuracao de fonte |
ingestion:source:update | Modificar configuracoes de fonte |
ingestion:source:delete | Remover fontes de dados |
Correspondencia
| Permissao | Descricao |
|---|---|
matching:job:run | Executar jobs de correspondencia |
matching:job:read | Visualizar status do job |
matching:job:cancel | Cancelar jobs em execucao |
matching:match:read | Visualizar resultados de correspondencia |
matching:match:confirm | Confirmar correspondencias propostas |
matching:match:reject | Rejeitar correspondencias propostas |
matching:rule:create | Criar regras de correspondencia |
matching:rule:update | Modificar regras de correspondencia |
matching:rule:delete | Excluir regras de correspondencia |
Excecao
| Permissao | Descricao |
|---|---|
exception:item:read | Visualizar excecoes |
exception:item:resolve | Resolver excecoes |
exception:item:assign | Atribuir excecoes |
exception:item:escalate | Escalar excecoes |
exception:routing:manage | Configurar regras de roteamento |
Governanca
| Permissao | Descricao |
|---|---|
governance:report:read | Visualizar relatorios |
governance:report:create | Gerar relatorios |
governance:report:export | Exportar dados de relatorio |
governance:audit:read | Visualizar logs de auditoria |
governance:context:create | Criar contextos |
governance:context:update | Modificar contextos |
governance:context:delete | Excluir contextos |
Administracao
| Permissao | Descricao |
|---|---|
admin:user:manage | Gerenciar acesso de usuarios |
admin:role:manage | Gerenciar funcoes |
admin:tenant:configure | Configurar definicoes do tenant |
admin:system:monitor | Visualizar saude do sistema |
Funcoes integradas
| Funcao | Permissoes | Caso de Uso |
|---|---|---|
reconciliation_viewer | Acesso somente leitura a correspondencias e excecoes | Auditores |
reconciliation_analyst | Visualizar + resolver excecoes | Equipe financeira |
reconciliation_admin | Acesso completo exceto administracao do sistema | Lideres de equipe |
system_admin | Todas as permissoes | Administradores de TI |
Isolamento de tenant
O Matcher usa isolamento schema-por-tenant no PostgreSQL, fornecendo forte separacao de dados entre tenants.
Como funciona
Quando uma requisicao chega, o Matcher extrai o ID do tenant do token JWT (nunca de parametros de consulta ou headers que voce controla). Em seguida, configura a conexao do banco de dados para usar o schema daquele tenant, para que cada consulta seja executada em completo isolamento.Mesmo se existisse um bug na camada de aplicacao, o banco de dados impoe a separacao.
- ID do tenant apenas do JWT: Nunca aceito de parametros de requisicao
- Selecao automatica de schema: Aplicada via
auth.ApplyTenantSchema() - Isolamento de consulta: Todas as consultas sao limitadas ao schema do tenant
- Sem acesso entre tenants: O banco de dados impoe o isolamento
Estrutura de schema do banco de dados
Garantias de isolamento
| Garantia | Implementacao |
|---|---|
| Isolamento de dados | Schemas PostgreSQL separados |
| Escopo de consulta | search_path definido por conexao |
| Sem spoofing de tenant | Tenant apenas do JWT |
| Separacao de auditoria | Tabelas de auditoria por tenant |
Verificar isolamento de tenant
Trilha de auditoria
Todas as acoes sao registradas em um log de auditoria imutavel, somente-anexacao, para conformidade e forense.
Eventos auditados
| Categoria | Eventos |
|---|---|
| Autenticacao | Login, logout, renovacao de token, tentativas falhas |
| Acesso a Dados | Visualizar correspondencias, visualizar excecoes, exportar dados |
| Modificacao de Dados | Criar correspondencia, resolver excecao, atualizar regras |
| Configuracao | Criar contexto, modificar fonte, alterar configuracoes |
| Administracao | Gerenciamento de usuarios, alteracoes de funcao, concessao de permissoes |
Estrutura do log de auditoria
Consultar logs de auditoria
Use o endpoint de logs de auditoria para recuperar registros de auditoria.Retencao de log de auditoria
| Ambiente | Retencao | Arquivamento |
|---|---|---|
| Producao | 7 anos | Armazenamento frio apos 1 ano |
| Staging | 90 dias | Sem arquivamento |
| Desenvolvimento | 30 dias | Sem arquivamento |
Criptografia de dados
Criptografia em transito
Todos os dados transmitidos para e do Matcher sao criptografados usando TLS.| Requisito | Configuracao |
|---|---|
| Protocolo | TLS 1.2 ou superior |
| Conjuntos de cifras | Apenas cifras fortes |
| Certificado | Certificado valido assinado por CA |
| HSTS | Habilitado com max-age de 1 ano |
Criptografia em repouso
| Tipo de Dado | Metodo de Criptografia |
|---|---|
| Banco de dados | PostgreSQL TDE (Transparent Data Encryption) |
| Armazenamento de arquivos | Criptografia AES-256 |
| Backups | Criptografados antes do armazenamento |
| Segredos | Vault com criptografia envelope |
Criptografia de campos sensiveis
Campos sensiveis especificos sao criptografados no nivel da aplicacao:Gerenciamento de chaves
| Pratica | Implementacao |
|---|---|
| Rotacao de chaves | Rotacao automatica a cada 90 dias |
| Armazenamento de chaves | HashiCorp Vault ou AWS KMS |
| Controle de acesso | Principio do menor privilegio |
| Auditoria | Todo acesso a chaves e registrado |
Conformidade SOX
O Matcher mantem registros para requisitos de auditoria SOX (Sarbanes-Oxley).
Recursos de controle SOX
| Controle | Recurso do Matcher |
|---|---|
| Segregacao de funcoes | RBAC com permissoes granulares |
| Gerenciamento de mudancas | Trilha de auditoria para todas as mudancas de configuracao |
| Controle de acesso | Autenticacao JWT com aplicacao de funcoes |
| Trilha de auditoria | Logs imutaveis com retencao de 7 anos |
| Integridade de dados | Checksums e validacao de transacoes |
Principio dos quatro olhos
Impor aprovacao dupla para acoes sensiveis:Seguranca de API
Limitacao de taxa
Proteja contra abusos com limites de taxa:| Tipo de Endpoint | Limite |
|---|---|
| Operacoes de leitura | 1000/minuto |
| Operacoes de escrita | 100/minuto |
| Geracao de relatorios | 10/minuto |
| Uploads de arquivos | 20/minuto |
Headers de limite de taxa
Lista de permissao de IP
Restrinja o acesso a API a intervalos de IP conhecidos:Assinatura de requisicao
Para ambientes de alta seguranca, habilite a assinatura de requisicao:Melhores praticas
Use acesso de menor privilegio
Use acesso de menor privilegio
Conceda aos usuarios apenas as permissoes que eles precisam. Comece com acesso minimo e adicione permissoes conforme necessario.
Rotacione credenciais regularmente
Rotacione credenciais regularmente
Implemente rotacao automatica para chaves de API e credenciais de servico. Use tokens de curta duracao sempre que possivel.
Habilite o log de auditoria
Habilite o log de auditoria
Mantenha os logs de auditoria habilitados e revise-os regularmente. Configure alertas para atividades suspeitas.
Implemente lista de permissao de IP
Implemente lista de permissao de IP
Restrinja o acesso a API a intervalos de IP conhecidos, especialmente para ambientes de producao.
Use autenticacao forte
Use autenticacao forte
Exija MFA para contas de usuario. Use autenticacao baseada em certificado para contas de servico quando possivel.
Revise o acesso regularmente
Revise o acesso regularmente
Realize revisoes de acesso periodicas. Remova o acesso prontamente quando usuarios mudarem de funcao ou sairem.
Criptografe dados sensiveis
Criptografe dados sensiveis
Habilite criptografia no nivel de campo para dados de transacao sensiveis alem da criptografia do banco de dados.
Monitore eventos de seguranca
Monitore eventos de seguranca
Configure monitoramento e alertas em tempo real para eventos de seguranca. Investigue anomalias prontamente.

