Copy page

Backend

Auth Router: Login, Token Refresh, and User Management API

Auth Router: Login, Token Refresh, and User Management API

Relevant source files

The following files were used as context for generating this wiki page:

• src/modules/auth/casdoor-api-client.ts
• src/modules/auth/router.ts
• src/modules/auth/user-profiles-dal.ts
• src/modules/auth/user_profile_entity.ts

The Auth Router provides a centralized interface for authentication proxying and user profile management. It bridges the gap between the external Identity Provider (Casdoor) and the internal application state, implementing Just-In-Time (JIT) provisioning to ensure that every authenticated identity has a corresponding internal uuid for audit and relational purposes.

Implementation Overview

The authentication system is designed to be IDP-agnostic within the core business logic while using Casdoor for credential management. The authRouter src/modules/auth/router.ts:24-42 initializes specialized services:

• CasdoorApiClient: Handles administrative operations (CRUD) against the Casdoor REST API src/modules/auth/casdoor-api-client.ts:42-53.
• UserProfilesDal: Manages the user_profiles table, which mirrors IDP identities src/modules/auth/user-profiles-dal.ts:67-74.
• AuditService: Records changes to user profiles and administrative actions src/modules/auth/router.ts:29-34.

Login Data Flow and Proxying

The /api/v1/auth/login endpoint src/modules/auth/router.ts:68-70 acts as a secure proxy to Casdoor's OAuth2 token endpoint. This pattern ensures that client_secret and client_id never leave the backend environment.

Login Sequence

1. Validation: The request body is validated against LoginBodySchema (username/password) src/modules/auth/router.ts:19-22.
2. Config Resolution: Auth settings are loaded from the database via loadAuthConfigFromDb src/modules/auth/router.ts:99-103.
3. Outbound Proxy: The backend performs a POST to Casdoor's /api/login/oauth/access_token using grant_type: password src/modules/auth/router.ts:113-141.
4. Error Mapping: Specific Casdoor errors (e.g., "too many failed attempts") are parsed and mapped to user-friendly messages src/modules/auth/router.ts:160-174.

Login Proxy Logic

Code
sequenceDiagram
    participant Client as "Web Client"
    participant API as "authRouter (Backend)"
    participant DB as "PostgreSQL (auth_config)"
    participant IDP as "Casdoor"

    Client->>API: POST /api/v1/auth/login (username, password)
    API->>DB: loadAuthConfigFromDb()
    DB-->>API: clientId, clientSecret, endpoint
    API->>IDP: POST /api/login/oauth/access_token (grant_type=password)
    IDP-->>API: Access Token + ID Token
    API-->>Client: 200 OK (JWT Payload)

Sources: src/modules/auth/router.ts:68-180, src/modules/auth/config-repo.ts:1-20

---

Token Refresh and JIT Provisioning

The /api/v1/auth/refresh endpoint src/modules/auth/router.ts:203-205 handles token renewal and ensures the internal user_profiles record is synchronized with the IDP.

Just-In-Time (JIT) Logic

When a token is refreshed or a user logs in, the system checks if the idp_code (the IDP's sub claim) exists in the user_profiles table src/modules/auth/user_profile_entity.ts:12-17.

• If missing: A new record is inserted with a fresh internal uuid src/modules/auth/user_profile_entity.ts:15.
• If present: The last_synced_at field is updated src/modules/auth/user_profile_entity.ts:75-77.

This mechanism prevents vendor-specific IDs (like Casdoor's org/user format) from leaking into business tables or audit logs, as all internal foreign keys reference the generated uuid src/modules/auth/user_profile_entity.ts:8-10.

Sources: src/modules/auth/router.ts:203-270, src/modules/auth/user_profile_entity.ts:1-20

---

User Management and Administrative API

The router provides a full suite of CRUD operations for user management, protected by RBAC permissions src/modules/auth/router.ts:316-320.

Endpoint	Permission	Description
GET /api/v1/auth/users	Permission.USER_LIST	Paginated list with filtering/search src/modules/auth/router.ts:316.
GET /api/v1/auth/users/:uuid	Permission.USER_READ	Detailed profile view with audit metadata src/modules/auth/router.ts:348.
PATCH /api/v1/auth/users/:uuid	Permission.USER_UPDATE	Update roles, status, or profile info src/modules/auth/router.ts:384.
DELETE /api/v1/auth/users/:uuid	Permission.USER_DELETE	Soft-delete a user profile src/modules/auth/router.ts:466.
POST /api/v1/auth/users/:uuid/restore	Permission.USER_RESTORE	Restore a soft-deleted user src/modules/auth/router.ts:494.

Administrative Data Flow

Code
graph TD
    subgraph "Auth Router"
        R[router.patch '/users/:uuid']
    end

    subgraph "Data Access Layer"
        DAL[UserProfilesDal.updateProfile]
        Repo[Repository.update]
    end

    subgraph "External Sync"
        CDC[CasdoorApiClient.updateUser]
    end

    R --> DAL
    DAL --> Repo
    DAL -.-> CDC
    Repo --> DB[("user_profiles table")]

Sources: src/modules/auth/router.ts:384-464, src/modules/auth/user-profiles-dal.ts:97-102, src/modules/auth/casdoor-api-client.ts:105-159

---

Profile Self-Service and Avatars

Users can manage their own profiles via the /api/v1/auth/me endpoint src/modules/auth/router.ts:275-277.

Avatar Generation

If a user does not have an avatar URL, the system generates initials and a background color based on their display_name src/modules/auth/router.ts:285-300.

• avatar_initials: Derived from the first letters of the display name.
• avatar_color: Deterministically generated from a hash of the user's ID or name to ensure consistency across sessions.

Profile Update Logic

When a user updates their profile (e.g., changing a display name), the UserProfilesDal performs a dual-write:

1. It updates the local user_profiles table using the Repository src/modules/auth/user-profiles-dal.ts:101.
2. It attempts to sync the change back to Casdoor via the CasdoorApiClient if credentials are available src/modules/auth/router.ts:436-456.

Sources: src/modules/auth/router.ts:275-314, src/modules/auth/user-profiles-dal.ts:97-102, src/modules/auth/casdoor-api-client.ts:105-131

---

Soft-Delete and Audit Trail

User profiles implement the IAuditableEntity interface src/modules/auth/user_profile_entity.ts:39.

• Soft-Delete: Uses the @DeletableField decorator on deleted_at and deleted_by src/modules/auth/user_profile_entity.ts:109-113.
• Audit Logging: Every change is captured by the AuditService. The UserProfilesDal includes a specialized getUserProfileAudit method that enriches the audit delta with display names for better readability src/modules/auth/user-profiles-dal.ts:183-205.

Sources: src/modules/auth/user_profile_entity.ts:94-114, src/modules/auth/user-profiles-dal.ts:211-260

---