# CorradAF - Role-Based Access Control (RBAC) System

A comprehensive RBAC system built with Nuxt 3, integrated with Authentik for enterprise-grade user management and authentication.

## 🚀 Overview

CorradAF provides a complete Role-Based Access Control system that sits on top of Authentik, offering simplified management for multi-application environments with granular permissions at the menu and component level.

## 🏗️ Architecture

### RBAC Hierarchy: Group → Roles → Users
```
Organization/Tenant
├── Groups (Departments/Teams - synced with Authentik)
│   ├── Roles (Job Functions with app-specific permissions)
│   │   ├── Menu Permissions (key-unique based)
│   │   ├── Component Permissions (key-unique based)
│   │   └── Feature Permissions (key-unique based)
│   └── Users (Inherited from Group + Role combinations)
└── Applications (Multi-app support)
```

## ✨ Core Features

### 👥 User Management
- **Complete User Lifecycle**: Create, update, deactivate users with full profile management
- **Bulk Operations**: CSV import/export for mass user operations
- **Authentik Integration**: Bidirectional sync with Authentik SSO system
- **Advanced Search & Filtering**: Built-in table filtering with sorting and pagination
- **Profile Management**: Employee ID, department, job titles, contact information
- **Password Management**: Secure password generation and change enforcement

### 🏢 Group Management  
- **Department Structure**: Organize users into logical groups (IT, HR, Finance, etc.)
- **Hierarchical Groups**: Support for parent-child group relationships
- **Authentik Sync**: Real-time synchronization with Authentik groups
- **Custom Attributes**: Flexible metadata for groups (cost center, location, manager)
- **Member Management**: Easy addition/removal of users from groups

### 🛡️ Role Management
- **Application-Specific Roles**: Roles scoped to individual applications
- **Permission Templates**: Pre-configured role templates (Admin, Manager, Editor, Viewer)
- **Custom Role Creation**: Granular permission assignment for specific business needs
- **Role Inheritance**: Users inherit permissions from group + role combinations
- **Global vs Local Roles**: Support for system-wide and application-specific roles

### 🏢 Application Management ✅ **NEW**
- **Complete Application Lifecycle**: Create, configure, and manage applications with Authentik integration
- **Multiple Provider Support**: OAuth2/OIDC, SAML, Proxy, and LDAP provider configurations
- **Authentik Synchronization**: Automatic application and provider creation in Authentik
- **Access Control Integration**: Group and policy-based application access control
- **Real-time Monitoring**: Sync status tracking and health monitoring
- **Bulk Operations**: Sync multiple applications to Authentik simultaneously
- **Smart Configuration**: Auto-generation of OAuth2 credentials and application slugs
- **Provider Templates**: Pre-configured settings for common authentication protocols

### 🔐 Granular Permissions System
- **Key-Unique Based**: Each permission tied to a specific unique key
- **Three Permission Levels**:
  - **Menu Permissions**: Control navigation visibility (`menu.users`, `menu.reports`)
  - **Component Permissions**: Control UI element access (`component.user.edit_button`)
  - **Feature Permissions**: Control functionality access (`feature.export.data`)
- **Action-Based**: View, Create, Edit, Delete, Approve actions per resource
- **Real-Time Enforcement**: Dynamic show/hide based on user permissions

### 📊 Advanced Data Tables (RsTable)
- **Built-in Search**: Global search across all columns
- **Column Filtering**: Hide/show specific columns via filter dropdown
- **Sorting**: Click headers to sort data ascending/descending
- **Pagination**: Configurable page sizes with navigation controls
- **Responsive Design**: Auto-collapse to mobile-friendly card view
- **Export Options**: Built-in data export capabilities

### 🔗 Authentik Integration
- **SSO Authentication**: Complete OAuth/OIDC integration
- **User Synchronization**: Bidirectional sync of users and groups
- **Group Management**: Automatic creation and sync of Authentik groups
- **Permission Mapping**: Custom permission translation to Authentik policies
- **Tenant Support**: Multi-tenant organization support

### 🎛️ RBAC Management Interface
- **Permission Matrix**: Visual grid showing role-resource-action combinations
- **Bulk Assignment**: Assign multiple permissions or roles simultaneously
- **Role Templates**: Quick application of common permission sets
- **Audit Trail**: Complete logging of permission changes and user actions
- **Application Scope**: Manage permissions across multiple applications

## 🛠️ Technical Stack

- **Frontend**: Nuxt 3, Vue 3, TailwindCSS
- **UI Components**: Custom RS component library (RsCard, RsButton, RsTable, RsBadge)
- **Forms**: FormKit for consistent form handling
- **State Management**: Pinia stores
- **Authentication**: Authentik SSO integration
- **Database**: Prisma ORM (PostgreSQL/MySQL support)
- **Icons**: Phosphor Icons
- **Styling**: TailwindCSS with dark/light mode support

## 📱 User Interface Features

### Navigation & Layout
- **Breadcrumb Navigation**: Hierarchical navigation with parent-child relationships
- **Responsive Sidebar**: Clean navigation organized by functional areas
- **Stats Cards**: Real-time metrics for users, groups, roles, and permissions
- **Search Integration**: Global search across all data tables

### Form Management
- **Validation**: Real-time form validation with FormKit
- **Auto-completion**: Smart dropdowns for groups, roles, and departments
- **File Uploads**: CSV upload for bulk operations
- **Password Strength**: Visual password strength indicators
- **Multi-step Forms**: Progressive form filling for complex operations

### Data Visualization
- **Advanced Tables**: Sortable, filterable, paginated data tables
- **Status Indicators**: Visual badges for active/inactive states
- **Avatar System**: Generated initials for users, groups, and roles
- **Progress Tracking**: Visual progress for bulk operations
- **Audit Logs**: Timestamped activity feeds

## 🚦 Getting Started

### Prerequisites
- Node.js 18+ 
- Yarn or npm
- Authentik instance (for SSO integration)
- PostgreSQL or MySQL database

### Installation

1. **Clone the repository**
```bash
git clone <repository-url>
cd corrad-rbac
```

2. **Install dependencies**
```bash
yarn install
# or
npm install
```

3. **Environment Setup**
```bash
cp .env.example .env
# Configure your environment variables
```

4. **Database Setup**
```bash
npx prisma migrate deploy
npx prisma generate
```

5. **Development Server**
```bash
npm run dev
# Server starts on http://localhost:3000
```

### Production Deployment

```bash
# Build for production
npm run build

# Preview production build
npm run preview

# Start production server
npm run start
```

## 📁 Project Structure

```
corrad-rbac/
├── components/           # Reusable UI components
│   ├── Rs*/             # Custom component library
│   └── layouts/         # Layout components
├── pages/               # Application pages
│   ├── users/           # User management pages
│   ├── groups/          # Group management pages
│   ├── roles/           # Role management pages
│   ├── applications/    # Application management pages ✅ NEW
│   └── rbac-permission/ # RBAC management interface
├── stores/              # Pinia state management
├── middleware/          # Route protection
├── server/              # API endpoints
├── docs/                # Documentation
└── prisma/              # Database schema
```

## 🔧 Configuration

### Authentik Integration
1. Configure Authentik provider in your environment
2. Set up OAuth application in Authentik
3. Configure callback URLs and scopes
4. Enable user and group synchronization

### Permission System
1. Define application resources in the database
2. Create permission templates for common roles
3. Set up default group-role assignments
4. Configure automatic permission inheritance

## 📚 Documentation

### **📋 Main Documentation**
- **[README.md](README.md)** - Complete project overview and setup guide
- **[Features Overview](docs/FEATURES_OVERVIEW.md)** - Comprehensive list of all implemented features
- **[Implementation Status](docs/IMPLEMENTATION_STATUS.md)** - Current development status and metrics

### **🔧 Technical Documentation**  
- **[RBAC & Authentik Analysis](docs/RBAC_AUTHENTIK_ANALYSIS.md)** - Detailed technical analysis and architecture
- **[Business Justification](docs/BUSINESS_JUSTIFICATION_RBAC.md)** - Why build RBAC on top of Authentik
- **[Authentik Integration](docs/AUTHENTIK_INTEGRATION_IMPLEMENTATION.md)** - Integration implementation guide
- **[Application Management](docs/APPLICATION_MANAGEMENT.md)** - Complete application management documentation ✅ **NEW**
- **[Site Settings](docs/SITE_SETTINGS.md)** - Configuration options and settings

### **📊 Quick Reference**
- **Frontend Implementation**: 100% Complete ✅
- **Pages Implemented**: 10/10 (Users, Groups, Roles, Applications, RBAC Management) ✅  
- **UI Components**: 6/6 (RsTable, RsCard, RsButton, RsBadge, FormKit, Breadcrumb) ✅
- **User Experience**: Modern, responsive, accessible interface ✅
- **Application Management**: Complete with Authentik integration ✅ **NEW**
- **Next Phase**: Backend API and authentication system ⏳

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For support and questions:
- Check the documentation in the `/docs` folder
- Create an issue for bugs or feature requests
- Review existing issues for common problems

---

**Built with ❤️ using Nuxt 3 and modern web technologies**