User Authentication and Sessions

Relevant source files

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

• app.py
• templates/admin_login.html
• static/openapi.yaml
• templates/admin_dashboard.html
• SECURITY.md
• qr_sync.py

The Smart Absen application employs two distinct authentication mechanisms to secure different parts of the system. The first is a traditional username and password system for administrators to access the management dashboard. The second is a temporary, session-based QR code synchronization system designed to authorize devices for marking attendance.

Both systems rely on the Flask session object, which is a client-side, cryptographically signed cookie. The security of this session is dependent on the SECRET_KEY configured for the application. This document details the architecture and implementation of both authentication schemes and the session management that underpins them.

Admin Authentication

Admin authentication provides access to the administrative backend, where an admin can manage employees, view attendance records, and configure the system. This is a role-based system, although the current implementation uses a hardcoded dictionary for credentials.

Sources: app.py:168-181, 804-820, templates/admin_login.html

Mechanism

Authentication is handled by checking submitted credentials against a hardcoded dictionary ADMIN_CREDENTIALS in app.py.

# app.py:168-172
ADMIN_CREDENTIALS = {
    'admin': 'admin123',
    'supervisor': 'super123'
}

Sources: app.py:168-172

Upon a successful credential match, two keys are set in the Flask session: admin_logged_in (as True) and admin_username.

Admin Login Flow

The following diagram illustrates the sequence of events during an admin login attempt.

Sources: app.py:804-820, templates/admin_login.html

Session Protection

Admin-only routes are protected by the @admin_required decorator. This decorator checks for the presence of admin_logged_in in the session. If the key is not present, the user is redirected to the login page.

# app.py:174-181
def admin_required(f):
    """Decorator untuk memerlukan login admin"""
    @wraps(f)
    def decorated_function(*args, **kwargs):
        if 'admin_logged_in' not in session:
            return redirect(url_for('admin_login'))
        return f(*args, **kwargs)
    return decorated_function

Sources: app.py:174-181

The following diagram shows the logic of the @admin_required decorator.

Sources: app.py:174-181

Logout

The /admin/logout route removes the admin_logged_in and admin_username keys from the session, effectively logging the user out.

Sources: app.py:822-827

QR Code Device Authentication

This is a stateless, temporary authentication mechanism used to authorize a device (e.g., a laptop with a webcam) to access the attendance page (/web_attendance). It works by synchronizing a primary device (displaying the QR) with a secondary device (scanning the QR, typically a mobile phone).

Sources: app.py:73-101, 400-601, qr_sync.py

Core Concepts

Component	Description	Source File
unit_code	A short-lived (10 min), time-based, unique code. It's the central token for the authentication handshake.	app.py:80-91
QR Code	A visual representation of a URL containing the current unit_code.	app.py:93-110
qr_sync_manager	An in-memory object that tracks verified unit_codes from scanning devices.	qr_sync.py
Flask Session	Used on the primary device to store the qr_verified status after a successful handshake.	app.py:461-468

Authentication Flow

The QR authentication process is a multi-step handshake between the primary device (laptop) and the secondary device (mobile phone), orchestrated by the server.

Sources: app.py:400-601, [qr_sync.py]

Session Protection

Access to the /web_attendance page is guarded by the @qr_verification_required decorator. It performs two checks:

1. Ensures session['qr_verified'] is True.
2. Checks if the verification timestamp (session['qr_verified_time']) is within the 10-minute validity period.

If either check fails, the user is redirected back to the /auth page.

Sources: app.py:604-633

Session Management

The application uses Flask's default session implementation, which stores session data in a cryptographically signed cookie on the client-side. The app.secret_key is critical for securing this data.

Sources: app.py:44, [SECURITY.md]

Key Session Variables

Session Key	Purpose	Authentication System	Set In	Checked In
admin_logged_in	Flag indicating a valid admin session.	Admin	/admin/login	@admin_required
admin_username	Stores the username of the logged-in admin.	Admin	/admin/login	/admin/profile
qr_verified	Flag indicating a successful QR handshake.	QR Code	/verify, /api/accept_qr_sync	@qr_verification_required
qr_verified_time	ISO format timestamp of when QR verification occurred.	QR Code	/verify, /api/accept_qr_sync	@qr_verification_required
verified_unit_code	The unit_code that was successfully verified.	QR Code	/verify, /api/accept_qr_sync	/api/qr_sync_status
qr_session_consumed	A unique key to prevent re-using a single QR scan for multiple attendance sessions.	QR Code	/api/accept_qr_sync	/api/qr_sync_status
attendance_completed_time	Timestamp to create a grace period after attendance, preventing immediate re-sync.	QR Code	/api/clear_qr_session	/api/qr_sync_status

Sources: app.py

API Endpoints

The following API endpoints are central to the authentication systems.

Method	Endpoint	Description	Auth System
POST	/admin/login	Authenticates an admin user and creates a session.	Admin
GET	/admin/logout	Clears the admin session.	Admin
GET	/auth	Displays the QR code authentication page.	QR Code
GET	/verify	Verifies a unit_code from a scanning device.	QR Code
GET	/api/qr_sync_status	Polling endpoint for the primary device to check for a successful scan.	QR Code
POST	/api/accept_qr_sync	Called by the primary device to finalize the handshake and verify its own session.	QR Code
POST	/api/clear_qr_session	Clears the QR session state after attendance is complete.	QR Code

Sources: static/openapi.yaml, app.py

Summary

User authentication in this project is twofold. A standard, persistent session model is used for administrators, granting access to the backend based on a username/password login. For the primary user-facing feature—attendance—a more dynamic, temporary authentication model is used. This QR-based system acts as a secure, time-limited "key" to authorize a specific device session for the sensitive task of face capture, without requiring the end-user to have a permanent account. Both systems leverage the Flask session cookie, making the application's SECRET_KEY a cornerstone of its security.