Skip to content

ChatLogin Documentation

0.2.1 new-service path: Complete factory, account discovery, and gear/links navigation.

ChatLogin makes the backend security contract for website login reusable in Python while leaving presentation under host control. Use the packaged page, override templates/CSS, or keep an existing HTML/vanilla-JS frontend and use the headless JSON API.

Site entry: https://arch.gh.wzhecnu.cn/ChatLogin/en/

Choose Documentation by Scenario

  • FastAPI integration

    Install the web extra and mount configurable auth routes, dependencies, and an optional page.

    Open Integration and Security

  • Run the packaged product demo

    Start four real backend families, three frontend modes, and the template playground from the installed wheel.

    Open Demo Guide

  • Application-managed users

    For owner/admin/user accounts, management pages, and self-service profiles, use ManagedUsers and the default FastAPI preset while keeping business-data authorization in the host.

    Open Managed Users

  • Keep an existing visual style

    Choose packaged UI, host template overrides, or a fully headless host-owned frontend.

    Open Capability Map

  • Review CLI and package boundaries

    The CLI exposes version, command trees, read-only paths, first-owner bootstrap, and default or managed isolated serve demos; reusable auth remains a Python API.

    Open CLI Tree

Install

python -m pip install "ChatLogin[web]"

To run only the packaged interactive site:

python -m pip install "ChatLogin[demo]"
chatlogin serve

It binds only 127.0.0.1:8765 by default. Its public synthetic identity, short bounded sessions, and disposable schema fixture are demonstration-only; this is not a production login microservice. See Demo and Quick Start.

The smallest FastAPI integration uses either synthetic accounts or a host-provided callback. There is no built-in production password.

from fastapi import Depends, FastAPI
import os
from chatlogin import PasswordBackend, MemorySessionStore, Principal, SessionManager, hash_password
from chatlogin.fastapi import CookieSettings, FastAPIAuth
from chatlogin.ui import LoginUI

backend = PasswordBackend({
    "demo": (Principal("usr_1", "Demo user"), hash_password(os.environ["EXAMPLE_LOGIN_PASSWORD"]))
})
auth = FastAPIAuth(
    backend,
    SessionManager(MemorySessionStore(), instance="my-site"),
    origin="https://www.example.com",
    prefix="/api/auth",
    ui=LoginUI(title="My site"),
    cookie=CookieSettings(name="my_site_session"),
)
app = FastAPI()
app.include_router(auth.router)

@app.get("/private")
def private(principal=Depends(auth.current_user)):
    return principal.as_dict()

See examples/demo_fastapi.py for a runnable synthetic-account demo.

For application-managed accounts, new consumers explicitly require ChatLogin>=0.2.0,<0.3.0, let an operator run chatlogin users bootstrap with an environment-variable name, then mount create_managed_auth(instance=..., origin=...). It does not migrate old user stores or replace host require_owner business authorization; see Managed Users.

Three Frontend Levels

Level Best for Security boundary
Default UI New sites Packaged HTML/CSS/JS, palettes, and layouts with the same opaque-cookie backend
Host override Brand or partial/full page customization Jinja choice loading, block inheritance, and local custom CSS without editing site-packages
Headless Existing static HTML/vanilla-JS apps such as ChatVoice No default page or assets; only /login, /session, and /logout JSON contracts

Themes affect presentation only. They cannot weaken CSRF, cookies, roles, or owner checks. Default resources use scoped .chatlogin classes and CSS variables rather than global resets.

Secure Defaults

  • Server-trusted identities are guest, user, and admin, plus managed-preset owner; login payloads cannot escalate role.
  • Credential verification is injectable: fixed account, multiple accounts, or a host callback. Existing PBKDF2 material can be verified without forced migration.
  • Session tokens are random; only SHA-256 digests are stored. Expiry, rotation, revocation, and instance isolation are supported.
  • Cookies default to HttpOnly, Secure, and SameSite=Lax; cookie-authenticated writes require same-site Origin and CSRF.
  • next accepts only local absolute paths; login bodies are bounded and rate limited.
  • Roles do not bypass resource ownership, including admin.