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)

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)

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:

[
    {
        "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:

[
    "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:

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:

[
    {
        "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:

[
    {
        "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:

{
    "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:

{
    "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

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

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

Remove Role

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

List All Admins

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:

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:

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