{"id":31581336,"url":"https://github.com/triepod-ai/authentication-boilerplate","last_synced_at":"2025-10-05T21:56:29.080Z","repository":{"id":318004291,"uuid":"1068637638","full_name":"triepod-ai/authentication-boilerplate","owner":"triepod-ai","description":"An enterprise-pattern authentication system for Flask + React with JWT, RBAC, session management, and audit logging. Implements production-grade security patterns used in financial services environments.","archived":false,"fork":false,"pushed_at":"2025-10-04T11:50:45.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T13:26:44.973Z","etag":null,"topics":["authentication","boilerplate","flask","javascript","jwt","jwt-authentication","python","rbac","react"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/triepod-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T17:22:41.000Z","updated_at":"2025-10-04T11:50:48.000Z","dependencies_parsed_at":"2025-10-04T13:26:47.680Z","dependency_job_id":"830a6c3a-4fc7-4315-9853-050d8383bd84","html_url":"https://github.com/triepod-ai/authentication-boilerplate","commit_stats":null,"previous_names":["triepod-ai/authentication-boilerplate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/triepod-ai/authentication-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fauthentication-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fauthentication-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fauthentication-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fauthentication-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/triepod-ai","download_url":"https://codeload.github.com/triepod-ai/authentication-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fauthentication-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526240,"owners_count":26001326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","boilerplate","flask","javascript","jwt","jwt-authentication","python","rbac","react"],"created_at":"2025-10-05T21:56:27.854Z","updated_at":"2025-10-05T21:56:29.075Z","avatar_url":"https://github.com/triepod-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Authentication Boilerplate\n\n## ⚠️ Important Notice\n\n**This repository is for demonstration purposes only.**\n\nThis authentication boilerplate has been extracted from private production repositories to demonstrate architectural patterns and best practices. All sensitive implementation details, proprietary business logic, and confidential information have been removed or sanitized.\n\n**Purpose:**\n- Demonstrate authentication system architecture patterns used in production environments\n- Provide educational reference for secure authentication implementation\n- Showcase integration patterns between Flask backend and React frontend\n- Share proven patterns while maintaining privacy of production systems\n\n**What this is NOT:**\n- Not a copy of any production system\n- Not intended to expose proprietary or confidential code\n- Not a security risk or leak of private repositories\n\nThis repository serves as a pattern reference extracted and adapted from real-world production systems, modified specifically for public demonstration and educational purposes.\n\n---\n\nA comprehensive, production-ready authentication system for Flask + React applications.\n\n## Features\n\n### Backend (Flask)\n- **JWT-based user authentication**\n  - Secure token generation and verification\n  - Password hashing (SHA-256 with salt + Werkzeug)\n  - Token refresh mechanism\n  - Failed login tracking\n\n- **Admin authentication with RBAC**\n  - Session-based authentication\n  - Role-based access control (super_admin, admin, moderator)\n  - Admin audit logging\n  - Permission-based decorators\n\n- **Multi-tenant support** (optional)\n  - Tenant-aware authentication\n  - Isolated user spaces\n\n- **Security features**\n  - Password strength validation\n  - Email format validation\n  - Session expiry management\n  - Audit trail for admin actions\n\n### Frontend (React)\n- **Reusable authentication components**\n  - LoginForm\n  - RegisterForm\n  - ProtectedRoute\n\n- **Global authentication state**\n  - AuthContext with React Context API\n  - useAuth hook\n  - LocalStorage token persistence\n\n- **Features**\n  - Auto token verification\n  - Token refresh\n  - Profile management\n  - Password change\n\n## Project Structure\n\n```\nauthentication-boilerplate/\n├── backend/\n│   ├── auth/\n│   │   ├── __init__.py\n│   │   ├── user_auth.py          # User authentication system\n│   │   └── admin_auth.py         # Admin authentication system\n│   ├── models/\n│   │   ├── __init__.py\n│   │   ├── user.py               # User model\n│   │   ├── admin_user.py         # Admin user model\n│   │   └── audit_log.py          # Admin audit log model\n│   ├── routes/\n│   │   ├── __init__.py\n│   │   ├── user_auth_routes.py   # User API routes\n│   │   └── admin_auth_routes.py  # Admin API routes\n│   ├── utils/\n│   │   ├── __init__.py\n│   │   └── validators.py         # Validation utilities\n│   ├── app_example.py            # Example Flask app\n│   └── requirements.txt\n├── frontend/\n│   ├── components/\n│   │   └── auth/\n│   │       ├── LoginForm.jsx\n│   │       ├── RegisterForm.jsx\n│   │       └── ProtectedRoute.jsx\n│   ├── context/\n│   │   └── AuthContext.jsx       # Global auth state\n│   ├── hooks/\n│   │   └── useAuth.js\n│   └── package.json\n├── docs/\n├── .env.example\n└── README.md\n```\n\n## Development Approach\n\nThis repository represents a curated boilerplate extracted and sanitized\nfrom private production implementations. The single/minimal commit history\nreflects:\n\n- **Extraction \u0026 Sanitization**: Production code adapted for public use\n- **Security-First**: All proprietary business logic and credentials removed\n- **Pattern Focus**: Emphasis on reusable patterns vs. specific features\n\nFor iterative development history, see active projects:\n- [mcp-server-qdrant-enhanced](https://github.com/triepod-ai/mcp-server-qdrant-enhanced) - 88+ commits\n- [inspector-assessment](https://github.com/triepod-ai/inspector) - 1,612+ commits\n- [chroma-mcp](https://github.com/triepod-ai/chroma-mcp) - 63+ commits\n\n## Quick Start\n\n### Automated Setup (Recommended)\n\nRun the setup script to automatically configure everything:\n\n```bash\n./setup.sh\n```\n\nThis will:\n- Install `uv` if not present\n- Create virtual environment\n- Install all backend dependencies\n- Install all frontend dependencies\n- Create `.env` file from template\n\n### Manual Backend Setup\n\n1. **Create virtual environment (recommended - uses uv for WSL compatibility):**\n   ```bash\n   cd backend\n   uv venv\n   source .venv/bin/activate\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   uv pip install -r requirements.txt\n   ```\n\n   **Optional - for PostgreSQL or MySQL:**\n   ```bash\n   # For PostgreSQL\n   uv pip install -r requirements-postgres.txt\n\n   # For MySQL\n   uv pip install -r requirements-mysql.txt\n   ```\n\n3. **Configure environment:**\n   ```bash\n   cp ../.env.example ../.env\n   # Edit .env with your configuration\n   ```\n\n4. **Run the application:**\n   ```bash\n   python3 app_example.py\n   ```\n\n   The backend will start on `http://localhost:5000`\n\n4. **Default admin credentials:**\n   - Username: `admin`\n   - Password: `admin123` (change this immediately!)\n\n### Frontend Setup\n\n1. **Install dependencies:**\n   ```bash\n   cd frontend\n   npm install\n   ```\n\n2. **Run development server:**\n   ```bash\n   npm run dev\n   ```\n\n   The frontend will start on `http://localhost:5173`\n\n## Usage\n\n### Backend Integration\n\n#### Basic Setup\n\n```python\nfrom flask import Flask\nfrom auth import UserAuthSystem, AdminAuthSystem\nfrom models import db, User, AdminUser, AdminAuditLog\nfrom routes import create_user_auth_routes, create_admin_auth_routes\n\napp = Flask(__name__)\napp.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///auth.db'\napp.config['JWT_SECRET'] = 'your-secret-key'\n\n# Initialize database\ndb.init_app(app)\n\n# Initialize authentication systems\nuser_auth = UserAuthSystem(app, db, User)\nadmin_auth = AdminAuthSystem(app, db, AdminUser, AdminAuditLog)\n\n# Register routes\napp.register_blueprint(create_user_auth_routes(user_auth, db))\napp.register_blueprint(create_admin_auth_routes(admin_auth, db, AdminAuditLog))\n\n# Create tables\nwith app.app_context():\n    db.create_all()\n```\n\n#### Using Decorators\n\n```python\nfrom auth import require_user, require_admin\n\n@app.route('/api/protected')\n@require_user(user_auth)\ndef protected_endpoint():\n    user = request.current_user\n    return {'message': f'Hello {user.name}!'}\n\n@app.route('/api/admin/dashboard')\n@require_admin(admin_auth)\ndef admin_dashboard():\n    admin = request.admin_user\n    return {'message': f'Admin: {admin.username}'}\n```\n\n#### Multi-tenant Support\n\n```python\napp.config['MULTI_TENANT_ENABLED'] = True\n\n# In your routes\n@app.route('/api/auth/login', methods=['POST'])\ndef login():\n    data = request.get_json()\n    tenant = request.headers.get('X-Tenant-ID')  # Get tenant from header\n    result = user_auth.authenticate_user(\n        data['email'],\n        data['password'],\n        tenant\n    )\n```\n\n### Frontend Integration\n\n#### Setup AuthProvider\n\n```jsx\nimport React from 'react';\nimport { BrowserRouter } from 'react-router-dom';\nimport { AuthProvider } from './context/AuthContext';\nimport App from './App';\n\nfunction Root() {\n  return (\n    \u003cBrowserRouter\u003e\n      \u003cAuthProvider apiUrl=\"http://localhost:5000/api/auth\"\u003e\n        \u003cApp /\u003e\n      \u003c/AuthProvider\u003e\n    \u003c/BrowserRouter\u003e\n  );\n}\n\nexport default Root;\n```\n\n#### Using Authentication Components\n\n```jsx\nimport { LoginForm, RegisterForm } from './components/auth';\nimport { useAuth } from './hooks/useAuth';\n\nfunction LoginPage() {\n  const { login } = useAuth();\n\n  const handleLogin = async (email, password) =\u003e {\n    try {\n      await login(email, password);\n      // Redirect or update UI\n    } catch (error) {\n      console.error('Login failed:', error);\n    }\n  };\n\n  return \u003cLoginForm onLogin={handleLogin} /\u003e;\n}\n```\n\n#### Protected Routes\n\n```jsx\nimport { Routes, Route } from 'react-router-dom';\nimport { ProtectedRoute } from './components/auth';\nimport { useAuth } from './hooks/useAuth';\n\nfunction App() {\n  const { isAuthenticated } = useAuth();\n\n  return (\n    \u003cRoutes\u003e\n      \u003cRoute path=\"/login\" element={\u003cLoginPage /\u003e} /\u003e\n      \u003cRoute\n        path=\"/dashboard\"\n        element={\n          \u003cProtectedRoute isAuthenticated={isAuthenticated}\u003e\n            \u003cDashboard /\u003e\n          \u003c/ProtectedRoute\u003e\n        }\n      /\u003e\n    \u003c/Routes\u003e\n  );\n}\n```\n\n#### Using useAuth Hook\n\n```jsx\nimport { useAuth } from './hooks/useAuth';\n\nfunction UserProfile() {\n  const { user, logout, updateProfile } = useAuth();\n\n  const handleUpdate = async (updates) =\u003e {\n    try {\n      await updateProfile(updates);\n      alert('Profile updated!');\n    } catch (error) {\n      console.error('Update failed:', error);\n    }\n  };\n\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eWelcome, {user?.name}!\u003c/h1\u003e\n      \u003cbutton onClick={logout}\u003eLogout\u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## API Endpoints\n\n### User Authentication\n\n| Method | Endpoint | Description | Auth Required |\n|--------|----------|-------------|---------------|\n| POST | `/api/auth/register` | Register new user | No |\n| POST | `/api/auth/login` | User login | No |\n| POST | `/api/auth/logout` | User logout | Yes |\n| GET | `/api/auth/profile` | Get user profile | Yes |\n| PUT | `/api/auth/profile` | Update user profile | Yes |\n| POST | `/api/auth/change-password` | Change password | Yes |\n| POST | `/api/auth/refresh` | Refresh token | Yes |\n| GET | `/api/auth/verify` | Verify token | Optional |\n\n### Admin Authentication\n\n| Method | Endpoint | Description | Auth Required | Role Required |\n|--------|----------|-------------|---------------|---------------|\n| POST | `/api/admin/login` | Admin login | No | - |\n| POST | `/api/admin/logout` | Admin logout | Yes | - |\n| GET | `/api/admin/profile` | Get admin profile | Yes | - |\n| POST | `/api/admin/change-password` | Change password | Yes | - |\n| GET | `/api/admin/users` | List admin users | Yes | super_admin |\n| POST | `/api/admin/users` | Create admin user | Yes | super_admin |\n| PUT | `/api/admin/users/:id` | Update admin user | Yes | super_admin |\n| GET | `/api/admin/audit-logs` | Get audit logs | Yes | - |\n\n## Configuration\n\n### Database Setup\n\n**SQLite (Default - No setup required)**\n\nThe boilerplate uses SQLite by default, which requires no additional setup. Perfect for development and small deployments.\n\n**PostgreSQL (Optional)**\n\n1. Install PostgreSQL driver:\n   ```bash\n   cd backend\n   source .venv/bin/activate\n   uv pip install -r requirements-postgres.txt\n   ```\n\n2. Update `.env`:\n   ```\n   DATABASE_URI=postgresql://user:password@localhost:5432/auth_db\n   ```\n\n**MySQL (Optional)**\n\n1. Install MySQL driver:\n   ```bash\n   cd backend\n   source .venv/bin/activate\n   uv pip install -r requirements-mysql.txt\n   ```\n\n2. Update `.env`:\n   ```\n   DATABASE_URI=mysql://user:password@localhost:3306/auth_db\n   ```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SECRET_KEY` | Flask secret key | (required) |\n| `DATABASE_URI` | Database connection string | `sqlite:///auth.db` |\n| `JWT_SECRET` | JWT signing secret | (required) |\n| `TOKEN_EXPIRY_SECONDS` | User token expiry | `604800` (7 days) |\n| `ADMIN_SESSION_EXPIRY_SECONDS` | Admin session expiry | `86400` (24 hours) |\n| `MULTI_TENANT_ENABLED` | Enable multi-tenant | `false` |\n\n## Database Models\n\n### User\n\n- `id`: Integer, primary key\n- `email`: String, unique\n- `name`: String\n- `password_hash`: String\n- `tenant`: String (optional, for multi-tenant)\n- `is_active`: Boolean\n- `email_verified`: Boolean\n- `last_login`: DateTime\n- `login_count`: Integer\n- `failed_login_attempts`: Integer\n- `created_at`: DateTime\n- `updated_at`: DateTime\n\n### AdminUser\n\n- `id`: Integer, primary key\n- `username`: String, unique\n- `email`: String, unique\n- `password_hash`: String\n- `role`: String (super_admin, admin, moderator)\n- `is_active`: Boolean\n- `session_token`: String\n- `session_expires`: DateTime\n- `last_login`: DateTime\n- `created_at`: DateTime\n- `updated_at`: DateTime\n\n### AdminAuditLog\n\n- `id`: Integer, primary key\n- `admin_user_id`: Integer, foreign key\n- `action`: String\n- `resource_type`: String\n- `resource_id`: Integer\n- `details`: Text (JSON)\n- `ip_address`: String\n- `user_agent`: String\n- `created_at`: DateTime\n\n## Security Best Practices\n\n1. **Change default credentials** immediately in production\n2. **Use strong secrets** for JWT_SECRET and SECRET_KEY\n3. **Use HTTPS** in production\n4. **Set secure cookie flags** if using cookies\n5. **Implement rate limiting** for login endpoints\n6. **Monitor audit logs** regularly\n7. **Keep dependencies updated**\n8. **Use environment variables** for sensitive config\n9. **Implement password complexity rules** as needed\n10. **Enable CORS carefully** in production\n\n## Customization\n\n### Adding Custom User Fields\n\n1. Extend the User model in `backend/models/user.py`\n2. Update registration endpoint to accept new fields\n3. Update frontend forms as needed\n\n### Custom Password Hashing\n\nThe system supports both Werkzeug and SHA-256 hashing:\n\n```python\n# In User model\nuser.set_password('password', method='werkzeug')  # or 'sha256'\n```\n\n### Adding Permissions\n\n1. Add permission fields to AdminUser model\n2. Create custom decorators in `backend/auth/admin_auth.py`\n3. Apply decorators to protected routes\n\n## Testing\n\n### Backend Testing\n\n```bash\ncd backend\nsource .venv/bin/activate  # Activate virtual environment\nuv pip install pytest      # Install pytest if not already installed\npython3 -m pytest tests/\n```\n\n### Frontend Testing\n\n```bash\ncd frontend\nnpm run test\n```\n\n## License\n\nMIT License - feel free to use this boilerplate in your projects.\n\n## Support\n\nFor issues or questions, please check the documentation or create an issue in the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriepod-ai%2Fauthentication-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriepod-ai%2Fauthentication-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriepod-ai%2Fauthentication-boilerplate/lists"}