python-json-rbac

Minimal, secure JWT/JWE + RBAC for FastAPI. Provides decorators and utilities for secure, role-based access control in modern Python web APIs.

Table of Contents

• Overview
• Features
• Installation
• Quickstart
• Configuration & .env Support
• Usage Example
• Advanced Usage & API
• Testing
• Security & Logging
• Contributing & Support
• License

Overview

python-json-rbac provides decorators and utilities for secure, role-based access control (RBAC) in modern Python web APIs. It supports JWT and JWE tokens, integrates with FastAPI, and is designed for modular, scalable, and secure backend architectures.

Features

• JWT and optional JWE (encrypted JWT) support
• Role-based access control (RBAC) decorators
• FastAPI dependency integration
• Modular, service-oriented design
• Secure defaults and environment-based configuration
• Support for multiple user roles
• Extensible for custom permission logic
• .env support for easy configuration
• Production-grade logging

Installation

pip install python-json-rbac

Quickstart

1. Add a .env file to your project root:

   JWT_SECRET=your_super_secret_key
   JWT_ALGORITHM=HS256
   JWT_EXPIRE_MINUTES=30
   

2. Install dependencies (if not already):

   pip install python-json-rbac
   

3. Create a FastAPI app:

   from python_json_rbac.auth import create_access_token, get_current_user
   from python_json_rbac.decorators import rbac_protect
   from fastapi import FastAPI, Depends
   
   app = FastAPI()
   
   @app.get("/admin")
   @rbac_protect(role="admin")
   def admin_dashboard(user=Depends(get_current_user)):
       return {"message": f"Welcome, {user['sub']}!"}
   

Configuration & .env Support

• All configuration can be set via environment variables or a .env file (recommended for development).
• Supported variables:
  • JWT_SECRET (required)
  • JWT_ALGORITHM (HS256 or RS256)
  • JWT_PRIVATE_KEY_PATH, JWT_PUBLIC_KEY_PATH (for RS256)
  • JWT_ENABLE_JWE (optional, default: false)
  • JWT_EXPIRE_MINUTES (default: 30)
  • See documentation/docs/configuration/env-vars.md for full details.

Usage Example

Symmetric (HS256) Example

from python_json_rbac.auth import create_access_token, get_current_user
from python_json_rbac.decorators import rbac_protect
from fastapi import FastAPI, Depends

app = FastAPI()

@app.get("/admin")
@rbac_protect(role="admin")
def admin_dashboard(user=Depends(get_current_user)):
    return {"message": f"Welcome, {user['sub']}!"}

Asymmetric (RS256) Example

# In your .env:
# JWT_ALGORITHM=RS256
# JWT_PRIVATE_KEY_PATH=path/to/private.pem
# JWT_PUBLIC_KEY_PATH=path/to/public.pem

from python_json_rbac.auth import create_access_token
# ...rest is the same as above

Advanced Usage & API

• See the documentation/docs/ directory for advanced RBAC, JWE, key rotation, and API reference.
• Example: documentation/docs/usage.md

Testing

To run tests:

pip install pytest
pytest

Security & Logging

• All warnings and errors use Python's logging module for production readiness.
• Secrets are validated for length and entropy.
• JWE encryption and key rotation are supported.
• See documentation/docs/configuration/best-practices.md for best practices.

Contributing & Support

• Contributions are welcome! Please open issues or submit pull requests on GitHub.
• For questions, use GitHub Discussions or file an issue.

License

LGPL-2.1-only. See LICENSE for details.