Identity module

Authentication and account lifecycle foundation for apps that need secure sign-in, user management, and access rules.

Generate with OpenKnitBrowse other modules

What this module does

Auth, users, roles, and access control.

Key capabilities

  • Login, logout, refresh tokens, and session lifecycle
  • User registration, verification, password reset, and profile flows
  • MFA, OAuth2 sign-in, and admin user management

Core flows

  1. Sign-in and token issue

    • Trigger: POST /oauth/login
    • Steps: validate credentials, enforce email verification and MFA, mint refresh token, mint access token, set refresh cookie.
    • Output: SignInResponse with access token and user details.
    • Failure/edge cases: unverified email, invalid MFA code, unsupported MFA method, auth failure.

  2. Access token refresh

    • Trigger: POST /oauth/tokens/access with refreshTokenId cookie.
    • Steps: validate refresh token UUID and expiry/revocation, load user, mint access token.
    • Output: RefreshTokenResponse.
    • Failure/edge cases: missing cookie, revoked/expired token, missing user.

  3. User registration and email verification

    • Trigger: POST /users then POST /users/confirmations/{verificationCode}.
    • Steps: create user+default role+userData, send verification email with code, confirm and mark emailConfirmed=true.
    • Output: registered/confirmed user account.
    • Failure/edge cases: existing account, rate-limited verification requests, invalid confirmation code.

  4. MFA setup and login verification

    • Trigger: PUT /users/mfa and login with MFA-enabled account.
    • Steps: configure EMAIL/QR TOTP method, issue verification challenge on login, validate code.
    • Output: MFA-enabled sign-in.
    • Failure/edge cases: bad code, unsupported method, QR generation errors.

  5. Forgotten password recovery

    • Trigger: POST /users/passwords/recovery/{username} and POST /users/passwords/recovery.
    • Steps: generate one-time verification token, email reset link, verify token, update hashed password.
    • Output: password reset completed.
    • Failure/edge cases: unknown user, invalid/expired code, email send failure.

  6. OAuth2 sign-in and account linking

    • Trigger: OAuth2 success callback.
    • Steps: resolve provider identity, link to existing user or create new confirmed user, issue refresh cookie, redirect with access token.
    • Output: authenticated user session.
    • Failure/edge cases: unsupported provider, malformed provider attributes.

  7. Admin user management

    • Trigger: /admin/users endpoints.
    • Steps: search/filter users, fetch statistics, invite/create user with role and temp password.
    • Output: admin-managed account lifecycle.
    • Failure/edge cases: duplicate email, unknown role.

Module is included in

  • Subscription Access: Create plans, manage subscriptions, and control what users can see or use.
  • Value Ledger: Record value movements with clear entries, timestamps, and a complete audit trail.
  • Tradebook: Track transfers and swaps between parties, assets or resources.
  • AI assistant: AI assistant, vector store, ingestion, and admin tooling.
  • Included by default in the custom modules generator flow.

Source paths

  • backend/modules/identity
  • frontend/modules/identity