goplt/docs/content/stories/epic2/2.3-rbac-system.md

Story 2.3: Authz Service - Authorization & RBAC

Metadata

• Story ID: 2.3
• Title: Authz Service - Authorization & RBAC
• Epic: 2 - Core Services (Authentication & Authorization)
• Status: Pending
• Priority: High
• Estimated Time: 10-12 hours
• Dependencies: 1.1, 1.2, 1.5, 1.7, 2.2

Goal

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 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. 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. 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

5. Permission System (pkg/perm/perm.go)

• Permission type (string format: "module.resource.action")
• Core permission constants
• Permission validation utilities

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

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

• Authz Service is independently deployable
• Service entry point exists at cmd/authz-service/main.go
• Service registers with Consul on startup
• gRPC server starts on configured port (8083)
• Authorize RPC checks if user has permission
• HasPermission RPC returns boolean permission check
• GetUserPermissions RPC returns all user permissions
• Users inherit permissions through roles
• Permission checks are cached (Redis)
• Service has its own database connection (authz schema)
• Role and Permission entity schemas are defined and migrated
• Service uses IdentityServiceClient to get user roles
• Service uses AuditServiceClient for logging
• Service can be discovered by other services via Consul
• Health check endpoint works for Consul

Related ADRs

• ADR-0019: Permission DSL Format
• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy
• ADR-0033: Service Discovery Implementation

Testing

# 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
• config/default.yaml - Add authz service configuration