Pular para o conteúdo principal
O Matcher implementa controles de seguranca abrangentes para proteger dados de reconciliacao financeira. Este guia aborda autenticacao, autorizacao, isolamento de tenant, criptografia e recursos de conformidade.

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.
1
Primeiro, o TLS criptografa a conexao.
2
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.
3
Por fim, o sistema registra tudo para fins de auditoria.

Protecao por camadas

CamadaProtecao
TransporteCriptografia TLS 1.2+
AutenticacaoTokens JWT via lib-auth
Isolamento de TenantSchema-por-tenant PostgreSQL
AutorizacaoControle de acesso baseado em funcoes
AuditoriaLogs imutaveis somente-anexacao
ArmazenamentoCriptografia 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

MetodoCaso de Uso
OAuth 2.0 + JWTAutenticacao de usuario via IdP
Client CredentialsAutenticacao servico-a-servico
API KeysAcesso programatico

Estrutura do token JWT

{
  "sub": "user_123",
  "tenant_id": "tenant_001",
  "roles": [
    "reconciliation_admin"
  ],
  "permissions": [
    "ingestion:import:create",
    "matching:job:run",
    "exception:item:resolve"
  ],
  "iat": 1705749600,
  "exp": 1705753200,
  "iss": "https://auth.example.com"
}

Headers obrigatorios

Todas as requisicoes de API devem incluir autenticacao:
curl -X GET "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $JWT_TOKEN" \
 -H "X-Request-ID: req_abc123"

Validacao de token

O Matcher valida tokens em cada requisicao:
  1. Verificacao de assinatura: Valida a assinatura JWT contra a chave publica
  2. Verificacao de expiracao: Rejeita tokens expirados
  3. Validacao do emissor: Confirma token de emissor confiavel
  4. Extracao de tenant: Extrai tenant_id para isolamento de schema

Autenticacao servico-a-servico

Para servicos backend integrando com o Matcher:
# Solicitar token
curl -X POST "https://auth.example.com/oauth/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=client_credentials" \
 -d "client_id=matcher-service" \
 -d "client_secret=$CLIENT_SECRET" \
 -d "scope=matcher:read matcher:write"

Resposta

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "matcher:read matcher:write"
}

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

<bounded_context>:<resource>:<action>
Exemplos:
  • ingestion:import:create - Criar importacoes
  • matching:job:run - Executar jobs de correspondencia
  • exception:item:resolve - Resolver excecoes

Lista completa de permissoes

Ingestao

PermissaoDescricao
ingestion:import:createFazer upload de arquivos de transacao
ingestion:import:readVisualizar status de importacao
ingestion:import:cancelCancelar importacoes em andamento
ingestion:source:createCriar fontes de dados
ingestion:source:readVisualizar configuracao de fonte
ingestion:source:updateModificar configuracoes de fonte
ingestion:source:deleteRemover fontes de dados

Correspondencia

PermissaoDescricao
matching:job:runExecutar jobs de correspondencia
matching:job:readVisualizar status do job
matching:job:cancelCancelar jobs em execucao
matching:match:readVisualizar resultados de correspondencia
matching:match:confirmConfirmar correspondencias propostas
matching:match:rejectRejeitar correspondencias propostas
matching:rule:createCriar regras de correspondencia
matching:rule:updateModificar regras de correspondencia
matching:rule:deleteExcluir regras de correspondencia

Excecao

PermissaoDescricao
exception:item:readVisualizar excecoes
exception:item:resolveResolver excecoes
exception:item:assignAtribuir excecoes
exception:item:escalateEscalar excecoes
exception:routing:manageConfigurar regras de roteamento

Governanca

PermissaoDescricao
governance:report:readVisualizar relatorios
governance:report:createGerar relatorios
governance:report:exportExportar dados de relatorio
governance:audit:readVisualizar logs de auditoria
governance:context:createCriar contextos
governance:context:updateModificar contextos
governance:context:deleteExcluir contextos

Administracao

PermissaoDescricao
admin:user:manageGerenciar acesso de usuarios
admin:role:manageGerenciar funcoes
admin:tenant:configureConfigurar definicoes do tenant
admin:system:monitorVisualizar saude do sistema

Funcoes integradas

FuncaoPermissoesCaso de Uso
reconciliation_viewerAcesso somente leitura a correspondencias e excecoesAuditores
reconciliation_analystVisualizar + resolver excecoesEquipe financeira
reconciliation_adminAcesso completo exceto administracao do sistemaLideres de equipe
system_adminTodas as permissoesAdministradores 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.
Detalhes de implementacao
  1. ID do tenant apenas do JWT: Nunca aceito de parametros de requisicao
  2. Selecao automatica de schema: Aplicada via auth.ApplyTenantSchema()
  3. Isolamento de consulta: Todas as consultas sao limitadas ao schema do tenant
  4. Sem acesso entre tenants: O banco de dados impoe o isolamento

Estrutura de schema do banco de dados

Database: matcher_db
├── tenant_001 (schema)
│ ├── transactions
│ ├── matches
│ ├── exceptions
│ ├── audit_logs
│ └── ...
├── tenant_002 (schema)
│ ├── transactions
│ ├── matches
│ ├── exceptions
│ ├── audit_logs
│ └── ...
└── shared (schema)
 ├── field_map_templates
 ├── rule_templates
 └── system_config

Garantias de isolamento

GarantiaImplementacao
Isolamento de dadosSchemas PostgreSQL separados
Escopo de consultasearch_path definido por conexao
Sem spoofing de tenantTenant apenas do JWT
Separacao de auditoriaTabelas de auditoria por tenant

Verificar isolamento de tenant

# Isso retorna apenas dados para o tenant no JWT
curl -X GET "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN"

Trilha de auditoria


Todas as acoes sao registradas em um log de auditoria imutavel, somente-anexacao, para conformidade e forense.

Eventos auditados

CategoriaEventos
AutenticacaoLogin, logout, renovacao de token, tentativas falhas
Acesso a DadosVisualizar correspondencias, visualizar excecoes, exportar dados
Modificacao de DadosCriar correspondencia, resolver excecao, atualizar regras
ConfiguracaoCriar contexto, modificar fonte, alterar configuracoes
AdministracaoGerenciamento de usuarios, alteracoes de funcao, concessao de permissoes

Estrutura do log de auditoria

{
  "id": "audit_001",
  "timestamp": "2024-01-20T10:30:00Z",
  "tenant_id": "tenant_001",
  "user_id": "user_123",
  "user_email": "analyst@company.com",
  "action": "exception:item:resolve",
  "resource_type": "exception",
  "resource_id": "exc_001",
  "details": {
    "resolution_type": "FORCE_MATCH",
    "matched_transaction": "txn_456",
    "notes": "Verified with bank statement"
  },
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "request_id": "req_abc123",
  "outcome": "SUCCESS"
}

Consultar logs de auditoria

Use o endpoint de logs de auditoria para recuperar registros de auditoria.
Referência da API: Listar logs de auditoria

Retencao de log de auditoria

AmbienteRetencaoArquivamento
Producao7 anosArmazenamento frio apos 1 ano
Staging90 diasSem arquivamento
Desenvolvimento30 diasSem arquivamento

Criptografia de dados


Criptografia em transito

Todos os dados transmitidos para e do Matcher sao criptografados usando TLS.
RequisitoConfiguracao
ProtocoloTLS 1.2 ou superior
Conjuntos de cifrasApenas cifras fortes
CertificadoCertificado valido assinado por CA
HSTSHabilitado com max-age de 1 ano

Criptografia em repouso

Tipo de DadoMetodo de Criptografia
Banco de dadosPostgreSQL TDE (Transparent Data Encryption)
Armazenamento de arquivosCriptografia AES-256
BackupsCriptografados antes do armazenamento
SegredosVault com criptografia envelope

Criptografia de campos sensiveis

Campos sensiveis especificos sao criptografados no nivel da aplicacao:
{
  "settings": {
    "encryption": {
      "encrypt_fields": [
        "counterparty_account",
        "reference",
        "external_id"
      ],
      "key_id": "key_prod_001"
    }
  }
}

Gerenciamento de chaves

PraticaImplementacao
Rotacao de chavesRotacao automatica a cada 90 dias
Armazenamento de chavesHashiCorp Vault ou AWS KMS
Controle de acessoPrincipio do menor privilegio
AuditoriaTodo acesso a chaves e registrado

Conformidade SOX


O Matcher mantem registros para requisitos de auditoria SOX (Sarbanes-Oxley).

Recursos de controle SOX

ControleRecurso do Matcher
Segregacao de funcoesRBAC com permissoes granulares
Gerenciamento de mudancasTrilha de auditoria para todas as mudancas de configuracao
Controle de acessoAutenticacao JWT com aplicacao de funcoes
Trilha de auditoriaLogs imutaveis com retencao de 7 anos
Integridade de dadosChecksums e validacao de transacoes

Principio dos quatro olhos

Impor aprovacao dupla para acoes sensiveis:
{
  "settings": {
    "governance": {
      "require_approval": {
        "exception_write_off": true,
        "high_value_match": true,
        "threshold_amount": 100000.0
      },
      "approver_role": "reconciliation_admin"
    }
  }
}

Seguranca de API


Limitacao de taxa

Proteja contra abusos com limites de taxa:
Tipo de EndpointLimite
Operacoes de leitura1000/minuto
Operacoes de escrita100/minuto
Geracao de relatorios10/minuto
Uploads de arquivos20/minuto

Headers de limite de taxa

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705753200

Lista de permissao de IP

Restrinja o acesso a API a intervalos de IP conhecidos:
{
  "settings": {
    "security": {
      "ip_allowlist": [
        "10.0.0.0/8",
        "192.168.1.0/24",
        "203.0.113.50"
      ],
      "enforce_allowlist": true
    }
  }
}

Assinatura de requisicao

Para ambientes de alta seguranca, habilite a assinatura de requisicao:
# Gerar assinatura
TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "$TIMESTAMP$REQUEST_BODY" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)

curl -X POST "https://api.matcher.example.com/v1/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "X-Timestamp: $TIMESTAMP" \
 -H "X-Signature: $SIGNATURE" \
 -d "$REQUEST_BODY"

Melhores praticas


Conceda aos usuarios apenas as permissoes que eles precisam. Comece com acesso minimo e adicione permissoes conforme necessario.
Implemente rotacao automatica para chaves de API e credenciais de servico. Use tokens de curta duracao sempre que possivel.
Mantenha os logs de auditoria habilitados e revise-os regularmente. Configure alertas para atividades suspeitas.
Restrinja o acesso a API a intervalos de IP conhecidos, especialmente para ambientes de producao.
Exija MFA para contas de usuario. Use autenticacao baseada em certificado para contas de servico quando possivel.
Realize revisoes de acesso periodicas. Remova o acesso prontamente quando usuarios mudarem de funcao ou sairem.
Habilite criptografia no nivel de campo para dados de transacao sensiveis alem da criptografia do banco de dados.
Configure monitoramento e alertas em tempo real para eventos de seguranca. Investigue anomalias prontamente.

Proximos passos