UserModule - User Authentication

UserModule provides complete user authentication with email/password, OAuth, sessions, and JWT tokens.

Quick Start

from myfy.core import Application
from myfy.data import DataModule
from myfy.web import WebModule
from myfy.web.auth import AuthModule
from myfy.user import UserModule, BaseUser
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String

# Extend BaseUser with custom fields
class User(BaseUser):
    __tablename__ = "users"
    phone: Mapped[str | None] = mapped_column(String(20))

# Create module
user_module = UserModule(
    user_model=User,
    oauth_providers=["google", "github"],
    auto_create_tables=True,
)

# Set up application
app = Application()
app.add_module(DataModule())
app.add_module(WebModule())
app.add_module(AuthModule(
    authenticated_provider=user_module.get_authenticated_provider(),
))
app.add_module(user_module)

Configuration

Environment variables use the MYFY_USER_ prefix:

Variable	Default	Description
MYFY_USER_SECRET_KEY	(auto-generated)	Secret for JWT/sessions
MYFY_USER_SESSION_LIFETIME	604800	Session duration (7 days, in seconds)
MYFY_USER_JWT_ALGORITHM	HS256	JWT signing algorithm
MYFY_USER_JWT_ACCESS_TOKEN_LIFETIME	3600	JWT access token lifetime
MYFY_USER_PASSWORD_MIN_LENGTH	8	Minimum password length
MYFY_USER_REQUIRE_EMAIL_VERIFICATION	True	Require email verification

OAuth Configuration

# Google OAuth
MYFY_USER_OAUTH_GOOGLE_CLIENT_ID=your-client-id
MYFY_USER_OAUTH_GOOGLE_CLIENT_SECRET=your-secret

# GitHub OAuth
MYFY_USER_OAUTH_GITHUB_CLIENT_ID=your-client-id
MYFY_USER_OAUTH_GITHUB_CLIENT_SECRET=your-secret

Module Options

UserModule(
    user_model=User,              # Custom user model (must extend BaseUser)
    oauth_providers=["google"],   # OAuth providers to enable
    auto_create_tables=True,      # Create tables on start
    enable_routes=True,           # Register auth routes
    enable_templates=True,        # Provide Jinja2 templates
)

Custom User Model

from myfy.user import BaseUser
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String, Boolean

class User(BaseUser):
    __tablename__ = "users"

    # Custom fields
    phone: Mapped[str | None] = mapped_column(String(20))
    is_admin: Mapped[bool] = mapped_column(Boolean, default=False)
    company_id: Mapped[int | None] = mapped_column(ForeignKey("companies.id"))

    # Relationships
    company: Mapped["Company"] = relationship(back_populates="users")

BaseUser provides:

• id: Primary key
• email: Unique email address
• password_hash: Hashed password
• is_active: Account active status
• is_verified: Email verified status
• created_at, updated_at: Timestamps

Protected Routes

from myfy.web import route, Authenticated

@route.get("/profile")
async def profile(user: User) -> dict:
    # user is injected if authenticated
    # Returns 401 if not authenticated
    return {"email": user.email, "name": user.name}

@route.get("/admin")
async def admin_dashboard(user: User) -> dict:
    if not user.is_admin:
        abort(403, "Admin access required")
    return {"message": "Welcome, admin"}

Auth Routes

UserModule registers these routes by default:

Route	Method	Description
/auth/login	GET/POST	Login page and handler
/auth/logout	POST	Logout (clear session)
/auth/register	GET/POST	Registration page and handler
/auth/forgot-password	GET/POST	Password reset request
/auth/reset-password	GET/POST	Password reset form
/auth/verify-email	GET	Email verification link
/auth/google	GET	Google OAuth start
/auth/google/callback	GET	Google OAuth callback
/auth/github	GET	GitHub OAuth start
/auth/github/callback	GET	GitHub OAuth callback

Using UserService

from myfy.user import UserService

@route.post("/users")
async def create_user(body: CreateUserRequest, user_service: UserService) -> dict:
    user = await user_service.create(
        email=body.email,
        password=body.password,
    )
    return {"id": user.id}

@route.get("/users/{user_id}")
async def get_user(user_id: int, user_service: UserService) -> dict:
    user = await user_service.get_by_id(user_id)
    if not user:
        abort(404, "User not found")
    return {"email": user.email}

Session vs JWT

Session-Based (Web)

Default for web routes. Session ID stored in cookie.

@route.get("/dashboard")
async def dashboard(user: User) -> str:
    # Session cookie auto-validated
    return render_template("dashboard.html", user=user)

JWT-Based (API)

For API clients, use JWT tokens.

from myfy.user import JWTService

@route.post("/api/login")
async def api_login(body: LoginRequest, jwt_service: JWTService, user_service: UserService) -> dict:
    user = await user_service.authenticate(body.email, body.password)
    if not user:
        abort(401, "Invalid credentials")
    token = jwt_service.create_token(user)
    return {"token": token}

Client sends token in header:

Authorization: Bearer <token>

OAuth Integration

Google OAuth

user_module = UserModule(
    user_model=User,
    oauth_providers=["google"],
)

Login link:

<a href="/auth/google" class="btn">Login with Google</a>

GitHub OAuth

user_module = UserModule(
    user_model=User,
    oauth_providers=["github"],
)

Login link:

<a href="/auth/github" class="btn">Login with GitHub</a>

Email Verification

Enable verification:

MYFY_USER_REQUIRE_EMAIL_VERIFICATION=true

Users must verify email before full access. Verification link sent on registration.

Password Reset

1. User requests reset at /auth/forgot-password
2. Reset email sent with secure token
3. User clicks link to /auth/reset-password?token=...
4. User enters new password

Custom Templates

Override default templates by placing files in your templates directory:

frontend/templates/auth/
  login.html
  register.html
  forgot-password.html
  reset-password.html
  verify-email.html

Best Practices

1. Set a strong SECRET_KEY - Use a long random string
2. Enable email verification - For production apps
3. Use OAuth where possible - Reduces password management burden
4. Extend BaseUser - Don't modify it directly
5. Use sessions for web, JWT for API - Different use cases
6. Hash passwords - UserService handles this automatically
7. Rate limit auth routes - Prevent brute force attacks