accounts Accounts & Authentication

Author: Zhenyu Yang yangzhenyu@sust.edu.cn

Last updated: Apr 24, 2026

Corresponding API docs: Authentication & User Account API

accounts Code Entry

  • backend/apps/accounts/models/__init__.py

  • backend/apps/accounts/views/__init__.py

  • backend/apps/accounts/serializers/__init__.py

  • backend/apps/accounts/authentication.py

  • backend/apps/accounts/middleware.py

accounts Core Data

User

  • Inherits from AbstractUser.

  • Business fields include:

    • user_code

    • full_name

    • wxid

    • roles

    • status

    • student_class

    • totp_secret

    • is_totp_enabled

    • preferred_locale

    • auth_version

  • roles stores all roles assigned to the user.

  • current_role is not stored in the database; it is extracted at runtime from the JWT or request headers.

  • auth_version is used for token revocation; it increments on password, role, or status changes, automatically invalidating old tokens.

WebAuthn Tables

  • WebAuthnCredential: Stores registered security keys.

  • WebAuthnChallenge: Stores registration/login challenge values.

Authentication Flows

Email / Student ID / Staff ID Login

  • Entry: EmailLoginView

  • The identifier field accepts both email and user_code.

  • Passwords are first attempted to be decrypted via SM2; on failure, the fallback allows plaintext for compatibility.

  • If the user has TOTP enabled, a totp_code must also be submitted during login.

WeChat Mini Program Login

  • Entry: WeChatLoginView

  • Calls WeChat code2session and locates the user by wxid=open_id.

  • The mini program does not use cookies; it returns access/refresh tokens in the response body.

  • If the account has TOTP enabled, a totp_code is also required.

WebAuthn Login

  • Login options: WebAuthnLoginOptionsView

  • Login verification: WebAuthnLoginView

  • After successful login, same as email login: returns tokens and writes HttpOnly cookies.

TOTP

  • setup generates a secret key and provisioning_uri.

  • enable verifies the code and activates TOTP.

  • disable requires verifying the code again when TOTP is already enabled.

accounts Permission Boundaries

  • User list, user detail, user create/update/delete:

    • superadmin or secretary only.

  • Invite foreign teacher:

    • superadmin or secretary only.

  • Update roles:

    • superadmin only.

  • Update account status:

    • superadmin or secretary.

  • /auth/me:

    • All authenticated users can read and update their own language preference.

User Import

  • Entry: UserViewSet.import_users

  • superadmin / secretary only.

  • Uses user_code as the unique key.

  • Existing records are skipped without being overwritten.

  • Newly created users uniformly receive:

    • status="active"

    • set_unusable_password()

  • The Excel file only accepts basic identity fields; plaintext or hashed passwords are never written from the import file.

Implementation Highlights

  • CookieJWTAuthentication reads the Authorization header first, then falls back to the cookie.

  • CurrentRoleMiddleware validates that the current_role in the request belongs to user.roles; if invalid, it falls back to the default role.

  • On login or first access, if the user has no valid preferred_locale, the system auto-normalizes the Accept-Language header to zh-CN or en-US.

  • The foreign teacher email registration endpoint EmailRegisterView is an anonymous endpoint; the user is logged in immediately after creation.

  • SM2PublicKeyView distributes the public key to the frontend via /api/v1/accounts/sm2/public-key.