Admin Authentication Module

Overview Description

The Admin Authentication Module manages identity verification and session management for administrative users. It provides secure access to the administrative sections of the application using Firebase authentication, handling admin login flows and the specialized representative login capability that allows administrators to assume the identity of group members for support purposes.

Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components
    Client[Client Application]
    AuthController[AuthController]
    AuthService(AuthService)
    Firebase((Firebase Auth))
    UserDB[(users)]
    RoleDB[(roles)]
    SessionDB[(Cookie)]

    Client --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>Submit Admin Login</p>
        </div>
    ]
    Step1 --> AuthController

    AuthController --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>Validate Request</p>
        </div>
    ]
    Step2 --> AuthService

    AuthService --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>Verify Firebase Token</p>
        </div>
    ]
    Step3 --> Firebase

    Firebase --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>Return User Info</p>
        </div>
    ]
    Step4 --> AuthService

    AuthService --- Step5[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
            <p style='margin-top: 8px'>Find User</p>
        </div>
    ]
    Step5 --> UserDB

    AuthService --- Step6[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6</span>
            <p style='margin-top: 8px'>Check Admin Role</p>
        </div>
    ]
    Step6 --> RoleDB

    AuthService --- Step7[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>7</span>
            <p style='margin-top: 8px'>Create Auth Cookies</p>
        </div>
    ]
    Step7 --> SessionDB

    AuthService --- Step8[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>8</span>
            <p style='margin-top: 8px'>Generate Auth Cookie</p>
        </div>
    ]
    Step8 --> AuthController

    AuthController --- Step9[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>9</span>
            <p style='margin-top: 8px'>Return Response</p>
        </div>
    ]
    Step9 --> Client

    %% Styling
    style Client fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AuthController fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AuthService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style Firebase fill:#fcd9d9,stroke:#cc3333,stroke-width:2px
    style UserDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style RoleDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style SessionDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5 fill:transparent,stroke:transparent,stroke-width:1px
    style Step6 fill:transparent,stroke:transparent,stroke-width:1px
    style Step7 fill:transparent,stroke:transparent,stroke-width:1px
    style Step8 fill:transparent,stroke:transparent,stroke-width:1px
    style Step9 fill:transparent,stroke:transparent,stroke-width:1px

API: Admin Authentication API

Case Documentation

Case 1: Admin Login

Description

Administrator successfully logs in with valid credentials and appropriate role.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as AuthController
    participant Service as AuthService
    participant Firebase
    participant UserDB as users
    participant AdminRoleDB as admin_roles
    participant AdminRoleUserDB as admin_role_user
    participant GroupDB as groups
    participant GroupMemberDB as group_members
    participant GroupRoleDB as group_roles

    Note over Admin,API: Step 1: Submit Login
    Admin->>API: POST /api/v1/admin/auth/login (with firebase-token)
    
    Note over API,Service: Step 2: Process Login
    API->>Service: login(token, data)
    
    Note over Service,Firebase: Step 3: Verify Token
    Service->>Firebase: verifyIdToken(token)
    Firebase-->>Service: Return verified user info
    
    Note over Service,UserDB: Step 4: Find User
    Service->>UserDB: findByUid(uid)
    UserDB-->>Service: Return user data
    
    Note over Service,AdminRoleUserDB: Step 5: Check Admin Role
    Service->>AdminRoleUserDB: Check Admin Role 
    AdminRoleUserDB-->>Service: Return role data
    
    Note over Service,GroupDB: Step 6: Load Group Data
    Service->>GroupDB: Load group data
    GroupDB-->>Service: Return group data
    
    Note over Service,GroupMemberDB: Step 7: Load Group Member
    Service->>GroupMemberDB: Load group member
    GroupMemberDB-->>Service: Return group member data
    
    Note over Service,GroupRoleDB: Step 8: Load Group Role
    Service->>GroupRoleDB: Load group role
    GroupRoleDB-->>Service: Return group role data
    
    Note over Service,API: Step 9: Generate Auth Cookie
    Service->>Service: createAuthCookie(user)
    
    Note over API,Admin: Step 10: Return Response
    API-->>Admin: 200 OK with user data and cookies

Steps

Step 1: Submit Login

• Description: Admin submits login credentials
• Request: POST /api/v1/admin/auth/login
• Headers:
  • firebase-token: Token from Firebase authentication
• Validation:
  • Token presence check
  • Token format validation
  • Rate limiting check (5 attempts/minute)

Step 2: Process Login

• Description: Controller validates request and passes to service
• Action:
  • Extract token from header
  • Call authentication service for login process
  • Log login attempt

Step 3: Verify Token

• Description: Verify Firebase token authenticity
• Action:
  • Send token to Firebase for verification
  • Extract user information from verified token
  • Confirm authentication provider

Step 4: Find User

• Description: Locate user record in database
• Action:
  • Query database for user with matching Firebase UID
  • Verify user exists and is active
  • Load user relationships

Step 5: Check Admin Role

• Description: Verify user has admin privileges
• Action:
  • Check user's role assignments
  • Verify admin role is present
  • Validate role permissions

Step 6: Load Group Data

• Description: Retrieve group-related data
• Action:
  • Query database for group data
  • Verify group existence
  • Load group relationships

Step 7: Load Group Member

• Description: Retrieve group member data
• Action:
  • Query database for group member data
  • Verify group member existence
  • Load group member relationships

Step 8: Load Group Role

• Description: Retrieve group role data
• Action:
  • Query database for group role data
  • Verify group role existence
  • Load group role relationships

Step 9: Generate Auth Cookie

• Description: Create secure session cookie
• Action:
  • Generate authentication token
  • Create auth cookie with token
  • Set secure and httpOnly flags
  • Set appropriate domain and path

Step 10: Return Response

• Description: Send successful response to client
• Response:
  • Success: 200 OK with user data
  • Set cookies in response
  • Include user details in response body

Database Related Tables & Fields

erDiagram
    users {
        bigint id PK
        string name "User's full name"
        string email "User's email address (unique)"
        string uid "Firebase user ID (unique)"
        int status "Account status: 1: active, 0: inactive"
        boolean is_first_login "Flag indicating if user has completed first login"
        timestamp created_at
        timestamp updated_at
    }
    roles {
        bigint id PK
        string name "Role display name"
        string slug "Role identifier for permissions (unique)"
        timestamp created_at
        timestamp updated_at
    }
    admin_role_user {
        bigint user_id FK "Reference to users table"
        bigint role_id FK "Reference to roles table"
        timestamp created_at
        timestamp updated_at
    }

    users ||--o{ admin_role_user : has
    roles ||--o{ admin_role_user : has

Error Handling

• Log

  • Login failures logged to application logs
  • Role verification errors recorded
  • (Optional) Send slack message for security events

• Error Detail:

  Status Code	Error Message	Description
  401	"Login information is incorrect."	When credentials are invalid
  403	"No administrative privileges."	When user lacks admin role
  429	"Too many requests."	When rate limit exceeded
  401	Generic error with exception message	When unexpected errors occur

Case 2: Representative Login

Description

Administrator logs in as a representative of a group member.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as RepresentativeController
    participant Service as AuthService
    participant UserDB as Database
    participant SessionDB as Database

    Admin->>API: PATCH /api/v1/admin/auth/representative/{id}
    API->>Service: loginAsRepresentative(user_id)
    Service->>UserDB: findUserWithGroup(user_id)
    UserDB-->>Service: Return user data
    Service->>SessionDB: createRepresentativeSession(admin_id, user_id)
    SessionDB-->>Service: Return session data
    Service->>Service: generateRepresentativeCookie
    API-->>Admin: 200 OK with cookies

Steps

Step 1: Submit Representative Request

• Description: Admin requests to act as representative
• Request: PATCH /api/v1/admin/auth/representative/{id}
• Body Parameters:
  • user_id: ID of user to represent
• Validation:
  • Admin authentication check
  • User existence verification
  • Group membership validation

Step 2: Process Representative Login

• Description: Create representative session
• Action:
  • Verify admin permissions
  • Check user's group membership
  • Create representative context

Step 3: Create Representative Session

• Description: Store representative session data
• Action:
  • Generate session identifier
  • Link admin and user records
  • Set session expiration
  • Log representative access

Step 4: Generate Cookies

• Description: Create representative session cookies
• Action:
  • Generate representative token
  • Create secure cookies
  • Set appropriate flags and expiration

Step 5: Return Response

• Description: Send success response
• Response:
  • Success: 200 OK with user data
  • Set representative cookies
  • Include user details

Additional Notes

• Rate limiting: Admin login attempts are limited to 5 per minute per IP address
• Session expiration: Admin sessions expire after 8 hours of inactivity
• Representative sessions expire after 1 hour
• The system maintains audit logs of all admin and representative actions
• Consider implementing:
  • Two-factor authentication for admin access
  • IP-based access restrictions
  • Activity monitoring and alerts
  • Session activity tracking

Module Features