How to Add Authentication to GPT Academic: A Complete Guide

GPT Academic includes a built-in username-password authentication system that you can activate by populating the AUTHENTICATION list in config.py or setting the GPT_ACADEMIC_AUTHENTICATION environment variable.

GPT Academic is an open-source LLM interaction framework that provides a Gradio-based web interface for academic paper processing and translation. By default, the application runs without authentication, but the codebase includes a complete access control layer that protects the UI and sensitive user files. This guide explains how to enable and configure authentication using the native mechanisms found in the source code.

Understanding GPT Academic's Built-In Authentication System

The authentication architecture relies on four core components that work together to secure the FastAPI/Gradio application:

Component	Location	Function
AUTHENTICATION	config.py (lines 199-203)	Stores a list of (username, password) tuples. When non-empty, it triggers the login screen.
_authorize_user	shared_utils/fastapi_server.py (lines 72-90)	Validates request cookies (access-token / access-token-unsecure) against the token store and verifies file access permissions.
start_app	shared_utils/fastapi_server.py (lines 120-147)	Wires authentication into the FastAPI stack, replaces file routes with protected wrappers, and sets app_block.auth to enable the Gradio login dialog.
main.py	main.py (lines 50-55)	Retrieves the AUTHENTICATION value from the configuration loader and passes it to start_app.

When AUTHENTICATION contains valid credentials, start_app automatically sets app_block.auth_message = '请登录' (Please log in) and configures Gradio to render the authentication modal before granting access to the interface.

How to Enable Authentication in GPT Academic

You can activate authentication using either the configuration file or environment variables. The configuration loader in shared_utils/config_loader.py prioritizes environment variables over config.py values, making environment variables ideal for production deployments.

Method 1: Configure via config.py

Edit the AUTHENTICATION list in config.py to define allowed users:

# config.py – around line 199

AUTHENTICATION = [
    ("admin", "StrongP@ssw0rd123"),
    ("researcher1", "SecurePass456"),
    ("student_a", "UserPass789"),
]

Save the file and restart the application. The Gradio interface will now display a login screen before loading the main UI.

Method 2: Use Environment Variables (Recommended)

For Docker deployments or shared servers, set the GPT_ACADEMIC_AUTHENTICATION environment variable to avoid committing credentials to version control:

export GPT_ACADEMIC_AUTHENTICATION='[("admin","StrongP@ssw0rd123"),("user2","Pass456")]'
python main.py

Or using Docker:

docker run -e GPT_ACADEMIC_AUTHENTICATION='[("admin","StrongP@ssw0rd123")]' -p 7860:7860 gpt_academic

The config_loader.py module parses this string into the same list structure used by config.py, ensuring consistent behavior across deployment methods.

How the Authentication Flow Protects Your Data

Once enabled, the authentication system secures two critical areas: the Gradio UI and file system access.

UI Protection

When start_app detects a non-empty AUTHENTICATION list, it assigns the credentials to app_block.auth. Gradio then intercepts all incoming requests and presents a login modal. Successful authentication stores two cookies in the browser:

• access-token: The secure session token
• access-token-unsecure: A fallback identifier

File Access Control

The _authorize_user function in fastapi_server.py (lines 72-90) validates every request to /file/ endpoints. It performs two checks:

1. Verifies the request contains valid cookies from the Gradio token store
2. Ensures the requested file path resides within the user's private upload directory (PATH_PRIVATE_UPLOAD) or the logging directory (PATH_LOGGING)

If either check fails, the function returns "越权访问!" (Unauthorized access) and blocks the request. This prevents users from accessing other users' uploaded files or sensitive system logs.

Programmatic Access and API Authentication

For automated scripts or API clients, you must handle the authentication flow programmatically. The following Python example demonstrates logging in and accessing protected files:

import requests

BASE_URL = "http://localhost:7860"

# Step 1: Retrieve the login page to establish session context

session = requests.Session()
login_page = session.get(f"{BASE_URL}/").text

# Step 2: Submit credentials to the Gradio login endpoint

# Note: The exact endpoint may vary based on Gradio version; 

# typically it posts to the root or a /login path

resp = session.post(
    f"{BASE_URL}/login",
    data={"username": "admin", "password": "StrongP@ssw0rd123"},
    allow_redirects=True
)

# Step 3: Access protected resources using the session cookies

# The session object automatically handles the access-token cookie

file_response = session.get(f"{BASE_URL}/file/private_upload/admin/report.pdf")
print(file_response.status_code)  # Should be 200 if authorized

To log out and clear the session:

# Step 4: Logout to invalidate the session

session.get(f"{BASE_URL}/academic_logout")

Summary

• GPT Academic includes built-in authentication controlled by the AUTHENTICATION variable in config.py or the GPT_ACADEMIC_AUTHENTICATION environment variable.
• Enable security by populating the authentication list with (username, password) tuples and restarting the server; Gradio automatically renders a login modal.
• File protection is enforced by _authorize_user in fastapi_server.py, which validates cookies and restricts access to private upload and logging directories.
• Environment variables are the recommended approach for production deployments to avoid committing credentials to version control.

Frequently Asked Questions

Where is the AUTHENTICATION variable defined in GPT Academic?

The AUTHENTICATION variable is defined in config.py at lines 199-203. It defaults to an empty list [], which means no authentication is required. The configuration loader in shared_utils/config_loader.py also checks for the environment variable GPT_ACADEMIC_AUTHENTICATION, which takes precedence over the value in config.py if set.

Can I use external SSO providers like OAuth or LDAP with GPT Academic?

The current implementation in shared_utils/fastapi_server.py uses a simple cookie-based token system managed by Gradio. To use external SSO providers, you would need to modify the _authorize_user function (lines 72-90) to validate JWT tokens or session tickets from your identity provider instead of checking Gradio's token store. The rest of the file route protection mechanism would remain the same.

How do I disable authentication in GPT Academic?

To disable authentication, set AUTHENTICATION = [] in config.py or unset the environment variable GPT_ACADEMIC_AUTHENTICATION. When the list is empty, the start_app function in fastapi_server.py (lines 120-147) skips the authentication setup, leaving file routes unprotected and allowing direct access to the Gradio interface without a login screen.

What files and routes are protected when authentication is enabled?

When authentication is active, the _authorize_user function protects all routes under /file/. Specifically, users can only access files within their private upload directory (PATH_PRIVATE_UPLOAD) and the logging directory (PATH_LOGGING). The system checks the access-token cookie against Gradio's token store and verifies the requested file path belongs to the authenticated user, returning "越权访问!" (unauthorized access) for any invalid requests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}