0x1d
38a251968c
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.
Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
- Each service has own entry point (cmd/{service}/)
- Each service has own gRPC server and database schema
- Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
- Single entry point for all external traffic
- Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation
Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files
New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)
New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
150 lines
5.6 KiB
Markdown
150 lines
5.6 KiB
Markdown
# Story 2.1: Auth Service - JWT Authentication
|
|
|
|
## Metadata
|
|
- **Story ID**: 2.1
|
|
- **Title**: Auth Service - JWT Authentication
|
|
- **Epic**: 2 - Core Services (Authentication & Authorization)
|
|
- **Status**: Pending
|
|
- **Priority**: High
|
|
- **Estimated Time**: 8-10 hours
|
|
- **Dependencies**: 1.1, 1.2, 1.5, 1.7
|
|
|
|
## Goal
|
|
Implement Auth Service as an independent microservice with JWT token generation/validation. The service exposes a gRPC server, manages its own database connection, and registers with Consul service registry.
|
|
|
|
## Description
|
|
This story implements the Auth Service as a separate, independently deployable microservice. It includes JWT token generation, verification, login/refresh endpoints via gRPC, and integration with Identity Service for user credential validation. The service has its own entry point, database connection, and service registration.
|
|
|
|
## Deliverables
|
|
|
|
### 1. Service Entry Point (`cmd/auth-service/main.go`)
|
|
- Independent service entry point
|
|
- Bootstrap with core kernel services
|
|
- Register with Consul service registry
|
|
- Start gRPC server on configured port (default: 8081)
|
|
- Graceful shutdown with service deregistration
|
|
|
|
### 2. gRPC Service Definition (`api/proto/auth.proto`)
|
|
- `LoginRequest` / `LoginResponse` - User login
|
|
- `RefreshTokenRequest` / `RefreshTokenResponse` - Token refresh
|
|
- `ValidateTokenRequest` / `ValidateTokenResponse` - Token validation
|
|
- `AuthService` gRPC service definition
|
|
|
|
### 3. gRPC Server Implementation (`services/auth/internal/api/server.go`)
|
|
- gRPC server implementation
|
|
- Handler for Login, RefreshToken, ValidateToken
|
|
- Integration with Auth Service business logic
|
|
|
|
### 4. Auth Service Implementation (`services/auth/internal/service/auth_service.go`)
|
|
- JWT token generation (access tokens: 15 min, refresh tokens: 7 days)
|
|
- Token signature verification (HMAC or RSA)
|
|
- Token expiration validation
|
|
- Claims extraction and validation
|
|
- Uses `IdentityServiceClient` for credential validation
|
|
|
|
### 5. Database Connection and Schema (`services/auth/ent/schema/`)
|
|
- Auth Service database connection (schema: `auth`)
|
|
- Refresh token storage schema (if storing refresh tokens in DB)
|
|
- Migration support
|
|
- Per-service connection pool
|
|
|
|
### 6. Service Client Integration
|
|
- Uses `IdentityServiceClient` to validate user credentials
|
|
- Uses `AuditServiceClient` to log authentication events
|
|
- Service discovery via Consul
|
|
|
|
### 7. Service Registration
|
|
- Register with Consul on startup
|
|
- Health check endpoint for Consul
|
|
- Service metadata (name: `auth-service`, port: 8081)
|
|
- Deregister on shutdown
|
|
|
|
## Implementation Steps
|
|
|
|
1. **Create Service Entry Point**
|
|
- Create `cmd/auth-service/main.go`
|
|
- Bootstrap with core kernel (config, logger, DI, health, metrics)
|
|
- Create database connection (auth schema)
|
|
- Register with Consul service registry
|
|
- Start gRPC server
|
|
|
|
2. **Define gRPC Service**
|
|
- Create `api/proto/auth.proto`
|
|
- Define Login, RefreshToken, ValidateToken RPCs
|
|
- Generate Go code from proto
|
|
|
|
3. **Implement Auth Service**
|
|
- Create `services/auth/internal/service/auth_service.go`
|
|
- Implement JWT token generation/validation
|
|
- Integrate with IdentityServiceClient for credential validation
|
|
- Integrate with AuditServiceClient for logging
|
|
|
|
4. **Implement gRPC Server**
|
|
- Create `services/auth/internal/api/server.go`
|
|
- Implement gRPC handlers
|
|
- Wire up service logic
|
|
|
|
5. **Database Setup**
|
|
- Create `services/auth/ent/schema/` if storing refresh tokens
|
|
- Set up migrations
|
|
- Configure per-service connection pool
|
|
|
|
6. **Service Registration**
|
|
- Register with Consul on startup
|
|
- Set up health check endpoint
|
|
- Handle graceful shutdown
|
|
|
|
## Acceptance Criteria
|
|
- [x] Auth Service is independently deployable
|
|
- [x] Service entry point exists at `cmd/auth-service/main.go`
|
|
- [x] Service registers with Consul on startup
|
|
- [x] gRPC server starts on configured port (8081)
|
|
- [x] Login RPC validates credentials via IdentityServiceClient
|
|
- [x] Login RPC returns access and refresh tokens
|
|
- [x] RefreshToken RPC issues new access tokens
|
|
- [x] ValidateToken RPC validates token signatures and expiration
|
|
- [x] Service has its own database connection (auth schema)
|
|
- [x] Service uses AuditServiceClient for logging
|
|
- [x] Service can be discovered by API Gateway via Consul
|
|
- [x] Health check endpoint works for Consul
|
|
|
|
## Related ADRs
|
|
- [ADR-0017: JWT Token Strategy](../../adr/0017-jwt-token-strategy.md)
|
|
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
|
|
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
|
|
|
|
## Implementation Notes
|
|
- Use JWT v5 library
|
|
- Support both HMAC and RSA signing
|
|
- Token secrets should be configurable
|
|
- Consider token blacklisting for logout (future enhancement)
|
|
- Refresh tokens should be stored securely (database or cache)
|
|
|
|
## Testing
|
|
```bash
|
|
# Test Auth Service
|
|
go test ./services/auth/...
|
|
|
|
# Test service startup
|
|
go run cmd/auth-service/main.go
|
|
|
|
# Test gRPC service (via grpcurl or client)
|
|
grpcurl -plaintext localhost:8081 list
|
|
grpcurl -plaintext -d '{"email":"user@example.com","password":"password"}' \
|
|
localhost:8081 auth.AuthService/Login
|
|
|
|
# Test service discovery
|
|
# Verify service is registered in Consul
|
|
consul catalog services
|
|
consul catalog service auth-service
|
|
```
|
|
|
|
## Files to Create/Modify
|
|
- `cmd/auth-service/main.go` - Service entry point
|
|
- `api/proto/auth.proto` - gRPC service definition
|
|
- `services/auth/internal/api/server.go` - gRPC server implementation
|
|
- `services/auth/internal/service/auth_service.go` - Auth service logic
|
|
- `services/auth/ent/schema/` - Database schema (if storing refresh tokens)
|
|
- `config/default.yaml` - Add auth service configuration
|
|
|