HF Inference Proxy - RBAC System

Overview

The HF Inference Proxy now includes a comprehensive Role-Based Access Control (RBAC) system that manages user authentication and endpoint access permissions.

📖 Note: This document provides detailed RBAC documentation for developers and administrators. For quick start and basic usage, see the main README.md.

Features

• API Key Authentication: Users authenticate via Bearer tokens in the Authorization header
• Role-Based Access Control: Four predefined roles with different permission levels
• Admin Management: Full user and role management through admin endpoints
• Secure Universal Proxy: Protected universal proxy endpoint with role-based access
• Audit Logging: All requests are logged with user context when authenticated

Documentation Structure

README.md vs RBAC_README.md

Document	Purpose	Audience	Content
README.md	Quick Start & Usage	End Users	Basic setup, curl examples, quick reference
RBAC_README.md	Detailed RBAC Reference	Developers & Admins	Implementation details, validation, testing, troubleshooting

When to Use Which Document

• 🚀 Getting Started: Use README.md for quick setup and basic examples
• 🔧 Advanced Configuration: Use RBAC_README.md for detailed RBAC setup and troubleshooting
• 🧪 Testing & Development: Use RBAC_README.md for comprehensive testing examples
• 📚 API Reference: Use RBAC_README.md for Pydantic models and validation details

Quick Start

1. Default Admin User

The system creates a default admin user on first run:

{
  "username": "admin",
  "api_key": "hf_proxy_admin_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz5678901234567890"
}

⚠️ IMPORTANT: Use this API key to access admin endpoints and create additional users.

2. Authentication

All protected endpoints require the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/admin/users

3. Creating a New User

curl -X POST "http://localhost:8000/admin/users" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "newuser", "email": "newuser@example.com", "full_name": "New User", "role": "user"}'

Roles and Permissions

Admin Role

• Access: All endpoints (*)
• Description: Full system access
• Use Case: System administrators

Manager Role

• Access: Key management + Universal proxy
• Endpoints:
  • /check-validity/*
  • /add-key/*
  • /keys/*
  • /{path:path} (Universal proxy)
• Use Case: Key managers and system operators

User Role

• Access: Standard user access
• Endpoints:
  • /health, /docs, /
  • /{path:path} (Universal proxy)
  • /keys/provision, /keys/report
• Use Case: Regular users accessing HF Inference API

Guest Role (Default)

• Access: Public endpoints only
• Endpoints: /health, /docs, /
• Use Case: Basic access with authentication tracking

API Design

JSON-Based REST API

The admin endpoints use JSON for all request/response data, following REST API best practices:

• Content-Type: application/json for all POST/PUT requests
• Request Body: JSON objects with proper validation
• Response Format: Consistent JSON responses with success/error indicators
• Type Safety: Pydantic models provide automatic validation and type checking

API Response Format

All endpoints return consistent JSON responses:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {...}  // Optional, endpoint-specific data
}

Error responses:

{
  "detail": "Error message describing what went wrong"
}

API Endpoints

Public Endpoints (No Auth Required)

• GET /health - Health check
• GET /docs - API documentation
• GET / - Server information

Admin Endpoints (Admin Role Required)

User Management

List All Users

curl -H "Authorization: Bearer ADMIN_API_KEY" \
  "http://localhost:8000/admin/users"

Create New User

curl -X POST "http://localhost:8000/admin/users" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "full_name": "New User",
    "role": "user"
  }'

Update User

curl -X PUT "http://localhost:8000/admin/users/newuser" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "updated@example.com",
    "full_name": "Updated User Name"
  }'

Delete User

curl -X DELETE "http://localhost:8000/admin/users/newuser" \
  -H "Authorization: Bearer ADMIN_API_KEY"

Regenerate API Key

curl -X POST "http://localhost:8000/admin/users/newuser/generate-key" \
  -H "Authorization: Bearer ADMIN_API_KEY"

Role Management

List All Roles

curl -H "Authorization: Bearer ADMIN_API_KEY" \
  "http://localhost:8000/admin/roles"

Create New Role

curl -X POST "http://localhost:8000/admin/roles" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customrole",
    "description": "Custom role for specific access",
    "endpoints": ["/health", "/docs", "/custom/*"],
    "is_default": false
  }'

Update Role

curl -X PUT "http://localhost:8000/admin/roles/customrole" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated role description",
    "endpoints": ["/health", "/docs", "/custom/*", "/new/*"]
  }'

Delete Role

curl -X DELETE "http://localhost:8000/admin/roles/customrole" \
  -H "Authorization: Bearer ADMIN_API_KEY"

Key Management Endpoints

Manager/Admin Access Required

• GET /check-validity/{key} - Check key validity
• POST /add-key/{key} - Add new API key
• POST /add-key - Add multiple keys
• GET /keys/status - Get all keys status
• POST /keys/refresh - Force refresh keys
• POST /keys/validate - Validate keys
• POST /keys/reload - Reload keys from file
• POST /keys/cleanup - Cleanup invalid keys
• GET /keys/quarantine - Get quarantine status
• POST /keys/quarantine/clear/{key} - Clear quarantine

User Access Required

• GET /keys/provision - Get API key for client usage
• POST /keys/report - Report token usage status

Universal Proxy

• /{path:path} - Proxies requests to HF Inference API (role-based access)

Usage Examples

1. Create a Manager User

curl -X POST "http://localhost:8000/admin/users" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "manager1", "email": "manager@example.com", "full_name": "Key Manager", "role": "manager"}'

2. Create a Regular User

curl -X POST "http://localhost:8000/admin/users" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "user1", "email": "user@example.com", "full_name": "Regular User", "role": "user"}'

3. Use the Universal Proxy

# With user authentication
curl -H "Authorization: Bearer USER_API_KEY" \
  "http://localhost:8000/models/gpt2"

# With manager authentication (has access to key management)
curl -H "Authorization: Bearer MANAGER_API_KEY" \
  "http://localhost:8000/keys/status"

4. Check User Permissions

# List all users (admin only)
curl -H "Authorization: Bearer ADMIN_API_KEY" \
  "http://localhost:8000/admin/users"

# List all roles (admin only)
curl -H "Authorization: Bearer ADMIN_API_KEY" \
  "http://localhost:8000/admin/roles"

Data Models & Validation

Pydantic Models

The API uses Pydantic models for automatic validation and type safety:

CreateUserRequest

{
  "username": "string (required)",
  "email": "string (required)",
  "full_name": "string (required)",
  "role": "string (optional, defaults to 'guest')"
}

UpdateUserRequest

{
  "email": "string (optional)",
  "full_name": "string (optional)",
  "role": "string (optional)",
  "is_active": "boolean (optional)"
}

CreateRoleRequest

{
  "name": "string (required)",
  "description": "string (required)",
  "endpoints": ["array of strings (required)"],
  "is_default": "boolean (optional, defaults to false)"
}

UpdateRoleRequest

{
  "description": "string (optional)",
  "endpoints": ["array of strings (optional)"],
  "is_default": "boolean (optional)"
}

Validation Features

• Automatic Type Checking: Pydantic validates all input data types
• Required Field Validation: Missing required fields return 400 errors
• Data Sanitization: Input data is automatically cleaned and validated
• Clear Error Messages: Validation errors provide specific feedback

Security Features

• API Key Generation: 64+ character cryptographically secure random strings
• Role-Based Access: Endpoint access controlled by user roles
• Universal Proxy Protection: Universal proxy endpoint respects role permissions
• Audit Logging: All requests logged with user context
• No Password Storage: Only API keys, no password management
• Input Validation: Comprehensive validation of all request data

Testing & Examples

Testing Admin Endpoints

You can test all admin endpoints using curl commands. Here’s a comprehensive test suite:

1. Test Authentication (should fail)

# No auth header
curl http://localhost:8000/admin/users

# Invalid API key
curl -H "Authorization: Bearer invalid_key" http://localhost:8000/admin/users

2. Test User Management

# List users
curl -H "Authorization: Bearer ADMIN_API_KEY" http://localhost:8000/admin/users

# Create user
curl -X POST "http://localhost:8000/admin/users" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com", "full_name": "Test User", "role": "user"}'

# Update user
curl -X PUT "http://localhost:8000/admin/users/testuser" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "updated@example.com"}'

# Regenerate API key
curl -X POST "http://localhost:8000/admin/users/testuser/generate-key" \
  -H "Authorization: Bearer ADMIN_API_KEY"

# Delete user
curl -X DELETE "http://localhost:8000/admin/users/testuser" \
  -H "Authorization: Bearer ADMIN_API_KEY"

3. Test Role Management

# List roles
curl -H "Authorization: Bearer ADMIN_API_KEY" http://localhost:8000/admin/roles

# Create role
curl -X POST "http://localhost:8000/admin/roles" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "testrole", "description": "Test role", "endpoints": ["/health", "/docs"]}'

# Update role
curl -X PUT "http://localhost:8000/admin/roles/testrole" \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated test role"}'

# Delete role
curl -X DELETE "http://localhost:8000/admin/roles/testrole" \
  -H "Authorization: Bearer ADMIN_API_KEY"

Expected Responses

Success Response (User Creation)

{
  "success": true,
  "message": "User testuser created successfully",
  "username": "testuser",
  "api_key": "generated_api_key_here..."
}

Error Response (Validation Error)

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "username"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Testing Tools

• curl: Command-line HTTP client for testing endpoints
• Postman: GUI tool for API testing
• FastAPI Docs: Interactive documentation at /docs endpoint
• OpenAPI Schema: Available at /openapi.json

Configuration

Environment Variables

• HF_PROXY_HOST - Server host (default: 0.0.0.0)
• HF_PROXY_PORT - Server port (default: 8000)
• HF_KEYS_FILE - HF API keys file (default: ./hf-keys.json)
• HF_BASE_URL - HF Inference base URL (default: https://router.huggingface.co)

Data Files

• users.json - User and role definitions
• hf-keys.json - HF API keys for proxy functionality

Migration Notes

• Existing endpoints now require authentication (except public ones)
• Universal proxy endpoint requires appropriate role permissions
• Admin endpoints are restricted to admin role only
• Key management endpoints require manager or admin role

Troubleshooting

Common Issues

1. 401 Unauthorized: Missing or invalid Authorization header
2. 403 Forbidden: User role doesn’t have access to endpoint
3. User not found: Check if user exists in users.json
4. Role not found: Verify role exists and is properly configured

Debug Mode

Enable debug logging by setting environment variable:

export LOG_LEVEL=DEBUG

Benefits of JSON-Based API

Why JSON Instead of Form Data?

The admin endpoints use JSON instead of form data for several important reasons:

1. 🔄 REST API Standards: JSON is the de facto standard for modern REST APIs
2. 📊 Type Safety: Pydantic models provide automatic validation and type checking
3. 🛠️ Developer Experience: Better IDE support, autocomplete, and documentation
4. 📖 API Documentation: FastAPI generates superior OpenAPI/Swagger documentation
5. 🚀 Performance: JSON parsing is more efficient than form data parsing
6. 🔒 Security: Better input validation and sanitization
7. 📱 Client Support: All modern HTTP clients support JSON natively
8. 🔄 Consistency: Maintains consistency with other API endpoints

Migration from Form Data

If you were previously using form data, update your requests to use JSON:

Before (Form Data)

curl -X POST -d "username=user&email=test@example.com" /admin/users

After (JSON)

curl -X POST -H "Content-Type: application/json" \
  -d '{"username": "user", "email": "test@example.com"}' /admin/users

Future Enhancements

• User activity monitoring and analytics
• Advanced role inheritance and permission groups
• API key expiration and rotation policies
• Integration with external identity providers
• Rate limiting and usage quotas per user
• Web-based admin interface
• Enhanced API validation: More sophisticated validation rules
• Bulk operations: Create/update multiple users/roles at once
• API versioning: Support for multiple API versions
• GraphQL support: Alternative query language for complex operations