Admin Logout

Overview Description

The Admin Logout feature provides a secure mechanism for terminating administrative user sessions within the application. When an administrator logs out, the system invalidates their authentication tokens, clears session data, and removes authentication cookies from the browser. The process handles both regular admin sessions and specialized representative sessions, ensuring complete removal of all authentication traces for security purposes.

Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TD
    %% Main components
    AdminUser[Admin User]
    
    %% Process steps with numbering
    AdminUser --- 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'>Initiate Logout</p>
        </div>
    ]
    Step1 --> SendRequest[Send Logout Request]
    
    SendRequest --- 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'>Process Request</p>
        </div>
    ]
    Step2 --> ProcessRequest[Server Processes Logout]
    
    ProcessRequest --- 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'>Invalidate Session</p>
        </div>
    ]
    Step3 --> InvalidateSession[Invalidate Admin Session]
    
    InvalidateSession --- 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'>Clear Representative</p>
        </div>
    ]
    Step4 --> ClearRepresentative[Invalidate Representative Session]
    
    ClearRepresentative --- 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'>Clear Cookies</p>
        </div>
    ]
    Step5 --> ClearCookies[Clear Authentication Cookies]
    
    ClearCookies --- 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'>Clear Rep Cookies</p>
        </div>
    ]
    Step6 --> ClearRepCookies[Clear Representative Cookies]
    
    ClearRepCookies --- 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'>Clear State</p>
        </div>
    ]
    Step7 --> ClearState[Clear State Cookies]
    
    ClearState --- 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'>Return Response</p>
        </div>
    ]
    Step8 --> ReturnResponse[Return Success Response]
    
    ReturnResponse --- 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'>Redirect</p>
        </div>
    ]
    Step9 --> Redirect[Redirect to Login Page]
    
    %% Styling
    style AdminUser fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style SendRequest fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ProcessRequest fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style InvalidateSession fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ClearRepresentative fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ClearCookies fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ClearRepCookies fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ClearState fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ReturnResponse fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style Redirect fill:#f0f8e6,stroke:#339933,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 Logout API

Case Documentation

Case 1: Successful Admin Logout

Description

Administrator successfully logs out of the application and all session data is cleared.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as LogoutController
    participant Auth as AuthService
    participant Cookie as CookieService

    Note over Admin,API: Step 1: Initiate Logout
    Admin->>API: GET /api/v1/admin/auth/logout
    
    Note over API,Auth: Step 2: Invalidate Admin Session
    API->>Auth: logout()
    Auth->>Auth: invalidate main session
    
    Note over API,Auth: Step 3: Invalidate Representative Session
    API->>Auth: logout('representative')
    Auth->>Auth: invalidate representative session
    
    Note over API,Cookie: Step 4: Clear Auth Cookies
    API->>Cookie: forget(auth_api_token)
    API->>Cookie: forget(is_logged_in)
    API->>Cookie: forget(representative)
    
    Note over API,Admin: Step 5: Return Response
    API-->>Admin: 200 OK with cookies cleared

Steps

Step 1: Initiate Logout

• Description: Administrator requests to log out of the application
• Request: GET /api/v1/admin/auth/logout
• Headers:
  • Authorization cookies automatically included

Step 2: Invalidate Admin Session

• Description: Clear the main admin authentication session
• Action:
  • Call Auth facade's logout method
  • Remove admin from authenticated users list
  • Invalidate session token

Step 3: Invalidate Representative Session

• Description: Clear any representative session if present
• Action:
  • Call Auth facade's logout method on representative guard
  • Remove representative context if active

Step 4: Clear Auth Cookies

• Description: Remove all authentication cookies from client
• Action:
  • Create "forget" cookie instances for:
    • Auth API token cookie
    • Logged-in state cookie
    • Representative cookie
  • Set cookie expiration to past date
  • Ensure cookies use same domain/path as originals

Step 5: Return Response

• Description: Send success response with cookie clearing instructions
• Response:
  • Success: 200 OK with success message
  • Attach cookie clearing instructions to response
  • Clear cookie headers properly formatted for browser

Error Handling

• Log

  • Logout errors logged to application logs
  • Exception details recorded for debugging

• Error Detail:

  Status Code	Error Message	Description
  401	Generic error with exception message	When unexpected errors occur during logout

Case 2: Session Flush (Fallback)

Description

If normal logout fails, a session flush is performed to ensure session data is cleared.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as LogoutController
    participant Session

    Admin->>API: GET /api/v1/admin/auth/logout
    API->>API: try normal logout
    Note over API: Exception occurs
    API->>Session: flush()
    API-->>Admin: 401 Unauthorized with error message

Steps

Step 1: Attempt Normal Logout

• Description: System attempts standard logout procedure
• Action: Same as successful case

Step 2: Handle Exception

• Description: Catch and handle any exceptions during logout
• Action:
  • Catch exception in try/catch block
  • Log exception details

Step 3: Emergency Flush

• Description: Force clear all session data
• Action:
  • Call session flush method
  • Ensure all session data is removed

Step 4: Error Response

• Description: Inform client of logout issues
• Response:
  • Error: 401 Unauthorized with exception message

Additional Notes

• Logout is designed to work consistently regardless of whether the admin is in standard or representative mode
• Cookies are domain-specific according to configuration settings
• The system handles both expected and unexpected logout scenarios
• Session flushing is used as a last resort to ensure security when normal logout fails
• After logout, administrators are typically redirected to the login page by the client application

Database Related Tables & Fields

erDiagram
    users {
        id bigint "Primary key"
        name string "User's full name"
        email string "User's email address (unique)"
        uid string "Firebase UID (unique)"
        payment_provider_customer_id string "Payment provider customer ID (nullable)"
        status int "Account status (0: Inactive, 1: Active)"
        is_first_login int "First login flag (0: not yet, 1: logged in)"
        remember_token string "Remember token"
        created_at timestamp "Record creation timestamp"
        updated_at timestamp "Record last update timestamp"
        deleted_at timestamp "Soft delete timestamp"
    }
    admin_roles {
        id bigint "Primary key"
        name string "Role name"
        slug string "Role slug"
        created_at timestamp "Record creation timestamp"
        updated_at timestamp "Record last update timestamp"
    }
    admin_role_user {
        admin_role_id bigint "Reference to admin_roles table"
        user_id bigint "Reference to users table"
        created_at timestamp "Record creation timestamp"
        updated_at timestamp "Record last update timestamp"
    }

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