AuthorizeIt

A comprehensive authorization management system designed for microservices architecture, providing robust user management, role-based access control, and hierarchical claims-based permissions.

About AuthorizeIt

AuthorizeIt is a microservice that centralizes authorization logic for distributed systems. It provides a clean separation between authentication (handled by other services) and authorization (handled by AuthorizeIt), making it easy to integrate into existing microservice architectures.

Key Features

• User Management: Create, update, and manage users across your microservice ecosystem
• Role-Based Access Control (RBAC): Flexible role system with dynamic role assignment
• Hierarchical Claims: Tree-structured permission system allowing fine-grained access control
• Dual API Design:
  • User Interface API for frontend applications and administrative tools
  • System Integration API for service-to-service communication
• Real-time Authorization: Fast permission checking for real-time authorization decisions
• Dynamic Claim Sources: Configurable external claim sources from other microservices
• Reactive Architecture: Built for high performance with reactive programming patterns

Technology Stack

Backend (AuthorizeItService)

• Framework: Spring Boot 3.5.0 with Kotlin 1.9.25
• Database: PostgreSQL 17 with R2DBC (reactive database access)
• Caching: Redis 8 for performance optimization
• API: gRPC with Protocol Buffers for efficient service communication
• Migration: Flyway for database schema management
• Architecture: Clean Architecture with Domain-Driven Design
• Build: Gradle 8.14 with Java 17

Frontend (AuthorizeIt Frontend)

• Framework: Next.js 15.3.3 with React 19
• Language: TypeScript 5
• Styling: Tailwind CSS 4 with Radix UI components
• State Management: MobX 6.13.7 for reactive state management
• API Communication: gRPC client with auto-generated TypeScript types
• UI Components: Lucide React icons, custom component library

Infrastructure

• Database: PostgreSQL 17
• Cache: Redis 8
• Containerization: Docker with Docker Compose for local development
• Protocol: gRPC with Protocol Buffers v3

Architecture Overview

AuthorizeIt follows a multi-layered architecture designed for scalability and maintainability:

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                       │
│              User Management Interface                      │
└─────────────────────────┬───────────────────────────────────┘
                          │ gRPC (User Interface API)
┌─────────────────────────▼──────────────────────────────────┐
│                AuthorizeItService                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Transport Layer                        │   │
│  │    • User Interface gRPC Services                   │   │
│  │    • System Integration gRPC Services               │   │
│  └─────────────────────┬───────────────────────────────┘   │
│  ┌─────────────────────▼───────────────────────────────┐   │
│  │             Application Layer                       │   │
│  │    • Use Cases (Create User, Assign Role, etc.)     │   │
│  └─────────────────────┬───────────────────────────────┘   │
│  ┌─────────────────────▼───────────────────────────────┐   │
│  │              Domain Layer                           │   │
│  │    • Entities: User, Role, Claim                    │   │
│  │    • Business Logic & Rules                         │   │
│  └─────────────────────┬───────────────────────────────┘   │
│  ┌─────────────────────▼───────────────────────────────┐   │
│  │           Infrastructure Layer                      │   │
│  │    • PostgreSQL with R2DBC                          │   │
│  │    • Redis Caching                                  │   │
│  │    • External Claim Sources                         │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────┬──────────────────────────────────┘
                          │ gRPC (System Integration API)
┌─────────────────────────▼──────────────────────────────────┐
│                  Other Microservices                       │
│         Authentication, Business Logic, etc.               │
└────────────────────────────────────────────────────────────┘

Communication Layer

• gRPC: High-performance RPC framework with Protocol Buffers
• Dual API Design:
  • User Interface API: Rich data models for frontend applications
  • System Integration API: Lightweight endpoints for service-to-service communication

Database Schema

• users: User profiles and metadata
• roles: Role definitions and configurations
• claims: Hierarchical permission structure with parent-child relationships
• user_roles: Many-to-many user-role assignments
• role_claims: Role-permission associations

Project Structure

AuthorizeIt/
├── apps/
│   ├── authorizeitfrontend/           # Next.js Frontend Application
│   │   ├── src/
│   │   │   ├── app/                   # App Router pages (users, roles, settings)
│   │   │   ├── components/            # Reusable UI components
│   │   │   ├── lib/                   # API services and utilities
│   │   │   └── generated/             # Auto-generated protobuf types
│   │   ├── protos/                    # Frontend protobuf definitions
│   │   └── package.json               # Frontend dependencies
│   │
│   └── AuthorizeItService/            # Kotlin Spring Boot Backend
│       ├── src/main/kotlin/zone/artify/authorizeitservice/
│       │   ├── application/           # Use cases and application services
│       │   ├── domain/                # Core business logic and entities
│       │   ├── infrastructure/        # Database, external services
│       │   └── transport/             # gRPC services and API endpoints
│       ├── src/main/proto/            # Backend protobuf definitions
│       ├── src/main/resources/        # Configuration and migrations
│       ├── build.gradle.kts           # Backend dependencies and build
│       └── docker-compose.yaml        # Local development infrastructure
│
└── README.md                          # This file

Getting Started

Prerequisites

• Java 17 JDK (for backend development)
• Node.js 20+ (for frontend development)
• Docker & Docker Compose (for local infrastructure)
• Git (for version control)

Quick Setup

1. Clone the repository

   git clone <repository-url>
   cd AuthorizeIt

2. Start the infrastructure

   cd apps/AuthorizeItService
   docker-compose up -d

   This starts PostgreSQL on port 5432 and Redis on port 6379.

3. Start the backend service

   # In apps/AuthorizeItService directory
   ./gradlew bootRun

   The service will run on localhost:8080 (HTTP) and localhost:9090 (gRPC).

4. Start the frontend application

   cd apps/authorizeitfrontend
   npm install
   npm run dev

   The frontend will be available at http://localhost:3000.

Development Environment Setup

Backend Development

cd apps/AuthorizeItService

# Run tests
./gradlew test

# Build the application
./gradlew build

# Run with custom configuration
SERVER_PORT=8081 ./gradlew bootRun

Frontend Development

cd apps/authorizeitfrontend

# Install dependencies
npm install

# Generate protobuf types
npm run generate-proto

# Start development server
npm run dev

# Build for production
npm run build

Environment Configuration

Backend Environment Variables

• SERVER_PORT: HTTP server port (default: 8080)
• SPRING_GRPC_SERVER_ADDRESS: gRPC server address (default: 0.0.0.0:9090)
• SPRING_R2DBC_URL: Database connection URL
• DATABASE_USERNAME: Database username (default: postgres)
• DATABASE_PASSWORD: Database password (default: postgres)
• SPRING_DATA_REDIS_HOST: Redis host (default: localhost)
• SPRING_DATA_REDIS_PORT: Redis port (default: 6379)

Frontend Environment Variables

• ROLE_SERVICE_ADDRESS: Backend gRPC address (default: localhost:9090)

Deployment

Docker Compose (Local Development)

The included docker-compose.yaml provides PostgreSQL and Redis for local development. This setup is not intended for production use.

cd apps/AuthorizeItService
docker-compose up -d

Production Deployment

For production deployments, consider:

• Separate database and cache infrastructure
• Container orchestration (Kubernetes, Docker Swarm)
• Load balancing for multiple service instances
• Monitoring and logging solutions
• Secure gRPC communication with TLS

Integration with Other Microservices

Authentication vs Authorization

AuthorizeIt handles authorization (what users can do) while other services handle authentication (who users are). This separation allows:

• Centralized permission management
• Consistent authorization across services
• Independent scaling of auth concerns
• Flexible authentication provider integration

API Integration Patterns

System Integration API

For service-to-service communication:

// Check if user has permission
rpc CheckUserClaimAuthorized(CheckUserClaimAuthorizedRequest) 
    returns (CheckUserClaimAuthorizedResponse);

// Create user from auth service
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);

User Interface API

For frontend applications:

// Get user with roles
rpc GetUserById(GetUserByIdRequest) returns (GetUserByIdResponse);

// Manage roles
rpc ListRoles(ListRolesRequest) returns (ListRolesResponse);
rpc CreateRole(CreateRoleRequest) returns (CreateRoleResponse);

Authorization Flow in Microservice Architecture

1. User Authentication: Handled by dedicated authentication service
2. Permission Check: Business services call AuthorizeIt's CheckUserClaimAuthorized
3. Response: AuthorizeIt returns authorization decision based on user's roles and claims
4. Action: Business service proceeds or denies based on authorization response

Dynamic Claim Sources

AuthorizeIt supports loading claims from external sources (other microservices) through configurable claim sources. The system automatically creates a config.json file on first startup, allowing integration with other services' permission endpoints.

API Versioning

All APIs are currently v1 with built-in support for future version evolution:

• Package-based versioning (e.g., userinterface.user.v1)
• Separate service implementations per version
• Protocol buffer backward compatibility
• Coexistence of multiple API versions