OPENKNITv0.2.0Builder
All catalogue entries

01 / 07 Module catalogue detail

Identity module

Sign-in and account lifecycle flows, with roles assigned to user accounts.

Browse category: Application core

Open the builder Browse all modules

Choose the modules you want after opening the builder.

01 / Module overview

What this module does

Sign-in and account lifecycle flows, with roles assigned to user accounts.

Documented capabilities

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

Configuration highlights

  • JWT and auth security settings under bitecode.security.jwt.*

  • Frontend/backend app URLs used for redirects and email flows

  • User invite, confirmation, and reset URL path settings

02 / Implementation record

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.

Core flow source: backend/modules/identity/AGENTS.md

Continue exploring

PaymentWalletTransaction