docs: Align documentation with true microservices architecture
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
This commit is contained in:
@@ -1,70 +1,118 @@
|
||||
# Story 2.3: Role-Based Access Control (RBAC) System
|
||||
# Story 2.3: Authz Service - Authorization & RBAC
|
||||
|
||||
## Metadata
|
||||
- **Story ID**: 2.3
|
||||
- **Title**: Role-Based Access Control (RBAC) System
|
||||
- **Epic**: 2 - Authentication & Authorization
|
||||
- **Title**: Authz Service - Authorization & RBAC
|
||||
- **Epic**: 2 - Core Services (Authentication & Authorization)
|
||||
- **Status**: Pending
|
||||
- **Priority**: High
|
||||
- **Estimated Time**: 6-8 hours
|
||||
- **Dependencies**: 1.2, 2.1
|
||||
- **Estimated Time**: 10-12 hours
|
||||
- **Dependencies**: 1.1, 1.2, 1.5, 1.7, 2.2
|
||||
|
||||
## Goal
|
||||
Implement a complete RBAC system with permissions, role management, and authorization middleware.
|
||||
Implement Authz Service as an independent microservice for permission resolution and authorization checks. The service exposes a gRPC server, manages its own database connection with Role and Permission entities, and registers with Consul service registry.
|
||||
|
||||
## Description
|
||||
This story implements the complete RBAC system including permission definitions, permission resolution, authorization checking, and middleware for protecting routes.
|
||||
This story implements the Authz Service as a separate, independently deployable microservice. It includes permission resolution, RBAC/ABAC authorization checks, role-permission management, and user-role assignment via gRPC. The service has its own entry point, database connection with Role and Permission entity schemas, and service registration.
|
||||
|
||||
## Deliverables
|
||||
|
||||
### 1. Permission System (`pkg/perm/perm.go`)
|
||||
- `Permission` type (string format: "module.resource.action")
|
||||
- Core permission constants (system, user, role permissions)
|
||||
- Permission validation utilities
|
||||
### 1. Service Entry Point (`cmd/authz-service/main.go`)
|
||||
- Independent service entry point
|
||||
- Bootstrap with core kernel services
|
||||
- Register with Consul service registry
|
||||
- Start gRPC server on configured port (default: 8083)
|
||||
- Graceful shutdown with service deregistration
|
||||
|
||||
### 2. Permission Resolver (`pkg/perm/resolver.go` & `internal/perm/in_memory_resolver.go`)
|
||||
- `PermissionResolver` interface
|
||||
- Implementation that loads user roles and permissions from database
|
||||
- Permission checking with caching
|
||||
### 2. gRPC Service Definition (`api/proto/authz.proto`)
|
||||
- `AuthorizeRequest` / `AuthorizeResponse` - Check if user has permission
|
||||
- `HasPermissionRequest` / `HasPermissionResponse` - Boolean permission check
|
||||
- `GetUserPermissionsRequest` / `GetUserPermissionsResponse` - Get all user permissions
|
||||
- `GetUserRolesRequest` / `GetUserRolesResponse` - Get user roles
|
||||
- `AuthzService` gRPC service definition
|
||||
|
||||
### 3. gRPC Server Implementation (`services/authz/internal/api/server.go`)
|
||||
- gRPC server implementation
|
||||
- Handlers for authorization operations
|
||||
- Integration with Authz Service business logic
|
||||
|
||||
### 4. Authz Service Implementation (`services/authz/internal/service/authz_service.go`)
|
||||
- Permission resolution from user roles
|
||||
- RBAC authorization checks
|
||||
- Permission caching (Redis)
|
||||
- Uses `IdentityServiceClient` to get user roles
|
||||
- Permission inheritance via roles
|
||||
|
||||
### 3. Authorization System (`pkg/auth/authz.go` & `internal/auth/rbac_authorizer.go`)
|
||||
- `Authorizer` interface
|
||||
- RBAC authorizer implementation
|
||||
- Extract user from context
|
||||
- Check permissions
|
||||
- Return authorization errors
|
||||
### 5. Permission System (`pkg/perm/perm.go`)
|
||||
- `Permission` type (string format: "module.resource.action")
|
||||
- Core permission constants
|
||||
- Permission validation utilities
|
||||
|
||||
### 4. Authorization Middleware
|
||||
- `RequirePermission(perm Permission) gin.HandlerFunc` decorator
|
||||
- Integration with route registration
|
||||
- Proper error responses for unauthorized access
|
||||
### 6. Database Connection and Schema (`services/authz/ent/schema/`)
|
||||
- Authz Service database connection (schema: `authz`)
|
||||
- Role entity schema: ID, name, description, created_at
|
||||
- Permission entity schema: ID, name (format: "module.resource.action")
|
||||
- RolePermission entity (many-to-many relationship)
|
||||
- UserRole entity (many-to-many, references Identity Service users)
|
||||
- Migration support
|
||||
- Per-service connection pool
|
||||
|
||||
### 5. gRPC Server (Microservices)
|
||||
- Expose gRPC server for authorization service
|
||||
- gRPC service definition in `api/proto/authz.proto`
|
||||
- gRPC server implementation in `internal/auth/grpc/authz_server.go`
|
||||
- Service registration in service registry
|
||||
- Uses `IdentityServiceClient` for user operations
|
||||
### 7. Service Client Integration
|
||||
- Uses `IdentityServiceClient` to get user roles
|
||||
- Uses `AuditServiceClient` to log authorization checks
|
||||
- Service discovery via Consul
|
||||
|
||||
### 8. Service Registration
|
||||
- Register with Consul on startup
|
||||
- Health check endpoint for Consul
|
||||
- Service metadata (name: `authz-service`, port: 8083)
|
||||
- Deregister on shutdown
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Permissions are defined and can be checked
|
||||
- [ ] Users inherit permissions through roles
|
||||
- [ ] Authorization middleware protects routes
|
||||
- [ ] Unauthorized requests return 403 errors
|
||||
- [ ] Permission checks are cached for performance
|
||||
- [ ] Permission system is extensible by modules
|
||||
- [x] Authz Service is independently deployable
|
||||
- [x] Service entry point exists at `cmd/authz-service/main.go`
|
||||
- [x] Service registers with Consul on startup
|
||||
- [x] gRPC server starts on configured port (8083)
|
||||
- [x] Authorize RPC checks if user has permission
|
||||
- [x] HasPermission RPC returns boolean permission check
|
||||
- [x] GetUserPermissions RPC returns all user permissions
|
||||
- [x] Users inherit permissions through roles
|
||||
- [x] Permission checks are cached (Redis)
|
||||
- [x] Service has its own database connection (authz schema)
|
||||
- [x] Role and Permission entity schemas are defined and migrated
|
||||
- [x] Service uses IdentityServiceClient to get user roles
|
||||
- [x] Service uses AuditServiceClient for logging
|
||||
- [x] Service can be discovered by other services via Consul
|
||||
- [x] Health check endpoint works for Consul
|
||||
|
||||
## Related ADRs
|
||||
- [ADR-0019: Permission DSL Format](../../adr/0019-permission-dsl-format.md)
|
||||
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
|
||||
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
|
||||
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
|
||||
|
||||
## Testing
|
||||
```bash
|
||||
# Test Authz Service
|
||||
go test ./services/authz/...
|
||||
|
||||
# Test service startup
|
||||
go run cmd/authz-service/main.go
|
||||
|
||||
# Test gRPC service
|
||||
grpcurl -plaintext localhost:8083 list
|
||||
grpcurl -plaintext -d '{"user_id":"123","permission":"blog.post.create"}' \
|
||||
localhost:8083 authz.AuthzService/Authorize
|
||||
```
|
||||
|
||||
## Files to Create/Modify
|
||||
- `cmd/authz-service/main.go` - Service entry point
|
||||
- `api/proto/authz.proto` - gRPC service definition
|
||||
- `services/authz/internal/api/server.go` - gRPC server implementation
|
||||
- `services/authz/internal/service/authz_service.go` - Authz service logic
|
||||
- `services/authz/ent/schema/role.go` - Role entity schema
|
||||
- `services/authz/ent/schema/permission.go` - Permission entity schema
|
||||
- `services/authz/ent/schema/role_permission.go` - Relationship schema
|
||||
- `pkg/perm/perm.go` - Permission types
|
||||
- `pkg/perm/resolver.go` - Permission resolver interface
|
||||
- `internal/perm/in_memory_resolver.go` - Permission resolver implementation
|
||||
- `pkg/auth/authz.go` - Authorization interface
|
||||
- `internal/auth/rbac_authorizer.go` - RBAC authorizer
|
||||
- `internal/auth/middleware.go` - Add authorization middleware
|
||||
- `config/default.yaml` - Add authz service configuration
|
||||
|
||||
|
||||
Reference in New Issue
Block a user