677 lines
22 KiB
Markdown
677 lines
22 KiB
Markdown
# API Key Management Service (KMS) - System Architecture
|
|
|
|
## Table of Contents
|
|
1. [System Overview](#system-overview)
|
|
2. [Architecture Principles](#architecture-principles)
|
|
3. [Component Architecture](#component-architecture)
|
|
4. [System Architecture Diagram](#system-architecture-diagram)
|
|
5. [Request Flow Pipeline](#request-flow-pipeline)
|
|
6. [Authentication Flow](#authentication-flow)
|
|
7. [API Design](#api-design)
|
|
8. [Technology Stack](#technology-stack)
|
|
|
|
---
|
|
|
|
## System Overview
|
|
|
|
The API Key Management Service (KMS) is a secure, scalable platform for managing API authentication tokens across applications. Built with Go backend and React TypeScript frontend, it provides centralized token lifecycle management with enterprise-grade security features.
|
|
|
|
### Key Capabilities
|
|
- **Multi-Provider Authentication**: Header, JWT, OAuth2, SAML support
|
|
- **Dual Token System**: Static HMAC tokens and renewable JWT user tokens
|
|
- **Hierarchical Permissions**: Role-based access control with inheritance
|
|
- **Enterprise Security**: Rate limiting, brute force protection, audit logging
|
|
- **High Availability**: Containerized deployment with load balancing
|
|
|
|
### Core Features
|
|
- **Token Lifecycle Management**: Create, verify, renew, and revoke tokens
|
|
- **Application Management**: Multi-tenant application configuration
|
|
- **User Session Tracking**: Comprehensive session management
|
|
- **Audit Logging**: Complete audit trail of all operations
|
|
- **Health Monitoring**: Built-in health checks and metrics
|
|
|
|
---
|
|
|
|
## Architecture Principles
|
|
|
|
### Clean Architecture
|
|
The system follows clean architecture principles with clear separation of concerns:
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Handlers │ ← HTTP request handling
|
|
├─────────────────┤
|
|
│ Services │ ← Business logic
|
|
├─────────────────┤
|
|
│ Repositories │ ← Data access
|
|
├─────────────────┤
|
|
│ Database │ ← Data persistence
|
|
└─────────────────┘
|
|
```
|
|
|
|
### Design Principles
|
|
- **Dependency Injection**: All services receive dependencies through constructors
|
|
- **Interface Segregation**: Repository interfaces enable testing and flexibility
|
|
- **Single Responsibility**: Each component has one clear purpose
|
|
- **Fail-Safe Defaults**: Security-first configuration with safe fallbacks
|
|
- **Immutable Operations**: Database transactions and audit logging
|
|
- **Defense in Depth**: Multiple security layers throughout the stack
|
|
|
|
---
|
|
|
|
## Component Architecture
|
|
|
|
### Backend Components (`internal/`)
|
|
|
|
#### **Handlers Layer** (`internal/handlers/`)
|
|
HTTP request processors implementing REST API endpoints:
|
|
|
|
- **`application.go`**: Application CRUD operations
|
|
- Create, read, update, delete applications
|
|
- HMAC key management
|
|
- Ownership validation
|
|
|
|
- **`auth.go`**: Authentication workflows
|
|
- User login and logout
|
|
- Token renewal and validation
|
|
- Multi-provider authentication
|
|
|
|
- **`token.go`**: Token operations
|
|
- Static token creation
|
|
- Token verification
|
|
- Token revocation
|
|
|
|
- **`health.go`**: System health checks
|
|
- Database connectivity
|
|
- Cache availability
|
|
- Service status
|
|
|
|
- **`oauth2.go`, `saml.go`**: External authentication providers
|
|
- OAuth2 authorization code flow
|
|
- SAML assertion validation
|
|
- Provider callback handling
|
|
|
|
#### **Services Layer** (`internal/services/`)
|
|
Business logic implementation with transaction management:
|
|
|
|
- **`auth_service.go`**: Authentication provider orchestration
|
|
- Multi-provider authentication
|
|
- Session management
|
|
- User context creation
|
|
|
|
- **`token_service.go`**: Token lifecycle management
|
|
- Static token generation and validation
|
|
- JWT user token management
|
|
- Permission assignment
|
|
|
|
- **`application_service.go`**: Application configuration management
|
|
- Application CRUD operations
|
|
- Configuration validation
|
|
- HMAC key rotation
|
|
|
|
- **`session_service.go`**: User session tracking
|
|
- Session creation and validation
|
|
- Session timeout handling
|
|
- Cross-provider session management
|
|
|
|
#### **Repository Layer** (`internal/repository/postgres/`)
|
|
Data access with ACID transaction support:
|
|
|
|
- **`application_repository.go`**: Application persistence
|
|
- Secure dynamic query building
|
|
- Parameterized queries
|
|
- Ownership validation
|
|
|
|
- **`token_repository.go`**: Static token management
|
|
- BCrypt token hashing
|
|
- Token lookup and validation
|
|
- Permission relationship management
|
|
|
|
- **`permission_repository.go`**: Permission catalog
|
|
- Hierarchical permission structure
|
|
- Permission validation
|
|
- Bulk permission operations
|
|
|
|
- **`session_repository.go`**: User session storage
|
|
- Session persistence
|
|
- Expiration management
|
|
- Provider metadata storage
|
|
|
|
#### **Authentication Providers** (`internal/auth/`)
|
|
Pluggable authentication system:
|
|
|
|
- **`header_validator.go`**: HMAC signature validation
|
|
- Timestamp-based replay protection
|
|
- Constant-time signature comparison
|
|
- Email format validation
|
|
|
|
- **`jwt.go`**: JWT token management
|
|
- Token generation with secure JTI
|
|
- Signature validation
|
|
- Revocation list management
|
|
|
|
- **`oauth2.go`**: OAuth2 authorization code flow
|
|
- State management
|
|
- Token exchange
|
|
- Provider integration
|
|
|
|
- **`saml.go`**: SAML assertion validation
|
|
- XML signature validation
|
|
- Attribute extraction
|
|
- Provider configuration
|
|
|
|
- **`permissions.go`**: Hierarchical permission evaluation
|
|
- Role-based access control
|
|
- Permission inheritance
|
|
- Bulk permission evaluation
|
|
|
|
---
|
|
|
|
## System Architecture Diagram
|
|
|
|
```mermaid
|
|
graph TB
|
|
%% External Components
|
|
Client[Client Applications]
|
|
Browser[Web Browser]
|
|
AuthProvider[OAuth2/SAML Provider]
|
|
|
|
%% Load Balancer & Proxy
|
|
subgraph "Load Balancer Layer"
|
|
Nginx[Nginx Proxy<br/>:80, :8081]
|
|
end
|
|
|
|
%% Frontend Layer
|
|
subgraph "Frontend Layer"
|
|
React[React TypeScript SPA<br/>Ant Design UI<br/>:3000]
|
|
AuthContext[Authentication Context]
|
|
APIService[API Service Client]
|
|
end
|
|
|
|
%% API Gateway & Middleware
|
|
subgraph "API Layer"
|
|
API[Go API Server<br/>:8080]
|
|
|
|
subgraph "Middleware Chain"
|
|
Logger[Request Logger]
|
|
Security[Security Headers<br/>CORS, CSRF]
|
|
RateLimit[Rate Limiter<br/>100 RPS]
|
|
Auth[Authentication<br/>Header/JWT/OAuth2/SAML]
|
|
Validation[Request Validator]
|
|
end
|
|
end
|
|
|
|
%% Business Logic Layer
|
|
subgraph "Service Layer"
|
|
AuthService[Authentication Service]
|
|
TokenService[Token Service]
|
|
AppService[Application Service]
|
|
SessionService[Session Service]
|
|
PermService[Permission Service]
|
|
end
|
|
|
|
%% Data Access Layer
|
|
subgraph "Repository Layer"
|
|
AppRepo[Application Repository]
|
|
TokenRepo[Token Repository]
|
|
PermRepo[Permission Repository]
|
|
SessionRepo[Session Repository]
|
|
end
|
|
|
|
%% Infrastructure Layer
|
|
subgraph "Infrastructure"
|
|
PostgreSQL[(PostgreSQL 15<br/>:5432)]
|
|
Redis[(Redis Cache<br/>Optional)]
|
|
Metrics[Prometheus Metrics<br/>:9090]
|
|
end
|
|
|
|
%% External Security
|
|
subgraph "Security & Crypto"
|
|
HMAC[HMAC Signature<br/>Validation]
|
|
BCrypt[BCrypt Hashing<br/>Cost 14]
|
|
JWT[JWT Token<br/>Generation]
|
|
end
|
|
|
|
%% Flow Connections
|
|
Client -->|API Requests| Nginx
|
|
Browser -->|HTTPS| Nginx
|
|
AuthProvider -->|OAuth2/SAML| API
|
|
|
|
Nginx -->|Proxy| React
|
|
Nginx -->|API Proxy| API
|
|
|
|
React --> AuthContext
|
|
React --> APIService
|
|
APIService -->|REST API| API
|
|
|
|
API --> Logger
|
|
Logger --> Security
|
|
Security --> RateLimit
|
|
RateLimit --> Auth
|
|
Auth --> Validation
|
|
Validation --> AuthService
|
|
Validation --> TokenService
|
|
Validation --> AppService
|
|
Validation --> SessionService
|
|
Validation --> PermService
|
|
|
|
AuthService --> AppRepo
|
|
TokenService --> TokenRepo
|
|
AppService --> AppRepo
|
|
SessionService --> SessionRepo
|
|
PermService --> PermRepo
|
|
|
|
AppRepo --> PostgreSQL
|
|
TokenRepo --> PostgreSQL
|
|
PermRepo --> PostgreSQL
|
|
SessionRepo --> PostgreSQL
|
|
|
|
TokenService --> HMAC
|
|
TokenService --> BCrypt
|
|
TokenService --> JWT
|
|
AuthService --> Redis
|
|
|
|
API --> Metrics
|
|
|
|
%% Styling
|
|
classDef frontend fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
|
|
classDef api fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
|
|
classDef service fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
|
|
classDef data fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
|
|
classDef security fill:#ffebee,stroke:#c62828,stroke-width:2px
|
|
|
|
class React,AuthContext,APIService frontend
|
|
class API,Logger,Security,RateLimit,Auth,Validation api
|
|
class AuthService,TokenService,AppService,SessionService,PermService service
|
|
class PostgreSQL,Redis,Metrics,AppRepo,TokenRepo,PermRepo,SessionRepo data
|
|
class HMAC,BCrypt,JWT security
|
|
```
|
|
|
|
---
|
|
|
|
## Request Flow Pipeline
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
Start([HTTP Request]) --> Nginx{Nginx Proxy<br/>Load Balancer}
|
|
|
|
Nginx -->|Static Assets| Frontend[React SPA<br/>Port 3000]
|
|
Nginx -->|API Routes| API[Go API Server<br/>Port 8080]
|
|
|
|
API --> Logger[Request Logger<br/>Structured Logging]
|
|
Logger --> Security[Security Middleware<br/>Headers, CORS, CSRF]
|
|
Security --> RateLimit{Rate Limiter<br/>100 RPS, 200 Burst}
|
|
|
|
RateLimit -->|Exceeded| RateResponse[429 Too Many Requests]
|
|
RateLimit -->|Within Limits| Auth[Authentication<br/>Middleware]
|
|
|
|
Auth --> AuthHeader{Auth Provider}
|
|
AuthHeader -->|header| HeaderAuth[Header Validator<br/>X-User-Email]
|
|
AuthHeader -->|jwt| JWTAuth[JWT Validator<br/>Signature + Claims]
|
|
AuthHeader -->|oauth2| OAuth2Auth[OAuth2 Flow<br/>Authorization Code]
|
|
AuthHeader -->|saml| SAMLAuth[SAML Assertion<br/>XML Validation]
|
|
|
|
HeaderAuth --> AuthCache{Check Cache<br/>Redis 5min TTL}
|
|
JWTAuth --> JWTValidation[Signature Validation<br/>Expiry Check]
|
|
OAuth2Auth --> OAuth2Exchange[Token Exchange<br/>User Info Retrieval]
|
|
SAMLAuth --> SAMLValidation[Assertion Validation<br/>Signature Check]
|
|
|
|
AuthCache -->|Hit| AuthContext[Create AuthContext]
|
|
AuthCache -->|Miss| DBAuth[Database Lookup<br/>User Permissions]
|
|
JWTValidation --> RevocationCheck[Check Revocation List<br/>Redis Cache]
|
|
OAuth2Exchange --> SessionStore[Store User Session<br/>PostgreSQL]
|
|
SAMLValidation --> SessionStore
|
|
|
|
DBAuth --> CacheStore[Store in Cache<br/>5min TTL]
|
|
RevocationCheck --> AuthContext
|
|
SessionStore --> AuthContext
|
|
CacheStore --> AuthContext
|
|
|
|
AuthContext --> Validation[Request Validator<br/>JSON Schema]
|
|
Validation -->|Invalid| ValidationError[400 Bad Request]
|
|
Validation -->|Valid| Router{Route Handler}
|
|
|
|
Router -->|/health| HealthHandler[Health Check<br/>DB + Cache Status]
|
|
Router -->|/api/applications| AppHandler[Application CRUD<br/>HMAC Key Management]
|
|
Router -->|/api/tokens| TokenHandler[Token Operations<br/>Create, Verify, Revoke]
|
|
Router -->|/api/login| AuthHandler[Authentication<br/>Login, Renewal]
|
|
Router -->|/api/oauth2| OAuth2Handler[OAuth2 Callbacks<br/>State Management]
|
|
Router -->|/api/saml| SAMLHandler[SAML Callbacks<br/>Assertion Processing]
|
|
|
|
HealthHandler --> Service[Service Layer]
|
|
AppHandler --> Service
|
|
TokenHandler --> Service
|
|
AuthHandler --> Service
|
|
OAuth2Handler --> Service
|
|
SAMLHandler --> Service
|
|
|
|
Service --> Repository[Repository Layer<br/>Database Operations]
|
|
Repository --> PostgreSQL[(PostgreSQL<br/>ACID Transactions)]
|
|
|
|
Service --> CryptoOps[Cryptographic Operations]
|
|
CryptoOps --> HMAC[HMAC Signature<br/>Timestamp Validation]
|
|
CryptoOps --> BCrypt[BCrypt Hashing<br/>Cost 14]
|
|
CryptoOps --> JWT[JWT Generation<br/>RS256 Signing]
|
|
|
|
Repository --> AuditLog[Audit Logging<br/>All Operations]
|
|
AuditLog --> AuditTable[(audit_logs table)]
|
|
|
|
Service --> Response[HTTP Response]
|
|
Response --> Metrics[Prometheus Metrics<br/>Port 9090]
|
|
Response --> End([Response Sent])
|
|
|
|
%% Error Paths
|
|
RateResponse --> End
|
|
ValidationError --> End
|
|
|
|
%% Styling
|
|
classDef middleware fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
|
|
classDef auth fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
|
|
classDef handler fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
|
|
classDef data fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
|
|
classDef crypto fill:#ffebee,stroke:#c62828,stroke-width:2px
|
|
classDef error fill:#fce4ec,stroke:#ad1457,stroke-width:2px
|
|
|
|
class Logger,Security,RateLimit,Validation middleware
|
|
class Auth,HeaderAuth,JWTAuth,OAuth2Auth,SAMLAuth,AuthContext auth
|
|
class HealthHandler,AppHandler,TokenHandler,AuthHandler,OAuth2Handler,SAMLHandler,Service handler
|
|
class Repository,PostgreSQL,AuditTable,AuthCache data
|
|
class CryptoOps,HMAC,BCrypt,JWT crypto
|
|
class RateResponse,ValidationError error
|
|
```
|
|
|
|
### Request Processing Pipeline
|
|
|
|
1. **Load Balancer**: Nginx receives and routes requests
|
|
2. **Static Assets**: React SPA served directly by Nginx
|
|
3. **API Gateway**: Go server handles API requests
|
|
4. **Middleware Chain**: Security, rate limiting, authentication
|
|
5. **Route Handler**: Business logic processing
|
|
6. **Service Layer**: Transaction management and orchestration
|
|
7. **Repository Layer**: Database operations with audit logging
|
|
8. **Response**: JSON response with metrics collection
|
|
|
|
---
|
|
|
|
## Authentication Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client App
|
|
participant API as API Gateway
|
|
participant Auth as Auth Service
|
|
participant DB as PostgreSQL
|
|
participant Provider as OAuth2/SAML
|
|
participant Cache as Redis Cache
|
|
|
|
%% Header-based Authentication
|
|
rect rgb(240, 248, 255)
|
|
Note over Client, Cache: Header-based Authentication Flow
|
|
Client->>API: Request with X-User-Email header
|
|
API->>Auth: Validate header auth
|
|
Auth->>DB: Check user permissions
|
|
DB-->>Auth: Return user context
|
|
Auth->>Cache: Cache auth result (5min TTL)
|
|
Auth-->>API: AuthContext{UserID, Permissions}
|
|
API-->>Client: Authenticated response
|
|
end
|
|
|
|
%% JWT Authentication Flow
|
|
rect rgb(245, 255, 245)
|
|
Note over Client, Cache: JWT Authentication Flow
|
|
Client->>API: Login request {app_id, permissions}
|
|
API->>Auth: Generate JWT token
|
|
Auth->>DB: Validate app_id and permissions
|
|
DB-->>Auth: Application config
|
|
Auth->>Auth: Create JWT with claims<br/>{user_id, permissions, exp, iat}
|
|
Auth-->>API: JWT token + expires_at
|
|
API-->>Client: LoginResponse{token, expires_at}
|
|
|
|
Note over Client, API: Subsequent requests with JWT
|
|
Client->>API: Request with Bearer JWT
|
|
API->>Auth: Verify JWT signature
|
|
Auth->>Auth: Check expiration & claims
|
|
Auth->>Cache: Check revocation list
|
|
Cache-->>Auth: Token status
|
|
Auth-->>API: Valid AuthContext
|
|
API-->>Client: Authorized response
|
|
end
|
|
|
|
%% OAuth2/SAML Flow
|
|
rect rgb(255, 248, 240)
|
|
Note over Client, Provider: OAuth2/SAML Authentication Flow
|
|
Client->>API: POST /api/login {app_id, redirect_uri}
|
|
API->>Auth: Generate OAuth2 state
|
|
Auth->>DB: Store state + app context
|
|
Auth-->>API: Redirect URL + state
|
|
API-->>Client: {redirect_url, state}
|
|
|
|
Client->>Provider: Redirect to OAuth2 provider
|
|
Provider-->>Client: Authorization code + state
|
|
|
|
Client->>API: GET /api/oauth2/callback?code=xxx&state=yyy
|
|
API->>Auth: Validate state and exchange code
|
|
Auth->>Provider: Exchange code for tokens
|
|
Provider-->>Auth: Access token + ID token
|
|
Auth->>Provider: Get user info
|
|
Provider-->>Auth: User profile
|
|
Auth->>DB: Create/update user session
|
|
Auth->>Auth: Generate internal JWT
|
|
Auth-->>API: JWT token + user context
|
|
API-->>Client: Set-Cookie with JWT + redirect
|
|
end
|
|
|
|
%% Token Renewal Flow
|
|
rect rgb(248, 245, 255)
|
|
Note over Client, DB: Token Renewal Flow
|
|
Client->>API: POST /api/renew {app_id, user_id, token}
|
|
API->>Auth: Validate current token
|
|
Auth->>Auth: Check token expiration<br/>and max_valid_at
|
|
Auth->>DB: Get application config
|
|
DB-->>Auth: TokenRenewalDuration, MaxTokenDuration
|
|
Auth->>Auth: Generate new JWT<br/>with extended expiry
|
|
Auth->>Cache: Invalidate old token
|
|
Auth-->>API: New token + expires_at
|
|
API-->>Client: RenewResponse{token, expires_at}
|
|
end
|
|
```
|
|
|
|
### Authentication Methods
|
|
|
|
#### **Header-based Authentication**
|
|
- **Use Case**: Service-to-service authentication
|
|
- **Security**: HMAC-SHA256 signatures with timestamp validation
|
|
- **Replay Protection**: 5-minute timestamp window
|
|
- **Caching**: 5-minute Redis cache for performance
|
|
|
|
#### **JWT Authentication**
|
|
- **Use Case**: User authentication with session management
|
|
- **Security**: RSA signatures with revocation checking
|
|
- **Token Lifecycle**: Configurable expiration with renewal
|
|
- **Claims**: User ID, permissions, application scope
|
|
|
|
#### **OAuth2/SAML Authentication**
|
|
- **Use Case**: External identity provider integration
|
|
- **Security**: Authorization code flow with state validation
|
|
- **Session Management**: Database-backed session storage
|
|
- **Provider Support**: Configurable provider endpoints
|
|
|
|
---
|
|
|
|
## API Design
|
|
|
|
### RESTful Endpoints
|
|
|
|
#### **Authentication Endpoints**
|
|
```
|
|
POST /api/login - Authenticate user, issue JWT
|
|
POST /api/renew - Renew JWT token
|
|
POST /api/logout - Revoke JWT token
|
|
GET /api/verify - Verify token and permissions
|
|
```
|
|
|
|
#### **Application Management**
|
|
```
|
|
GET /api/applications - List applications (paginated)
|
|
POST /api/applications - Create application
|
|
GET /api/applications/:id - Get application details
|
|
PUT /api/applications/:id - Update application
|
|
DELETE /api/applications/:id - Delete application
|
|
```
|
|
|
|
#### **Token Management**
|
|
```
|
|
GET /api/applications/:id/tokens - List application tokens
|
|
POST /api/applications/:id/tokens - Create new token
|
|
DELETE /api/tokens/:id - Revoke token
|
|
```
|
|
|
|
#### **OAuth2/SAML Integration**
|
|
```
|
|
POST /api/oauth2/login - Initiate OAuth2 flow
|
|
GET /api/oauth2/callback - OAuth2 callback handler
|
|
POST /api/saml/login - Initiate SAML flow
|
|
POST /api/saml/callback - SAML assertion handler
|
|
```
|
|
|
|
#### **System Endpoints**
|
|
```
|
|
GET /health - System health check
|
|
GET /ready - Readiness probe
|
|
GET /metrics - Prometheus metrics
|
|
```
|
|
|
|
### Request/Response Patterns
|
|
|
|
#### **Authentication Headers**
|
|
```http
|
|
X-User-Email: user@example.com
|
|
X-Auth-Timestamp: 2024-01-15T10:30:00Z
|
|
X-Auth-Signature: sha256=abc123...
|
|
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
|
|
Content-Type: application/json
|
|
```
|
|
|
|
#### **Error Response Format**
|
|
```json
|
|
{
|
|
"error": "validation_failed",
|
|
"message": "Request validation failed",
|
|
"details": [
|
|
{
|
|
"field": "permissions",
|
|
"message": "Invalid permission format",
|
|
"value": "invalid.perm"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### **Success Response Format**
|
|
```json
|
|
{
|
|
"data": {
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"token": "ABC123_xyz789...",
|
|
"permissions": ["app.read", "token.create"],
|
|
"created_at": "2024-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Technology Stack
|
|
|
|
### Backend Technologies
|
|
- **Language**: Go 1.21+ with modules
|
|
- **Web Framework**: Gin HTTP framework
|
|
- **Database**: PostgreSQL 15 with connection pooling
|
|
- **Authentication**: JWT-Go library with RSA signing
|
|
- **Cryptography**: Go standard crypto libraries
|
|
- **Caching**: Redis for session and revocation storage
|
|
- **Logging**: Zap structured logging
|
|
- **Metrics**: Prometheus metrics collection
|
|
|
|
### Frontend Technologies
|
|
- **Framework**: React 18 with TypeScript
|
|
- **UI Library**: Ant Design components
|
|
- **State Management**: React Context API
|
|
- **HTTP Client**: Axios with interceptors
|
|
- **Routing**: React Router with protected routes
|
|
- **Build Tool**: Create React App with TypeScript
|
|
|
|
### Infrastructure
|
|
- **Containerization**: Docker with multi-stage builds
|
|
- **Orchestration**: Docker Compose for local development
|
|
- **Reverse Proxy**: Nginx with load balancing
|
|
- **Database Migrations**: Custom Go migration system
|
|
- **Health Monitoring**: Built-in health check endpoints
|
|
|
|
### Security Stack
|
|
- **TLS**: TLS 1.3 for all communications
|
|
- **Hashing**: BCrypt with cost 14 for production
|
|
- **Signatures**: HMAC-SHA256 and RSA signatures
|
|
- **Rate Limiting**: Token bucket algorithm
|
|
- **CSRF**: Double-submit cookie pattern
|
|
- **Headers**: Comprehensive security headers
|
|
|
|
---
|
|
|
|
## Deployment Considerations
|
|
|
|
### Container Configuration
|
|
```yaml
|
|
services:
|
|
kms-api:
|
|
image: kms-api:latest
|
|
ports:
|
|
- "8080:8080"
|
|
environment:
|
|
- DB_HOST=postgres
|
|
- DB_PORT=5432
|
|
- JWT_SECRET=${JWT_SECRET}
|
|
- HMAC_KEY=${HMAC_KEY}
|
|
healthcheck:
|
|
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
|
|
interval: 30s
|
|
timeout: 10s
|
|
retries: 3
|
|
```
|
|
|
|
### Environment Variables
|
|
```bash
|
|
# Database Configuration
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
DB_NAME=kms
|
|
DB_USER=postgres
|
|
DB_PASSWORD=postgres
|
|
|
|
# Server Configuration
|
|
SERVER_HOST=0.0.0.0
|
|
SERVER_PORT=8080
|
|
|
|
# Authentication
|
|
AUTH_PROVIDER=header
|
|
JWT_SECRET=your-jwt-secret
|
|
HMAC_KEY=your-hmac-key
|
|
|
|
# Security
|
|
RATE_LIMIT_ENABLED=true
|
|
RATE_LIMIT_RPS=100
|
|
RATE_LIMIT_BURST=200
|
|
```
|
|
|
|
### Monitoring Setup
|
|
```yaml
|
|
prometheus:
|
|
scrape_configs:
|
|
- job_name: 'kms-api'
|
|
static_configs:
|
|
- targets: ['kms-api:9090']
|
|
scrape_interval: 15s
|
|
metrics_path: /metrics
|
|
```
|
|
|
|
This architecture documentation provides a comprehensive technical overview of the KMS system, suitable for development teams, system architects, and operations personnel who need to understand, deploy, or maintain the system. |