goplt/docs/content/stories/epic2/2.1-jwt-authentication.md

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

• Auth Service is independently deployable
• Service entry point exists at cmd/auth-service/main.go
• Service registers with Consul on startup
• gRPC server starts on configured port (8081)
• Login RPC validates credentials via IdentityServiceClient
• Login RPC returns access and refresh tokens
• RefreshToken RPC issues new access tokens
• ValidateToken RPC validates token signatures and expiration
• Service has its own database connection (auth schema)
• Service uses AuditServiceClient for logging
• Service can be discovered by API Gateway via Consul
• Health check endpoint works for Consul

Related ADRs

• ADR-0017: JWT Token Strategy
• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy

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

# 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