Security - Lerian

Matcher implements comprehensive security controls to protect financial reconciliation data. This guide covers authentication, authorization, tenant isolation, encryption, and compliance features.

Overview

Matcher’s security architecture is built on several layers. Every API request passes through multiple security checkpoints before reaching your data.

First, TLS encrypts the connection.

Then authentication verifies who you are:

Tenant isolation ensures you only see your own data.
RBAC checks whether you’re allowed to perform the action.

Finally, the system logs everything for audit purposes.

Layer protection

Layer	Protection
Transport	TLS 1.2+ encryption
Authentication	JWT tokens via lib-auth
Tenant Isolation	Schema-per-tenant PostgreSQL
Authorization	Role-based access control
Audit	Immutable append-only logs
Storage	Encryption at rest

Authentication

Matcher uses the shared lib-auth library for authentication, supporting OAuth 2.0 and JWT-based access control.

Supported authentication methods

Method	Use Case
OAuth 2.0 + JWT	User authentication via IdP
Client Credentials	Service-to-service auth
API Keys	Programmatic access

JWT token structure

{
  "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"
}

Required headers

All API requests must include authentication:

curl -X GET "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $JWT_TOKEN" \
 -H "X-Request-ID: req_abc123"

Token validation

Matcher validates tokens on every request:

Signature verification: Validates JWT signature against public key
Expiration check: Rejects expired tokens
Issuer validation: Confirms token from trusted issuer
Tenant extraction: Extracts tenant_id for schema isolation

Service-to-service authentication

For backend services integrating with Matcher:

# Request 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"

Response

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

Authorization (rbac)

Role-based access control protects all API endpoints. Permissions are granular and follow the pattern domain:resource:action.

Permission structure

<bounded_context>:<resource>:<action>

Examples:

ingestion:import:create - Create imports
matching:job:run - Execute matching jobs
exception:item:resolve - Resolve exceptions

Complete permission list

Ingestion

Permission	Description
`ingestion:import:create`	Upload transaction files
`ingestion:import:read`	View import status
`ingestion:import:cancel`	Cancel in-progress imports
`ingestion:source:create`	Create data sources
`ingestion:source:read`	View source configuration
`ingestion:source:update`	Modify source settings
`ingestion:source:delete`	Remove data sources

Matching

Permission	Description
`matching:job:run`	Execute matching jobs
`matching:job:read`	View job status
`matching:job:cancel`	Cancel running jobs
`matching:match:read`	View match results
`matching:match:confirm`	Confirm proposed matches
`matching:match:reject`	Reject proposed matches
`matching:rule:create`	Create match rules
`matching:rule:update`	Modify match rules
`matching:rule:delete`	Delete match rules

Exception

Permission	Description
`exception:item:read`	View exceptions
`exception:item:resolve`	Resolve exceptions
`exception:item:assign`	Assign exceptions
`exception:item:escalate`	Escalate exceptions
`exception:routing:manage`	Configure routing rules

Governance

Permission	Description
`governance:report:read`	View reports
`governance:report:create`	Generate reports
`governance:report:export`	Export report data
`governance:audit:read`	View audit logs
`governance:context:create`	Create contexts
`governance:context:update`	Modify contexts
`governance:context:delete`	Delete contexts

Administration

Permission	Description
`admin:user:manage`	Manage user access
`admin:role:manage`	Manage roles
`admin:tenant:configure`	Configure tenant settings
`admin:system:monitor`	View system health

Built-in roles

Role	Permissions	Use Case
`reconciliation_viewer`	Read-only access to matches and exceptions	Auditors
`reconciliation_analyst`	View + resolve exceptions	Finance team
`reconciliation_admin`	Full access except system admin	Team leads
`system_admin`	All permissions	IT administrators

Custom roles

Create custom roles combining specific permissions:

cURL

curl -X POST "https://api.matcher.example.com/v1/admin/roles" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "exception_specialist",
   "description": "Can only work on exceptions",
   "permissions": [
     "exception:item:read",
     "exception:item:resolve",
     "exception:item:assign",
     "governance:report:read"
   ]
 }'

Response

{
  "id": "role_exc_001",
  "name": "exception_specialist",
  "description": "Can only work on exceptions",
  "permissions": [
    "exception:item:read",
    "exception:item:resolve",
    "exception:item:assign",
    "governance:report:read"
  ],
  "created_at": "2024-01-15T10:00:00Z"
}

Assign roles to users

curl -X POST "https://api.matcher.example.com/v1/admin/users/user_123/roles" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "roles": [
     "exception_specialist"
   ],
   "context_restrictions": [
     "ctx_abc123",
     "ctx_def456"
   ]
 }'

Tenant isolation

Matcher uses schema-per-tenant isolation in PostgreSQL, providing strong data separation between tenants.

How it works

When a request arrives, Matcher extracts the tenant ID from the JWT token (never from query parameters or headers you control). It then sets the database connection to use that tenant’s schema, so every query runs in complete isolation.

Even if a bug existed in the application layer, the database enforces separation.

Implementation details

Tenant ID from JWT only: Never accepted from request parameters
Automatic schema selection: Applied via auth.ApplyTenantSchema()
Query isolation: All queries scoped to tenant schema
No cross-tenant access: Database enforces isolation

Database schema structure

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

Isolation guarantees

Guarantee	Implementation
Data isolation	Separate PostgreSQL schemas
Query scoping	search_path set per connection
No tenant spoofing	Tenant from JWT only
Audit separation	Per-tenant audit tables

Verify tenant isolation

# This returns only data for the tenant in the JWT
curl -X GET "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN"

Audit trail

All actions are recorded in an immutable, append-only audit log for compliance and forensics.

Audited events

Category	Events
Authentication	Login, logout, token refresh, failed attempts
Data Access	View matches, view exceptions, export data
Data Modification	Create match, resolve exception, update rules
Configuration	Create context, modify source, change settings
Administration	User management, role changes, permission grants

Audit log structure

{
  "id": "audit_001",
  "timestamp": "2024-01-20T10:30:00Z",
  "tenant_id": "tenant_001",
  "user_id": "user_123",
  "user_email": "[email protected]",
  "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"
}

Query audit logs

cURL

curl -X GET "https://api.matcher.example.com/v1/governance/audit" \
 -H "Authorization: Bearer $TOKEN" \
 -G \
 -d "date_from=2024-01-01" \
 -d "date_to=2024-01-31" \
 -d "user_id=user_123" \
 -d "action=exception:item:resolve"

Response

{
  "audit_logs": [
    {
      "id": "audit_001",
      "timestamp": "2024-01-20T10:30:00Z",
      "user_id": "user_123",
      "action": "exception:item:resolve",
      "resource_id": "exc_001",
      "outcome": "SUCCESS"
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "per_page": 20
  }
}

Audit log retention

Environment	Retention	Archive
Production	7 years	Cold storage after 1 year
Staging	90 days	No archive
Development	30 days	No archive

Export audit logs

For compliance reporting:

curl -X POST "https://api.matcher.example.com/v1/governance/audit/export" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "date_from": "2024-01-01",
   "date_to": "2024-01-31",
   "format": "CSV",
   "include_details": true
 }'

Data encryption

Encryption in transit

All data transmitted to and from Matcher is encrypted using TLS.

Requirement	Configuration
Protocol	TLS 1.2 or higher
Cipher suites	Strong ciphers only
Certificate	Valid CA-signed certificate
HSTS	Enabled with 1-year max-age

Encryption at rest

Data Type	Encryption Method
Database	PostgreSQL TDE (Transparent Data Encryption)
File storage	AES-256 encryption
Backups	Encrypted before storage
Secrets	Vault with envelope encryption

Sensitive field encryption

Specific sensitive fields are encrypted at the application level:

{
  "settings": {
    "encryption": {
      "encrypt_fields": [
        "counterparty_account",
        "reference",
        "external_id"
      ],
      "key_id": "key_prod_001"
    }
  }
}

Key management

Practice	Implementation
Key rotation	Automatic 90-day rotation
Key storage	HashiCorp Vault or AWS KMS
Access control	Principle of least privilege
Audit	All key access logged

SOX compliance

Matcher maintains records for SOX (Sarbanes-Oxley) audit requirements.

SOX control features

Control	Matcher Feature
Segregation of duties	RBAC with granular permissions
Change management	Audit trail for all configuration changes
Access control	JWT authentication with role enforcement
Audit trail	Immutable logs with 7-year retention
Data integrity	Transaction checksums and validation

SOX compliance report

Generate compliance-ready reports:

curl -X POST "https://api.matcher.example.com/v1/governance/reports/sox" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "period": {
     "from": "2024-01-01",
     "to": "2024-03-31"
   },
   "include_sections": [
     "access_reviews",
     "configuration_changes",
     "exception_resolutions",
     "segregation_analysis"
   ]
 }'

Response

{
  "report_id": "sox_q1_2024",
  "period": {
    "from": "2024-01-01",
    "to": "2024-03-31"
  },
  "sections": {
    "access_reviews": {
      "total_users": 25,
      "role_changes": 8,
      "permission_grants": 12,
      "permission_revocations": 5
    },
    "configuration_changes": {
      "context_changes": 3,
      "rule_changes": 15,
      "source_changes": 7
    },
    "exception_resolutions": {
      "total_resolved": 450,
      "by_resolution_type": {
        "FORCE_MATCH": 280,
        "ADJUSTMENT": 120,
        "WRITE_OFF": 50
      },
      "approval_compliance": 100.0
    },
    "segregation_analysis": {
      "violations_detected": 0,
      "users_with_conflicting_roles": 0
    }
  }
}

Four-eyes principle

Enforce dual approval for sensitive actions:

{
  "settings": {
    "governance": {
      "require_approval": {
        "exception_write_off": true,
        "high_value_match": true,
        "threshold_amount": 100000.0
      },
      "approver_role": "reconciliation_admin"
    }
  }
}

API security

Rate limiting

Protect against abuse with rate limits:

Endpoint Type	Limit
Read operations	1000/minute
Write operations	100/minute
Report generation	10/minute
File uploads	20/minute

Rate limit headers

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

Ip allowlisting

Restrict API access to known IP ranges:

{
  "settings": {
    "security": {
      "ip_allowlist": [
        "10.0.0.0/8",
        "192.168.1.0/24",
        "203.0.113.50"
      ],
      "enforce_allowlist": true
    }
  }
}

Request signing

For high-security environments, enable request signing:

# Generate signature
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"

Security monitoring

Security events

Monitor security-relevant events:

curl -X GET "https://api.matcher.example.com/v1/admin/security/events" \
 -H "Authorization: Bearer $TOKEN" \
 -G \
 -d "severity=HIGH" \
 -d "date_from=2024-01-20"

Response

{
  "events": [
    {
      "id": "sec_001",
      "timestamp": "2024-01-20T14:30:00Z",
      "type": "AUTHENTICATION_FAILURE",
      "severity": "HIGH",
      "details": {
        "user_id": "user_456",
        "ip_address": "192.168.1.200",
        "failure_reason": "invalid_token",
        "attempt_count": 5
      }
    }
  ]
}

Security alerts

Configure alerts for security events:

{
  "settings": {
    "alerts": {
      "security": {
        "failed_auth_threshold": 5,
        "unusual_access_pattern": true,
        "permission_escalation": true,
        "notification_channels": [
          "[email protected]",
          "slack:#security"
        ]
      }
    }
  }
}

Best practices

Use least privilege access

Grant users only the permissions they need. Start with minimal access and add permissions as needed.

Rotate credentials regularly

Implement automatic rotation for API keys and service credentials. Use short-lived tokens where possible.

Enable audit logging

Keep audit logs enabled and review them regularly. Set up alerts for suspicious activity.

Implement IP allowlisting

Restrict API access to known IP ranges, especially for production environments.

Use strong authentication

Require MFA for user accounts. Use certificate-based auth for service accounts when possible.

Review access regularly

Conduct periodic access reviews. Remove access promptly when users change roles or leave.

Encrypt sensitive data

Enable field-level encryption for sensitive transaction data beyond database encryption.

Monitor security events

Set up real-time monitoring and alerting for security events. Investigate anomalies promptly.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​Overview

​Layer protection

​Authentication

​Supported authentication methods

​JWT token structure

​Required headers

​Token validation

​Service-to-service authentication

​Response

​Authorization (rbac)

​Permission structure

​Complete permission list

​Ingestion

​Matching

​Exception

​Governance

​Administration

​Built-in roles

​Custom roles

​Response

​Assign roles to users

​Tenant isolation

​How it works

​Database schema structure

​Isolation guarantees

​Verify tenant isolation

​Audit trail

​Audited events

​Audit log structure

​Query audit logs

​Response

​Audit log retention

​Export audit logs

​Data encryption

​Encryption in transit

​Encryption at rest

​Sensitive field encryption

​Key management

​SOX compliance

​SOX control features

​SOX compliance report

​Response

​Four-eyes principle

​API security

​Rate limiting

​Rate limit headers

​Ip allowlisting

​Request signing

​Security monitoring

​Security events

​Response

​Security alerts

​Best practices

​Next steps

Match Rules

Exception Routing

Overview

Layer protection

Authentication

Supported authentication methods

JWT token structure

Required headers

Token validation

Service-to-service authentication

Response

Authorization (rbac)

Permission structure

Complete permission list

Ingestion

Matching

Exception

Governance

Administration

Built-in roles

Custom roles

Response

Assign roles to users

Tenant isolation

How it works

Database schema structure

Isolation guarantees

Verify tenant isolation

Audit trail

Audited events

Audit log structure

Query audit logs

Response

Audit log retention

Export audit logs

Data encryption

Encryption in transit

Encryption at rest

Sensitive field encryption

Key management

SOX compliance

SOX control features

SOX compliance report

Response

Four-eyes principle

API security

Rate limiting

Rate limit headers

Ip allowlisting

Request signing

Security monitoring

Security events

Response

Security alerts

Best practices

Next steps