Improve the frontend 4
This commit is contained in:
Urtzi Alfaro
363
docs/ROLES_AND_PERMISSIONS_SYSTEM.md
Normal file
363
docs/ROLES_AND_PERMISSIONS_SYSTEM.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# Roles and Permissions System
|
||||
|
||||
## Overview
|
||||
|
||||
The Bakery IA platform implements a **dual role system** that provides fine-grained access control across both platform-wide and organization-specific operations.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Two Distinct Role Systems
|
||||
|
||||
#### 1. Global User Roles (Auth Service)
|
||||
|
||||
**Purpose:** System-wide permissions across the entire platform
|
||||
**Service:** Auth Service
|
||||
**Storage:** `User` model
|
||||
**Scope:** Cross-tenant, platform-level access control
|
||||
|
||||
**Roles:**
|
||||
- `super_admin` - Full platform access, can perform any operation
|
||||
- `admin` - System administrator, platform management capabilities
|
||||
- `manager` - Mid-level management access
|
||||
- `user` - Basic authenticated user
|
||||
|
||||
**Use Cases:**
|
||||
- Platform administration
|
||||
- Cross-tenant operations
|
||||
- System-wide features
|
||||
- User management at platform level
|
||||
|
||||
#### 2. Tenant-Specific Roles (Tenant Service)
|
||||
|
||||
**Purpose:** Organization/tenant-level permissions
|
||||
**Service:** Tenant Service
|
||||
**Storage:** `TenantMember` model
|
||||
**Scope:** Per-tenant access control
|
||||
|
||||
**Roles:**
|
||||
- `owner` - Full control of the tenant, can transfer ownership, manage all aspects
|
||||
- `admin` - Tenant administrator, can manage team members and most operations
|
||||
- `member` - Standard team member, regular operational access
|
||||
- `viewer` - Read-only observer, view-only access to tenant data
|
||||
|
||||
**Use Cases:**
|
||||
- Team management
|
||||
- Organization-specific operations
|
||||
- Resource access within a tenant
|
||||
- Most application features
|
||||
|
||||
## Role Mapping
|
||||
|
||||
When users are created through tenant management (pilot phase), tenant roles are automatically mapped to appropriate global roles:
|
||||
|
||||
```
|
||||
Tenant Role → Global Role │ Rationale
|
||||
─────────────────────────────────────────────────
|
||||
admin → admin │ Administrative access
|
||||
member → manager │ Management-level access
|
||||
viewer → user │ Basic user access
|
||||
owner → (no mapping) │ Owner is tenant-specific only
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- Frontend: `frontend/src/types/roles.ts`
|
||||
- Backend: `services/tenant/app/api/tenant_members.py` (lines 68-76)
|
||||
|
||||
## Permission Checking
|
||||
|
||||
### Unified Permission System
|
||||
|
||||
Location: `frontend/src/utils/permissions.ts`
|
||||
|
||||
The unified permission system provides centralized functions for checking permissions:
|
||||
|
||||
#### Functions
|
||||
|
||||
1. **`checkGlobalPermission(user, options)`**
|
||||
- Check platform-wide permissions
|
||||
- Used for: System settings, platform admin features
|
||||
|
||||
2. **`checkTenantPermission(tenantAccess, options)`**
|
||||
- Check tenant-specific permissions
|
||||
- Used for: Team management, tenant resources
|
||||
|
||||
3. **`checkCombinedPermission(user, tenantAccess, options)`**
|
||||
- Check either global OR tenant permissions
|
||||
- Used for: Mixed access scenarios
|
||||
|
||||
4. **Helper Functions:**
|
||||
- `canManageTeam()` - Check team management permission
|
||||
- `isTenantOwner()` - Check if user is tenant owner
|
||||
- `canPerformAdminActions()` - Check admin permissions
|
||||
- `getEffectivePermissions()` - Get all permission flags
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```typescript
|
||||
// Check if user can manage platform users (global only)
|
||||
checkGlobalPermission(user, { requiredRole: 'admin' })
|
||||
|
||||
// Check if user can manage tenant team (tenant only)
|
||||
checkTenantPermission(tenantAccess, { requiredRole: 'owner' })
|
||||
|
||||
// Check if user can access a feature (either global admin OR tenant owner)
|
||||
checkCombinedPermission(user, tenantAccess, {
|
||||
globalRoles: ['admin', 'super_admin'],
|
||||
tenantRoles: ['owner']
|
||||
})
|
||||
```
|
||||
|
||||
## Route Protection
|
||||
|
||||
### Protected Routes
|
||||
|
||||
Location: `frontend/src/router/ProtectedRoute.tsx`
|
||||
|
||||
All protected routes now use the unified permission system:
|
||||
|
||||
```typescript
|
||||
// Admin Route: Global admin OR tenant owner/admin
|
||||
<AdminRoute>
|
||||
<Component />
|
||||
</AdminRoute>
|
||||
|
||||
// Manager Route: Global admin/manager OR tenant admin/owner/member
|
||||
<ManagerRoute>
|
||||
<Component />
|
||||
</ManagerRoute>
|
||||
|
||||
// Owner Route: Super admin OR tenant owner only
|
||||
<OwnerRoute>
|
||||
<Component />
|
||||
</OwnerRoute>
|
||||
```
|
||||
|
||||
## Team Management
|
||||
|
||||
### Core Features
|
||||
|
||||
#### 1. Add Team Members
|
||||
- **Permission Required:** Tenant Owner or Admin
|
||||
- **Options:**
|
||||
- Add existing user to tenant
|
||||
- Create new user and add to tenant (pilot phase)
|
||||
- **Subscription Limits:** Checked before adding members
|
||||
|
||||
#### 2. Update Member Roles
|
||||
- **Permission Required:** Context-dependent
|
||||
- Viewer → Member: Any admin
|
||||
- Member → Admin: Owner only
|
||||
- Admin → Member: Owner only
|
||||
- **Restrictions:** Cannot change Owner role via standard UI
|
||||
|
||||
#### 3. Remove Members
|
||||
- **Permission Required:** Owner only
|
||||
- **Restrictions:** Cannot remove the Owner
|
||||
|
||||
#### 4. Transfer Ownership
|
||||
- **Permission Required:** Owner only
|
||||
- **Requirements:**
|
||||
- New owner must be an existing Admin
|
||||
- Two-step confirmation process
|
||||
- Irreversible operation
|
||||
- **Changes:**
|
||||
- New user becomes Owner
|
||||
- Previous owner becomes Admin
|
||||
|
||||
### Team Page
|
||||
|
||||
Location: `frontend/src/pages/app/settings/team/TeamPage.tsx`
|
||||
|
||||
**Features:**
|
||||
- Team member list with role indicators
|
||||
- Filter by role
|
||||
- Search by name/email
|
||||
- Member details modal
|
||||
- Activity tracking
|
||||
- Transfer ownership modal
|
||||
- Error recovery for missing user data
|
||||
|
||||
**Security:**
|
||||
- Removed insecure owner_id fallback
|
||||
- Proper access validation through backend
|
||||
- Permission-based UI rendering
|
||||
|
||||
## Backend Implementation
|
||||
|
||||
### Tenant Member Endpoints
|
||||
|
||||
Location: `services/tenant/app/api/tenant_members.py`
|
||||
|
||||
**Endpoints:**
|
||||
1. `POST /tenants/{tenant_id}/members/with-user` - Add member with optional user creation
|
||||
2. `POST /tenants/{tenant_id}/members` - Add existing user
|
||||
3. `GET /tenants/{tenant_id}/members` - List members
|
||||
4. `PUT /tenants/{tenant_id}/members/{user_id}/role` - Update role
|
||||
5. `DELETE /tenants/{tenant_id}/members/{user_id}` - Remove member
|
||||
6. `POST /tenants/{tenant_id}/transfer-ownership` - Transfer ownership
|
||||
7. `GET /tenants/{tenant_id}/admins` - Get tenant admins
|
||||
8. `DELETE /tenants/user/{user_id}/memberships` - Delete user memberships (internal)
|
||||
|
||||
### Member Enrichment
|
||||
|
||||
The backend enriches tenant members with user data from the Auth service:
|
||||
- User full name
|
||||
- Email
|
||||
- Phone
|
||||
- Last login
|
||||
- Language/timezone preferences
|
||||
|
||||
**Error Handling:**
|
||||
- Graceful degradation if Auth service unavailable
|
||||
- Fallback to user_id if enrichment fails
|
||||
- Frontend displays warning for incomplete data
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Use Which Permission Check
|
||||
|
||||
1. **Global Permission Check:**
|
||||
- Platform administration
|
||||
- Cross-tenant operations
|
||||
- System-wide features
|
||||
- User management at platform level
|
||||
|
||||
2. **Tenant Permission Check:**
|
||||
- Team management
|
||||
- Organization-specific resources
|
||||
- Tenant settings
|
||||
- Most application features
|
||||
|
||||
3. **Combined Permission Check:**
|
||||
- Features requiring elevated access
|
||||
- Admin-only operations that can be done by either global or tenant admins
|
||||
- Owner-specific operations with super_admin override
|
||||
|
||||
### Security Considerations
|
||||
|
||||
1. **Never use client-side owner_id comparison as fallback**
|
||||
- Always validate through backend
|
||||
- Use proper access endpoints
|
||||
|
||||
2. **Always validate permissions on the backend**
|
||||
- Frontend checks are for UX only
|
||||
- Backend is source of truth
|
||||
|
||||
3. **Use unified permission system**
|
||||
- Consistent permission checking
|
||||
- Clear documentation
|
||||
- Type-safe
|
||||
|
||||
4. **Audit critical operations**
|
||||
- Log role changes
|
||||
- Track ownership transfers
|
||||
- Monitor member additions/removals
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
|
||||
1. **Role Change History**
|
||||
- Audit trail for role changes
|
||||
- Display who changed roles and when
|
||||
- Integrated into member details modal
|
||||
|
||||
2. **Fine-grained Permissions**
|
||||
- Custom permission sets
|
||||
- Permission groups
|
||||
- Resource-level permissions
|
||||
|
||||
3. **Invitation Flow**
|
||||
- Replace direct user creation
|
||||
- Email-based invitations
|
||||
- Invitation expiration
|
||||
|
||||
4. **Member Status Management**
|
||||
- Activate/deactivate members
|
||||
- Suspend access temporarily
|
||||
- Bulk status updates
|
||||
|
||||
5. **Advanced Team Features**
|
||||
- Sub-teams/departments
|
||||
- Role templates
|
||||
- Bulk role assignments
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "Permission Denied" Errors
|
||||
- **Cause:** User lacks required role or permission
|
||||
- **Solution:** Verify user's tenant membership and role
|
||||
- **Check:** `currentTenantAccess` in tenant store
|
||||
|
||||
#### Missing User Data in Team List
|
||||
- **Cause:** Auth service enrichment failed
|
||||
- **Solution:** Check Auth service connectivity
|
||||
- **Workaround:** Frontend displays warning and fallback data
|
||||
|
||||
#### Cannot Transfer Ownership
|
||||
- **Cause:** No eligible admins
|
||||
- **Solution:** Promote a member to admin first
|
||||
- **Requirement:** New owner must be an existing admin
|
||||
|
||||
#### Access Validation Stuck Loading
|
||||
- **Cause:** Tenant access endpoint not responding
|
||||
- **Solution:** Reload page or check backend logs
|
||||
- **Prevention:** Backend health monitoring
|
||||
|
||||
## API Reference
|
||||
|
||||
### Frontend
|
||||
|
||||
**Permission Functions:** `frontend/src/utils/permissions.ts`
|
||||
**Protected Routes:** `frontend/src/router/ProtectedRoute.tsx`
|
||||
**Role Types:** `frontend/src/types/roles.ts`
|
||||
**Team Management:** `frontend/src/pages/app/settings/team/TeamPage.tsx`
|
||||
**Transfer Modal:** `frontend/src/components/domain/team/TransferOwnershipModal.tsx`
|
||||
|
||||
### Backend
|
||||
|
||||
**Tenant Members API:** `services/tenant/app/api/tenant_members.py`
|
||||
**Tenant Models:** `services/tenant/app/models/tenants.py`
|
||||
**Tenant Service:** `services/tenant/app/services/tenant_service.py`
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### From Single Role System
|
||||
|
||||
If migrating from a single role system:
|
||||
|
||||
1. **Audit existing roles**
|
||||
- Map old roles to new structure
|
||||
- Identify tenant vs global roles
|
||||
|
||||
2. **Update permission checks**
|
||||
- Replace old checks with unified system
|
||||
- Test all protected routes
|
||||
|
||||
3. **Migrate user data**
|
||||
- Set appropriate global roles
|
||||
- Create tenant memberships
|
||||
- Ensure owners are properly set
|
||||
|
||||
4. **Update frontend components**
|
||||
- Use new permission functions
|
||||
- Update route guards
|
||||
- Test all scenarios
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about the roles and permissions system:
|
||||
|
||||
1. **Check this documentation**
|
||||
2. **Review code comments** in permission utilities
|
||||
3. **Check backend logs** for permission errors
|
||||
4. **Verify tenant membership** in database
|
||||
5. **Test with different user roles** to isolate issues
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-10-31
|
||||
**Version:** 1.0.0
|
||||
**Status:** ✅ Production Ready
|
||||
Reference in New Issue
Block a user