Auth Scaffold
Lila can generate the authentication routes, templates, models and main.py wiring with one
command (Auth 2.0). Generated files are written with a .bak backup when an existing
file would change, and migrations run without --refresh so existing users are never
dropped.
Features (Auth 2.0)
- OAuth: Google, GitHub and Discord with official SVG icons; the callback checks that the provider reports a verified email before creating or logging in a user.
- Password hashing: Argon2id (OWASP parameters) via
PasswordHasher, with a nativescryptfallback when argon2-cffi is not installed. Async helpers (hash_async/verify_async) run in a worker thread. - Login lockout: 5 failed attempts lock the account for 5 minutes; login, register and reset endpoints are also per-IP throttled.
- Password reset: only the SHA-256 hash of the reset token is stored; the email is sent through SMTP when configured, and in debug the reset URL is printed to the console.
- Sessions: only
user_id/email/name/avatarare stored in the signed cookie — never password hashes. - SPA navigation: integrated with
lila-client.jsand View Transitions. - Generates routes:
/login,/register,/forgot-password,/change-password,/invalid-token, plus the dashboard/profile pages and OAuth callbacks.
Running Auth Scaffold
Use the unified CLI or the standalone script:
# Unified CLI (or: lila-auth)
lila auth
# Templates only / routes only
lila auth --no-routes
lila auth --no-templates
# Apply the new tables/columns
lila migrate
The scaffold creates app/routes/web/auth/ (login, register, logout, forgot-password,
change-password), app/routes/web/authenticated/ (dashboard, profile), the
User model plus LoginAttempt/PasswordResetToken models, and
auth templates under resources/html/auth/ and
resources/html/authenticated/.
OAuth Configuration (.env)
Provide your client credentials in .env and set
APP_URL (the callback URL is built from it):
APP_URL="https://example.com"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
DISCORD_CLIENT_ID="your-discord-client-id"
DISCORD_CLIENT_SECRET="your-discord-client-secret"
Register these redirect URIs with each provider:
https://example.com/auth/google/callback
https://example.com/auth/github/callback
https://example.com/auth/discord/callback
Mounting OAuth Manually
The scaffold mounts the routes for you; if you add OAuth to an existing project, mount them yourself in one line:
from lila.core.oauth import OAuth
from lila.core.routing import Router
from app.models.user import User
router = Router()
OAuth.mount_routes(
router,
user_model=User,
redirect_to="/dashboard",
login_url="/login",
)
Rendering OAuth Buttons in Templates
Use the built-in Jinja helper anywhere in your templates. It auto-detects the providers whose client id and secret are configured:
<!-- Auto-detects configured providers and renders Tailwind SVG buttons -->
{{ oauth_buttons() | safe }}
<!-- Customize label and provider list -->
{{ oauth_buttons(providers=['google', 'github'], label_prefix='Sign in with') | safe }}
Password Hashing & JWT in Your Code
from lila.core.auth import PasswordHasher, JWT
async def login_example(password: str) -> str:
# Argon2id (scrypt fallback if argon2-cffi is missing)
hashed = await PasswordHasher.hash_async(password)
ok = await PasswordHasher.verify_async(hashed, password)
# Rehash opportunity after a successful login
if ok and PasswordHasher.needs_rehash(hashed):
hashed = await PasswordHasher.hash_async(password)
# JWT for API clients (validate with @validate_token)
token = JWT.encode({"user_id": 1}, minutes=60)
payload = JWT.decode(token) # None when invalid/expired
return hashed
CACHE_DRIVER=redis if you run multiple workers; and always set a strong
SECRET_KEY in production (lila secret-key).