AuthService Sequence Diagrams

This document contains the sequence diagrams for the core functionalities of the AuthService, illustrating the interaction between the different components of the system.

1. User Authentication Flow (AuthenticateUser)

This diagram shows the sequence for a user attempting to log in. It covers both successful and failed authentication attempts, including the logic for incrementing failure counts, account lockout, and creating audit logs.

sequenceDiagram
    participant User
    participant Frontend
    participant AuthService
    participant Database

    User->>Frontend: Submits email and password
    Frontend->>AuthService: gRPC: AuthenticateUser(email, password)
    AuthService->>Database: SELECT user record by email (incl. hash, status, attempts)
    Database-->>AuthService: Returns user record

    alt Login Success (User is Active and password matches)
        AuthService->>Database: UPDATE user (reset failed_login_attempts = 0)
        AuthService->>Database: INSERT into sessions table (create session token)
        AuthService->>Database: INSERT into audit_logs (event: USER_LOGIN_SUCCESS)
        Database-->>AuthService: Confirm operations
        AuthService-->>Frontend: Returns { success: true, sessionToken }
        Frontend->>User: Redirects to Dashboard
    else Login Failure (Password mismatch or user not Active)
        AuthService->>Database: UPDATE user (increment failed_login_attempts)
        note right of AuthService: If attempts > threshold, set status = LockedOut.
        AuthService->>Database: INSERT into audit_logs (event: USER_LOGIN_FAILURE)
        Database-->>AuthService: Confirm operations
        AuthService-->>Frontend: Returns { success: false, error: "Invalid credentials" }
        Frontend->>User: Displays error message on login page
    end

2. Permission Check Flow (CheckPermission)

This diagram illustrates how the system checks if a user has the necessary permission to access a resource or perform an action. This is a critical flow for enforcing security throughout the application.

sequenceDiagram
    participant User
    participant Frontend
    participant AuthService
    participant Database

    User->>Frontend: Clicks on a protected link (e.g., User Management)
    Frontend->>AuthService: gRPC: CheckPermission(sessionToken, permission: 'admin:user:list')

    AuthService->>Database: SELECT user_id from sessions WHERE token is valid
    Database-->>AuthService: Returns user_id

    alt Session is Valid
        AuthService->>Database: Query for user's direct permissions
        AuthService->>Database: Query for user's roles
        AuthService->>Database: Query for user's groups
        note right of AuthService: Complex queries to resolve permissions from roles and groups.
        Database-->>AuthService: Returns all permission-related data

        AuthService->>AuthService: Calculate effective permissions set

        alt Permission Granted
            AuthService-->>Frontend: Returns { granted: true }
            Frontend->>User: Renders the User Management page
        else Permission Denied
            AuthService-->>Frontend: Returns { granted: false }
            Frontend->>User: Redirects to "Access Denied" page
        end

    else Session is Invalid or Expired
        AuthService-->>Frontend: Returns "Unauthenticated" error
        Frontend->>User: Redirects to Login page
    end

3. Admin Creates User Flow (CreateUser)

This diagram shows the sequence of events when an administrator creates a new user account. It includes permission checks, data validation, and auditing.

sequenceDiagram
    participant Admin
    participant Frontend
    participant AuthService
    participant Database

    Admin->>Frontend: Submits "Add User" form data
    Frontend->>AuthService: gRPC: CreateUser(adminSessionToken, newUserDetails)

    note over AuthService: First, check if the Admin has 'admin:user:create' permission.
    AuthService->>AuthService: Internal call to CheckPermission logic

    alt Admin is Authorized
        AuthService->>Database: SELECT 1 FROM users WHERE email = newUserDetails.email
        Database-->>AuthService: Returns result (to check for duplicates)

        alt Email is Unique
            AuthService->>Database: INSERT into users table
            AuthService->>Database: INSERT into user_roles table for each assigned role
            AuthService->>Database: INSERT into audit_logs (event: USER_CREATED, actor: admin, target: newUser)
            Database-->>AuthService: Confirm operations
            AuthService-->>Frontend: Returns { success: true, userId: new_user_id }
            Frontend->>Admin: Displays success message and redirects to user list
        else Email Already Exists
            AuthService-->>Frontend: Returns { success: false, error: "Email already exists" }
            Frontend->>Admin: Displays error message on the form
        end
    else Admin is Not Authorized
        AuthService-->>Frontend: Returns "Permission Denied" error
        Frontend->>Admin: Redirects to "Access Denied" page
    end