gateway/docs/rbac_admin_roles_and_options_api.md

# RBAC Admin Roles Management & Options API

## Overview

This document describes two new features added to support RBAC management:

1. **Options API**: Dynamic options endpoint for frontend select/multiselect fields
2. **Admin RBAC Roles Module**: Comprehensive role and role assignment management

---

## 1. Options API

### Purpose

The Options API provides dynamic options for frontend form fields that use `frontend_options` as a string reference (e.g., `"user.role"`). This allows the frontend to fetch options from the backend, enabling:
- Database-driven options (e.g., user connections)
- Context-aware options (filtered by current user's permissions)
- Centralized option management

### Frontend Options Format

The `frontend_options` attribute in Pydantic `Field` definitions supports **two formats**:

#### 1. Static List (for basic data types)
```python
frontend_options=[
    {"value": "a", "label": {"en": "All Records", "fr": "Tous les enregistrements"}},
    {"value": "m", "label": {"en": "My Records", "fr": "Mes enregistrements"}}
]
```

#### 2. String Reference (for dynamic/custom types)
```python
frontend_options="user.role"  # Frontend fetches from /api/options/user.role
```

### API Endpoints

#### Get Options
```
GET /api/options/{optionsName}
```

**Path Parameters:**
- `optionsName`: Name of the options set (e.g., "user.role", "user.connection")

**Response:**
```json
[
    {
        "value": "sysadmin",
        "label": {
            "en": "System Administrator",
            "fr": "Administrateur système"
        }
    },
    {
        "value": "admin",
        "label": {
            "en": "Administrator",
            "fr": "Administrateur"
        }
    }
]
```

**Examples:**
- `GET /api/options/user.role` - Get available role options
- `GET /api/options/user.connection` - Get user's connections (context-aware)
- `GET /api/options/auth.authority` - Get authentication authority options
- `GET /api/options/connection.status` - Get connection status options

#### List Available Options
```
GET /api/options/
```

**Response:**
```json
[
    "user.role",
    "auth.authority",
    "connection.status",
    "user.connection"
]
```

### Available Options

| Options Name | Description | Context-Aware |
|-------------|------------|---------------|
| `user.role` | Standard role options (sysadmin, admin, user, viewer) | No |
| `auth.authority` | Authentication authority options (local, google, msft) | No |
| `connection.status` | Connection status options (active, inactive, expired, error) | No |
| `user.connection` | User's connections (fetched from database) | Yes (requires currentUser) |

### Implementation

**Files:**
- `gateway/modules/features/options/mainOptions.py` - Options logic
- `gateway/modules/routes/routeOptions.py` - Options API endpoints

**Usage in Pydantic Models:**
```python
roleLabels: List[str] = Field(
    default_factory=list,
    description="List of role labels",
    json_schema_extra={
        "frontend_type": "multiselect",
        "frontend_readonly": False,
        "frontend_required": True,
        "frontend_options": "user.role"  # String reference
    }
)
```

---

## 2. Admin RBAC Roles Module

### Purpose

The Admin RBAC Roles module provides comprehensive management of roles and role assignments to users. This module allows administrators to:
- View all available roles with metadata
- List users with their role assignments
- Assign/remove roles to/from users
- Filter users by role or mandate
- View role statistics (user counts per role)

### Access Control

**Required Permissions:**
- User must have `admin` or `sysadmin` role
- RBAC permission check for `UserInDB` table update operations

### API Endpoints

#### List All Roles
```
GET /api/admin/rbac/roles/
```

**Response:**
```json
[
    {
        "roleLabel": "sysadmin",
        "description": {
            "en": "System Administrator - Full access to all system resources",
            "fr": "Administrateur système - Accès complet à toutes les ressources"
        },
        "userCount": 2,
        "isSystemRole": true
    },
    {
        "roleLabel": "admin",
        "description": {
            "en": "Administrator - Manage users and resources within mandate scope",
            "fr": "Administrateur - Gérer les utilisateurs et ressources dans le périmètre du mandat"
        },
        "userCount": 5,
        "isSystemRole": true
    }
]
```

#### List Users with Roles
```
GET /api/admin/rbac/roles/users?roleLabel=admin&mandateId=mandate-123
```

**Query Parameters:**
- `roleLabel` (optional): Filter by role label
- `mandateId` (optional): Filter by mandate ID

**Response:**
```json
[
    {
        "id": "user-123",
        "username": "john.doe",
        "email": "john@example.com",
        "fullName": "John Doe",
        "mandateId": "mandate-123",
        "enabled": true,
        "roleLabels": ["admin", "user"],
        "roleCount": 2
    }
]
```

#### Get User Roles
```
GET /api/admin/rbac/roles/users/{userId}
```

**Response:**
```json
{
    "id": "user-123",
    "username": "john.doe",
    "email": "john@example.com",
    "fullName": "John Doe",
    "mandateId": "mandate-123",
    "enabled": true,
    "roleLabels": ["admin", "user"],
    "roleCount": 2
}
```

#### Update User Roles
```
PUT /api/admin/rbac/roles/users/{userId}/roles
```

**Request Body:**
```json
{
    "roleLabels": ["admin", "user"]
}
```

**Response:**
Updated user object with new role assignments

#### Add Role to User
```
POST /api/admin/rbac/roles/users/{userId}/roles/{roleLabel}
```

**Response:**
Updated user object with role added (if not already present)

#### Remove Role from User
```
DELETE /api/admin/rbac/roles/users/{userId}/roles/{roleLabel}
```

**Response:**
Updated user object with role removed

**Note:** If all roles are removed, user defaults to `"user"` role

#### Get Users with Specific Role
```
GET /api/admin/rbac/roles/roles/{roleLabel}/users?mandateId=mandate-123
```

**Query Parameters:**
- `mandateId` (optional): Filter by mandate ID

**Response:**
List of users with the specified role

### Standard Roles

| Role Label | Description | System Role |
|-----------|-------------|-------------|
| `sysadmin` | System Administrator - Full access to all system resources | Yes |
| `admin` | Administrator - Manage users and resources within mandate scope | Yes |
| `user` | User - Standard user with access to own records | Yes |
| `viewer` | Viewer - Read-only access to group records | Yes |

**Custom Roles:** The system also supports custom role labels. These are detected when users are assigned non-standard roles and are marked with `isSystemRole: false`.

### Implementation

**Files:**
- `gateway/modules/routes/routeAdminRbacRoles.py` - Admin RBAC Roles API endpoints

**Dependencies:**
- `gateway/modules/interfaces/interfaceDbAppObjects.py` - User management interface
- `gateway/modules/security/auth.py` - Authentication and authorization

### Usage Examples

#### Assign Multiple Roles to User
```bash
curl -X PUT "http://localhost:8000/api/admin/rbac/roles/users/user-123/roles" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"roleLabels": ["admin", "user"]}'
```

#### Add Single Role
```bash
curl -X POST "http://localhost:8000/api/admin/rbac/roles/users/user-123/roles/admin" \
  -H "Authorization: Bearer <token>"
```

#### Remove Role
```bash
curl -X DELETE "http://localhost:8000/api/admin/rbac/roles/users/user-123/roles/viewer" \
  -H "Authorization: Bearer <token>"
```

#### List All Admins
```bash
curl "http://localhost:8000/api/admin/rbac/roles/roles/admin/users" \
  -H "Authorization: Bearer <token>"
```

---

## Integration

### Route Registration

Both modules are registered in `gateway/app.py`:

```python
from modules.routes.routeOptions import router as optionsRouter
app.include_router(optionsRouter)

from modules.routes.routeAdminRbacRoles import router as adminRbacRolesRouter
app.include_router(adminRbacRolesRouter)
```

### Frontend Integration

#### Using Dynamic Options

When a Pydantic model field uses `frontend_options` as a string reference:

```python
roleLabels: List[str] = Field(
    frontend_options="user.role"
)
```

The frontend should:
1. Detect the string reference (not a list)
2. Fetch options from `/api/options/user.role`
3. Use the returned options for the select/multiselect field

#### Using Admin RBAC Roles Module

The frontend can use the Admin RBAC Roles endpoints to:
- Display role management UI
- Show role assignments in user management
- Provide role assignment controls
- Display role statistics

---

## Security Considerations

1. **Options API**: 
   - Requires authentication (currentUser dependency)
   - Context-aware options (e.g., `user.connection`) are filtered by current user
   - Rate limited: 120 requests/minute

2. **Admin RBAC Roles Module**:
   - Requires `admin` or `sysadmin` role
   - All endpoints are rate limited: 30-60 requests/minute
   - RBAC permission checks ensure users can only manage roles if they have permission

---

## Future Enhancements

1. **Options API**:
   - Add more option types (e.g., mandate options, workflow options)
   - Support for filtered options based on RBAC permissions
   - Caching for frequently accessed options

2. **Admin RBAC Roles Module**:
   - Role metadata management (descriptions, permissions summary)
   - Bulk role assignment operations
   - Role usage analytics
   - Role templates/presets