Security Architecture

Overview

BankLingo implements a comprehensive, defense-in-depth security architecture to protect customer data, financial transactions, and system integrity. This document describes the authentication layers, authorization mechanisms, encryption strategies, compliance measures, and security best practices.

High-Level Security Architecture

Authentication Architecture

1. JWT-Based Authentication

JWT Token Structure:

Header:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-2026-01"
}

Payload:

{
  "sub": "user-123",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "roles": ["Teller", "Approver"],
  "permissions": [
    "transactions.create",
    "transactions.approve",
    "accounts.read",
    "customers.read"
  ],
  "branchId": "branch-456",
  "sessionId": "session-789",
  "deviceId": "device-abc",
  "iat": 1735729800,
  "exp": 1735733400,
  "nbf": 1735729800,
  "jti": "token-id-xyz",
  "iss": "https://api.banklingo.com",
  "aud": "banklingo-client"
}

Token Validation Process:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

---

2. OAuth 2.0 for Third-Party Applications

OAuth Scopes:

Scope	Description	Access Level
accounts.read	Read account information	Read-only access to account details, balances
accounts.write	Create/update accounts	Create savings accounts, update account details
transactions.read	Read transaction history	View transaction history and details
transactions.write	Create transactions	Initiate deposits, withdrawals (subject to approval)
customers.read	Read customer information	View customer profile, KYC details
customers.write	Create/update customers	Register new customers, update profiles
reports.read	Access reports	View and download financial reports

OAuth Client Registration:

{
  "clientId": "client-abc-123",
  "clientSecret": "secret-xyz-789-hashed",
  "clientName": "Mobile Banking App",
  "redirectUris": [
    "https://app.banklingo.com/callback",
    "https://app-staging.banklingo.com/callback"
  ],
  "allowedScopes": [
    "accounts.read",
    "transactions.read",
    "transactions.write"
  ],
  "tokenEndpointAuthMethod": "client_secret_post",
  "grantTypes": ["authorization_code", "refresh_token"],
  "requirePkce": true,
  "accessTokenLifetime": 3600,
  "refreshTokenLifetime": 604800
}

---

Authorization Architecture (RBAC + ABAC)

Role-Based Access Control (RBAC)

Attribute-Based Access Control (ABAC)

ABAC Policy Example:

{
  "policyId": "approve-transaction-policy",
  "effect": "Allow",
  "actions": ["transactions.approve"],
  "resources": ["Transaction"],
  "conditions": {
    "and": [
      {
        "attribute": "user.role",
        "operator": "in",
        "value": ["Teller", "Approver", "BranchManager"]
      },
      {
        "attribute": "transaction.amount",
        "operator": "lessThanOrEqual",
        "value": "user.approvalLimit"
      },
      {
        "attribute": "transaction.branchId",
        "operator": "equals",
        "value": "user.branchId"
      },
      {
        "attribute": "time.hourOfDay",
        "operator": "between",
        "value": [8, 18]
      },
      {
        "attribute": "transaction.status",
        "operator": "equals",
        "value": "PENDING"
      }
    ]
  }
}

Authorization Matrix:

Role	Approval Limit	Transaction Types	Branch Restriction	Time Restriction
Teller	₦500K	Deposit, Withdrawal	Own branch only	Business hours only (8am-6pm)
Senior Teller	₦2M	Deposit, Withdrawal, Cheque	Own branch only	Business hours + 1 hour overtime
Approver	₦5M	All types	Own branch only	Business hours only
Branch Manager	₦50M	All types	Own branch only	Anytime
Regional Manager	₦200M	All types	Assigned region	Anytime
Admin	Unlimited	All types	All branches	Anytime

---

Encryption Architecture

1. Encryption in Transit (TLS/SSL)

TLS Configuration:

• Protocol: TLS 1.2 minimum (TLS 1.3 preferred)
• Cipher Suites (ordered by preference):
  1. TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  2. TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  3. TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
• Certificate: Wildcard SSL (*.banklingo.com) with auto-renewal
• HSTS: Enabled (max-age=31536000, includeSubDomains, preload)
• Certificate Pinning: Mobile apps pin to root CA certificate

---

2. Encryption at Rest

Encrypted Data Classification:

Data Type	Encryption Method	Key Rotation	Access Control
PII (Name, Address)	TDE only	Annual	DB-level RBAC
Financial Data (Account Balance)	TDE + Application-level	Quarterly	Row-level security
Sensitive PII (BVN, NIN)	TDE + Always Encrypted	Monthly	Column-level encryption
Credentials (Passwords)	BCrypt hash (cost=12)	N/A (hashed)	No direct access
Payment Card Data (PAN)	TDE + Always Encrypted + Tokenization	Weekly	Tokenization service only
Audit Logs	TDE + Immutable storage	Annual	Append-only, read-only for auditors
Documents (KYC)	Blob encryption (AES-256)	Quarterly	SAS tokens with expiry

Application-Level Encryption Example:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

---

Network Security Architecture

1. Virtual Network Isolation

Network Security Group Rules:

App Service Subnet NSG:

Priority	Direction	Action	Source	Destination	Port	Protocol
100	Inbound	Allow	Azure Front Door	App Subnet	443	TCP
110	Inbound	Allow	Azure Bastion	App Subnet	443	TCP
200	Inbound	Deny	Any	App Subnet	Any	Any
100	Outbound	Allow	App Subnet	Data Subnet	1433, 6380	TCP
110	Outbound	Allow	App Subnet	Integration Subnet	443	TCP
120	Outbound	Allow	App Subnet	Internet	443	TCP

Data Subnet NSG:

Priority	Direction	Action	Source	Destination	Port	Protocol
100	Inbound	Allow	App Subnet	Data Subnet	1433	TCP
110	Inbound	Allow	App Subnet	Data Subnet	6380	TCP
200	Inbound	Deny	Any	Data Subnet	Any	Any
100	Outbound	Allow	Data Subnet	App Subnet	Any	TCP

---

2. Private Endpoints & Private Link

Benefits:

• ✅ No public IP exposure for data services
• ✅ Traffic stays within Azure backbone network
• ✅ No data exfiltration to public internet
• ✅ Enhanced compliance (GDPR, PCI-DSS)

Private Endpoint Configuration:

# Create private endpoint for SQL Database
az network private-endpoint create \
  --name pe-sql-banklingo \
  --resource-group rg-banklingo-prod \
  --vnet-name vnet-banklingo \
  --subnet data-subnet \
  --private-connection-resource-id /subscriptions/.../sqlServers/sql-banklingo \
  --group-id sqlServer \
  --connection-name pe-sql-connection

# Create private DNS zone
az network private-dns zone create \
  --resource-group rg-banklingo-prod \
  --name privatelink.database.windows.net

# Link DNS zone to VNet
az network private-dns link vnet create \
  --resource-group rg-banklingo-prod \
  --zone-name privatelink.database.windows.net \
  --name dns-link-sql \
  --virtual-network vnet-banklingo \
  --registration-enabled false

---

Security Monitoring & Threat Detection

Security Information & Event Management (SIEM)

Security Alerts & Detection Rules

Critical Security Alerts:

Alert	Condition	Severity	Response
Brute Force Attack	10+ failed logins in 5 min	Critical	Lock account, notify security team
Privilege Escalation	User gains admin role	Critical	Revert change, investigate
Data Exfiltration	Large data download (>1GB)	Critical	Block connection, alert CISO
SQL Injection Attempt	Malicious SQL in input	High	Block request, alert security team
Unusual Transaction	Transaction amount >10x average	High	Require approval, notify fraud team
Geo-Location Anomaly	Login from new country	Medium	Require MFA, notify user
Off-Hours Access	Admin access outside business hours	Medium	Log and notify security team
Failed MFA	3+ failed MFA attempts	Medium	Lock account temporarily

Azure Sentinel Detection Rules:

Suspicious Transaction Pattern:

AuditLog
| where TimeGenerated > ago(1h)
| where ActionType == "TransactionCreated"
| extend Amount = toreal(Properties.Amount)
| summarize 
    TransactionCount = count(),
    TotalAmount = sum(Amount),
    AvgAmount = avg(Amount)
  by UserId, bin(TimeGenerated, 5m)
| where TransactionCount > 10 or TotalAmount > 10000000
| project TimeGenerated, UserId, TransactionCount, TotalAmount, AvgAmount

Multiple Failed Login Attempts:

SigninLogs
| where TimeGenerated > ago(5m)
| where ResultType != 0 // Failed login
| summarize FailedAttempts = count() by UserPrincipalName, IPAddress
| where FailedAttempts >= 5
| project UserPrincipalName, IPAddress, FailedAttempts

---

Compliance & Audit Architecture

Audit Logging Strategy

Audit Log Schema:

CREATE TABLE AuditLog (
    Id UNIQUEIDENTIFIER PRIMARY KEY,
    Timestamp DATETIME2 NOT NULL,
    UserId UNIQUEIDENTIFIER NOT NULL,
    Action NVARCHAR(100) NOT NULL,
    ResourceType NVARCHAR(50) NOT NULL,
    ResourceId NVARCHAR(100),
    OldValue NVARCHAR(MAX),
    NewValue NVARCHAR(MAX),
    IPAddress NVARCHAR(45),
    UserAgent NVARCHAR(500),
    Result NVARCHAR(20) NOT NULL, -- SUCCESS, FAILED
    ErrorMessage NVARCHAR(MAX),
    SessionId UNIQUEIDENTIFIER,
    BranchId UNIQUEIDENTIFIER,
    INDEX IX_AuditLog_Timestamp (Timestamp DESC),
    INDEX IX_AuditLog_UserId (UserId, Timestamp DESC),
    INDEX IX_AuditLog_ResourceType (ResourceType, Timestamp DESC)
)

Audited Actions:

Category	Actions	Retention
Authentication	Login, Logout, Failed login, MFA verify, Token refresh	7 years
Authorization	Permission check, Role change, Access denied	7 years
Transactions	Create, Approve, Reject, Cancel, Reverse	10 years
Account Management	Create account, Update account, Close account, Change balance	10 years
User Management	Create user, Update user, Disable user, Reset password	7 years
System Configuration	Update settings, Change product config, Modify rates	7 years
Data Access	View sensitive data (BVN, PAN), Export reports	5 years

---

Compliance Frameworks

PCI-DSS v4.0 Compliance:

Requirement	Implementation	Status
1. Firewall configuration	NSG rules, Azure Front Door WAF	✅ Compliant
2. Secure defaults	Disabled default credentials, secure config	✅ Compliant
3. Protect stored data	TDE, Always Encrypted, tokenization	✅ Compliant
4. Encrypt in transit	TLS 1.2+, strong cipher suites	✅ Compliant
5. Anti-malware	Microsoft Defender for Cloud	✅ Compliant
6. Secure systems	Patching, vulnerability scanning	✅ Compliant
7. Access control	RBAC, ABAC, least privilege	✅ Compliant
8. Unique IDs	Unique user IDs, no shared accounts	✅ Compliant
9. Physical access	Azure datacenter security	✅ Compliant
10. Logging & monitoring	Audit logs, SIEM, alerting	✅ Compliant
11. Security testing	Penetration testing, vulnerability scans	✅ Compliant
12. Security policy	Information security policy	✅ Compliant

GDPR Compliance:

Right	Implementation	Status
Right to access	Customer portal to view personal data	✅ Implemented
Right to rectification	API to update personal information	✅ Implemented
Right to erasure	Data deletion API (soft delete + anonymization)	✅ Implemented
Right to portability	Export data in JSON format	✅ Implemented
Right to object	Opt-out of marketing communications	✅ Implemented
Data breach notification	Automated alerting within 72 hours	✅ Implemented
Data minimization	Collect only necessary data	✅ Implemented
Consent management	Explicit consent for data processing	✅ Implemented

---

Security Best Practices

1. Secure Development Practices

• ✅ Code reviews - All code changes reviewed by 2+ developers
• ✅ Static analysis - SonarQube for code quality and security
• ✅ Dependency scanning - OWASP Dependency-Check for vulnerable libraries
• ✅ Secret scanning - No secrets in source code (use Key Vault)
• ✅ Security testing - OWASP ZAP for vulnerability scanning
• ✅ Penetration testing - Annual third-party penetration tests

2. Operational Security

• ✅ Principle of least privilege - Minimal permissions for users and services
• ✅ Defense in depth - Multiple layers of security
• ✅ Zero trust - Verify every request, never trust by default
• ✅ Patch management - Monthly security patches, critical patches within 48 hours
• ✅ Incident response plan - Documented procedures for security incidents
• ✅ Disaster recovery testing - Quarterly DR drills

3. Data Protection

• ✅ Data classification - PII, Financial, Public, Internal
• ✅ Encryption everywhere - In transit and at rest
• ✅ Data masking - Mask sensitive data in non-production environments
• ✅ Backup encryption - Encrypted backups with separate keys
• ✅ Data retention - Automated deletion per retention policy
• ✅ Data loss prevention - Prevent unauthorized data export

4. Access Management

• ✅ MFA enforcement - Required for all admin accounts
• ✅ Conditional access - Device compliance, location-based access
• ✅ Just-in-time access - Temporary elevated privileges
• ✅ Privileged access workstations - Dedicated machines for admin tasks
• ✅ Access reviews - Quarterly review of user permissions
• ✅ Session management - Automatic logout after 30 minutes of inactivity

5. Security Awareness

• ✅ Security training - Annual security awareness training for all staff
• ✅ Phishing simulations - Quarterly phishing tests
• ✅ Incident reporting - Clear process for reporting security concerns
• ✅ Security champions - Designated security advocates in each team
• ✅ Threat intelligence - Subscribe to security bulletins and advisories

---

Related Diagrams

• System Architecture - Overall system overview
• Component Architecture - Modules and components
• Deployment Architecture - Azure infrastructure
• Data Flow Architecture - Transaction flows
• Integration Architecture - External integrations

---

Summary

The security architecture provides:

• ✅ Authentication - JWT + OAuth 2.0 with MFA support
• ✅ Authorization - RBAC + ABAC with fine-grained access control
• ✅ Encryption - TLS 1.2+ in transit, AES-256 at rest
• ✅ Network Security - VNet isolation, NSGs, private endpoints
• ✅ Monitoring - SIEM with Azure Sentinel, real-time threat detection
• ✅ Audit Logging - Immutable audit trails with 7-10 year retention
• ✅ Compliance - PCI-DSS, GDPR, CBN guidelines adherence
• ✅ Best Practices - Defense in depth, zero trust, least privilege

Security Posture:

• Authentication: Multi-factor, token-based with short expiry
• Authorization: Role and attribute-based with approval limits
• Data Protection: Encrypted at rest and in transit
• Network: Isolated subnets with private endpoints
• Monitoring: Real-time threat detection with automated response
• Compliance: PCI-DSS, GDPR, SOC 2 certified