AuthBarn 0.2.8.7

User authentication and role-based management.

AuthBarn

Version: 0.2.8.7
Creator: Darell Barnes
Email: [e-mail] License: MIT

---

Description

AuthBarn is a lightweight Python authentication system with user management and role-based permissions. It uses JWT tokens for stateless authentication, bcrypt for secure password hashing, and MySQL for reliable data persistence. Designed for standalone use or integration into larger applications, particularly web frameworks like Flask.

---

Key Features

• 🔐 JWT Authentication - Stateless token-based authentication with optional expiration
• 🔒 Secure Password Hashing - Uses bcrypt with salt for password storage
• 👥 Role-Based Access Control - Flexible permission system with custom roles
• 🗄️ MySQL Backend - Reliable database storage with thread-safe connections
• 📝 Logging System - Separate logs for general system activity and user actions
• 🛠️ Developer Mode - Enhanced debugging with detailed exceptions
• 🌐 Web-Ready - Returns structured JSON responses perfect for APIs

---

Installation

pip install AuthBarn

Dependencies

AuthBarn automatically installs:

• bcrypt - Password hashing
• PyJWT - JWT token generation and validation
• mysql-connector-python - MySQL database connectivity
• python-dotenv - Environment variable management

---

Quick Start

1. Database Setup

First, create a MySQL database:

CREATE DATABASE your_database_name;

2. Configuration

Create a configuration file or set up environment variables:

from authbarn import write_credentials_to_env

# One-time setup - creates .env file with credentials
write_credentials_to_env(
    host="127.0.0.1",
    port=3306,
    user="your_mysql_user",
    password="your_mysql_password",
    database_name="your_database_name"
)

This creates a .env file with your database credentials and a secure secret key.

Alternative: Manually create a .env file:

AUTHBARN_SECRET_KEY=your_generated_secret_key_here
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=your_mysql_user
DB_PASSWORD=your_mysql_password
DB_NAME=your_database_name

3. Initialize AuthBarn

from authbarn import Action

# Initialize with logging disabled (production)
auth = Action(enable_logging=False, dev_mode=False)

# Or with logging and dev mode (development)
auth = Action(enable_logging=True, dev_mode=True)

---

Core Concepts

Terminology

• Permission - Actions that can be performed (e.g., "add_user", "view_userinfo")
• Role - Groups of permissions (e.g., "Admin", "User", custom roles)
• Token - JWT token returned after login/register, used for authentication
• Developer Mode - When enabled, raises exceptions instead of returning error dictionaries

Return Values

AuthBarn methods return dictionaries for easy integration with web frameworks:

Success:

{"state": True, "token": "eyJhbG..."} # or other success data

Failure:

{"state": False, "message": "Error description"}

Developer Mode: Raises exceptions instead of returning error dictionaries.

---

Usage Guide

User Registration

Register a new user with default "User" role:

result = auth.register("john_doe", "secure_password123")

if result["state"]:
    token = result["Token"]  # Note: capital T
    print(f"Registration successful! Token: {token}")
else:
    print(f"Error: {result['message']}")

User Login

Authenticate and receive a JWT token:

result = auth.login("john_doe", "secure_password123")

if result["state"]:
    token = result["token"]  # Note: lowercase t
    print(f"Login successful! Token: {token}")
    # Store token for subsequent requests
else:
    print(f"Error: {result['message']}")

Token-Based Operations

Most operations require a valid token for authorization:

# Get token from login
result = auth.login("admin", "admin_password")
admin_token = result["token"]

# Use token for protected operations
result = auth.add_user("jane_doe", "password123", "User", token=admin_token)

---

Role Management

View Permission Configuration

Roles and their permissions are stored in authbarn/data/permission.json:

{
    "Admin": [
        "add_role",
        "remove_role", 
        "add_user",
        "remove_user",
        "view_userinfo"
    ],
    "User": []
}

Add a Role

# Add role with single permission
auth.add_role("Manager", "add_user", token=admin_token)

# Add role with multiple permissions
auth.add_role("Editor", ["view_userinfo", "add_user"], token=admin_token)

# Add empty role (no permissions)
auth.add_role("Guest", [], token=admin_token)

Remove a Role

result = auth.remove_role("Guest", token=admin_token)

Manually Edit Permissions

Edit authbarn/data/permission.json directly to add permissions to roles:

{
    "Admin": ["add_user", "remove_user", "view_userinfo"],
    "Manager": ["add_user", "view_userinfo"],
    "User": []
}

---

User Management

Add User (Requires Permission)

# Add user with default "User" role
result = auth.add_user("new_user", "password123", token=admin_token)

# Add user with custom role
result = auth.add_user("manager_user", "password123", "Manager", token=admin_token)

Bulk Add Users

usernames = ["user1", "user2", "user3"]
passwords = ["pass1", "pass2", "pass3"]

result = auth.add_bulk_user(
    username=usernames,
    password=passwords,
    role="User",
    token=admin_token
)

Remove User

result = auth.remove_user("john_doe", token=admin_token)

View User Information

# View specific user
user_info = auth.view_userinfo("john_doe", token=admin_token)
print(user_info)  # {"Username": "john_doe", "Role": "User"}

# View all users
all_users = auth.view_userinfo("all", token=admin_token)
# Returns list of tuples: [("user1", "User"), ("admin", "Admin"), ...]

Reset Password

result = auth.reset_password("john_doe", "new_secure_password")

if result["state"]:
    print("Password reset successful")

Security Note: Implement additional authentication (security questions, email verification) before allowing password resets in production.

---

Advanced Features

Custom Permission Decorator

Use the require_permission decorator to protect functions:

@auth.require_permission("Admin")
def admin_only_function(token):
    return "This function requires Admin role"

# Usage
try:
    result = admin_only_function(token=admin_token)
    print(result)
except PermissionDenied:
    print("Access denied!")

Verify Permissions Manually

has_permission = auth.verifypermissions("add_user", token=user_token)

if has_permission:
    # User has the permission
    result = auth.add_user(...)
else:
    print("User lacks required permission")

Custom Logging

Log custom events to the user log file:

auth = Action(enable_logging=True, dev_mode=False)

# Log levels: "info", "warning", "critical"
auth.log("info", "User performed custom action")
auth.log("warning", "Suspicious activity detected")
auth.log("critical", "System alert")

---

Configuration Options

Initialization Parameters

auth = Action(
    enable_logging=False,  # Enable/disable logging to files
    dev_mode=False         # Enable exceptions vs error dictionaries
)

• enable_logging (bool, default: False)

  • True: Logs all actions to authbarn/logfiles/general_logs.log
  • False: Logging disabled

• dev_mode (bool, default: False)

  • True: Raises exceptions for easier debugging
  • False: Returns error dictionaries (production-ready)

Log Levels

• info - General informational messages
• warning - Warning messages for non-critical issues
• critical - Critical errors requiring attention

---

File Structure

authbarn/
│
├── data/
│   └── permission.json          # Role-permission mappings
│
├── logfiles/
│   ├── general_logs.log         # System activity logs
│   └── user_logs.log            # Custom user logs
│
├── authbarn.py                  # Main authentication logic
├── config.py                    # Configuration and database setup
├── logger.py                    # Logging configuration
└── .env                         # Environment variables (git-ignored)

---

Integration Examples

Flask API Example

from flask import Flask, request, jsonify
from authbarn import Action

app = Flask(__name__)
auth = Action(enable_logging=True, dev_mode=False)

@app.route('/register', methods=['POST'])
def register():
    data = request.json
    result = auth.register(data['username'], data['password'])
    return jsonify(result)

@app.route('/login', methods=['POST'])
def login():
    data = request.json
    result = auth.login(data['username'], data['password'])
    return jsonify(result)

@app.route('/users', methods=['POST'])
def add_user():
    data = request.json
    token = request.headers.get('Authorization')
    result = auth.add_user(
        data['username'], 
        data['password'], 
        data.get('role', 'User'),
        token=token
    )
    return jsonify(result)

if __name__ == '__main__':
    app.run(debug=True)

FastAPI Example

from fastapi import FastAPI, Header
from authbarn import Action
from pydantic import BaseModel

app = FastAPI()
auth = Action(enable_logging=True, dev_mode=False)

class UserCreate(BaseModel):
    username: str
    password: str

@app.post("/register")
def register(user: UserCreate):
    result = auth.register(user.username, user.password)
    return result

@app.post("/login")
def login(user: UserCreate):
    result = auth.login(user.username, user.password)
    return result

@app.post("/users")
def add_user(user: UserCreate, role: str = "User", authorization: str = Header(None)):
    result = auth.add_user(user.username, user.password, role, token=authorization)
    return result

---

Security Best Practices

Production Deployment

1. Always disable developer mode:

   auth = Action(enable_logging=True, dev_mode=False)
   

2. Never commit .env file:

   • Ensure .env is in .gitignore
   • Use environment variables on production servers

3. Use strong secret keys:

   • AuthBarn auto-generates secure keys with write_credentials_to_env()
   • Never reuse secret keys across environments

4. Implement rate limiting:

   • Add rate limiting to prevent brute-force attacks on login endpoints

5. Use HTTPS:

   • Always transmit tokens over HTTPS in production

6. Token security:

   • Store tokens securely on the client (httpOnly cookies for web)
   • Implement token refresh for long-lived sessions
   • Consider adding token expiration (modify generate_token() to include exp claim)

Password Requirements

Consider implementing in your application:

• Minimum 8 characters
• Mix of uppercase, lowercase, numbers, and symbols
• Password strength checking
• Password history (prevent reuse)

---

Troubleshooting

Common Issues

"AUTHBARN_SECRET_KEY not found"

# Solution: Run the setup function first
from authbarn import write_credentials_to_env
write_credentials_to_env("localhost", 3306, "user", "pass", "dbname")

"credentials must be [host, port, user, password, database]"

# Solution: Check your .env file has all required fields
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=your_user
DB_PASSWORD=your_password
DB_NAME=your_database

Import Error: "No module named 'authbarn'"

# Solution: Install with correct capitalization
pip install AuthBarn

MySQL Connection Error

# Ensure MySQL is running
sudo systemctl start mysql  # Linux
# or
mysql.server start  # macOS

---

API Reference

Authentication Class

register(name, password)

Register a new user with "User" role.

Returns: {"state": True/False, "Token": "jwt_token", "message": "..."}

login(username, password)

Authenticate user and return JWT token.

Returns: {"state": True/False, "token": "jwt_token", "message": "..."}

reset_password(username, new_password)

Reset user's password.

Returns: {"state": True/False, "message": "..."}

generate_token(username, role)

Generate JWT token for user. Used internally but can be called directly.

Returns: str - JWT token

Action Class (extends Authentication)

add_role(new_role, permissions, token=None)

Add a new role with specified permissions.

Parameters:

• new_role (str): Role name
• permissions (str/list): Permission(s) to assign
• token (str): JWT token for authorization

remove_role(role_to_remove, token=None)

Remove a role from the system.

add_user(username, password, role="User", token=None)

Add a user with specified role.

add_bulk_user(username=[], password=[], role="User", token=None)

Add multiple users at once.

remove_user(username, token=None)

Remove a user from the system.

view_userinfo(toview, token=None)

View user information. Use "all" to view all users.

Returns: Dictionary with user info or list of all users

verifypermissions(perm, token=None)

Check if token has specific permission.

Returns: True/False

log(level, message)

Log custom message to user log file.

Parameters:

• level (str): "info", "warning", or "critical"
• message (str): Log message

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

Changelog

Version 0.2.8

• Migrated from JSON to MySQL database
• Added JWT token-based authentication
• Implemented role-based permission system
• Added environment variable configuration
• Improved thread safety with connection management
• Added bulk user operations
• Enhanced error handling and logging

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support

For issues, questions, or contributions:

• Email: [e-mail]
• GitHub: https://github.com/Barndalion/AuthBarn

---

AuthBarn - Secure and Lightweight Authentication for Your Python Applications! 🔐