When you build a desktop application with PyQt6 or PySide6, sooner or later you'll need to control who can use it and what they can do. Maybe your app connects to a cloud service. Maybe certain features should only be available to administrators. Either way, you need authentication (verifying who the user is) and authorization (deciding what they're allowed to do).
Neither PyQt6 nor PySide6 provides a built-in authentication framework — they're GUI toolkits, not security libraries. But that's fine. You can combine Qt's UI capabilities with Python's networking and security tools to build a solid auth flow for your application.
In this tutorial, we'll walk through the full process: creating a login dialog, authenticating against a remote server, handling tokens, and enabling or disabling parts of your UI based on a user's role.
Approaches to Authentication in Desktop Apps
Before writing any code, it helps to understand the options available when securing a desktop application. The right approach depends on how much security you need and what infrastructure you have.
Simple login check. Your app sends credentials to a remote server at startup. If authentication fails, you disable the UI (partially or entirely). This deters casual users, but a determined attacker could modify the client to bypass the check.
Token-based unlock. After a successful login, the server returns a token or key that unlocks functionality in the app. Without the token, the app simply can't perform certain operations. This is more secure — the app is genuinely non-functional without a valid token — though once data is decoded into memory, it's theoretically accessible.
Server-side execution. After authentication, the app sends work to the server, which performs the actual operations. The sensitive logic never runs on the client at all. This is the most secure approach, but it requires server infrastructure to handle the workload.
For most applications, the middle ground — authenticating against a remote API and using the returned token to gate access — provides a good balance of security and simplicity. That's what we'll build here.
Your app shouldn't care about the database directly. Instead, it should talk to an API (Application Programming Interface) on your server. The API handles user lookups, password verification, and token generation. Your desktop app just sends HTTP requests and processes the responses.
Setting Up a Simple Auth Server (For Testing)
To test our client application, we need something to authenticate against. We'll create a minimal Flask server that accepts login requests and returns a JSON Web Token (JWT). In a real project, this would be your existing backend, but having a self-contained example makes it easier to experiment.
Install the dependencies for the server:
pip install flask pyjwt
Here's a minimal auth server:
import datetime
import jwt
from flask import Flask, jsonify, request
app = Flask(__name__)
SECRET_KEY = "your-secret-key-change-this"
# In production, use a real database with hashed passwords.
USERS = {
"admin": {"password": "admin123", "role": "admin"},
"viewer": {"password": "viewer123", "role": "viewer"},
}
@app.route("/auth/login", methods=["POST"])
def login():
data = request.get_json()
username = data.get("username", "")
password = data.get("password", "")
user = USERS.get(username)
if user and user["password"] == password:
token = jwt.encode(
{
"username": username,
"role": user["role"],
"exp": datetime.datetime.utcnow()
+ datetime.timedelta(hours=1),
},
SECRET_KEY,
algorithm="HS256",
)
return jsonify(
{"token": token, "role": user["role"], "username": username}
)
return jsonify({"error": "Invalid credentials"}), 401
@app.route("/auth/verify", methods=["GET"])
def verify():
auth_header = request.headers.get("Authorization", "")
if not auth_header.startswith("Bearer "):
return jsonify({"error": "Missing token"}), 401
token = auth_header.split(" ", 1)[1]
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
return jsonify(
{"username": payload["username"], "role": payload["role"]}
)
except jwt.ExpiredSignatureError:
return jsonify({"error": "Token expired"}), 401
except jwt.InvalidTokenError:
return jsonify({"error": "Invalid token"}), 401
if __name__ == "__main__":
app.run(port=5000, debug=True)
Save this as auth_server.py and run it in a separate terminal:
python auth_server.py
The server exposes two endpoints:
POST /auth/login— accepts a JSON body withusernameandpassword, returns a JWT token.GET /auth/verify— accepts anAuthorization: Bearer <token>header and returns the user info if the token is valid.
Note: This server stores passwords in plain text and uses a hardcoded secret key. In production, you'd hash passwords (using
bcryptor similar) and store the secret key securely. This is purely for demonstration.
Building the Login Dialog
Now let's build the PyQt6 side. We'll start with a login dialog — a modal window where the user enters their credentials.
Install the client dependencies:
pip install PyQt6 requests
If you're using PySide6, replace
from PyQt6.QtWidgets import ...withfrom PySide6.QtWidgets import ...(and similarly for other Qt modules). The rest of the code is identical.
from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import (
QDialog,
QFormLayout,
QLabel,
QLineEdit,
QPushButton,
QVBoxLayout,
)
class LoginDialog(QDialog):
def __init__(self, parent=None):
super().__init__(parent)
self.setWindowTitle("Login")
self.setFixedSize(350, 200)
layout = QVBoxLayout()
self.form_layout = QFormLayout()
self.username_input = QLineEdit()
self.username_input.setPlaceholderText("Enter your username")
self.form_layout.addRow("Username:", self.username_input)
self.password_input = QLineEdit()
self.password_input.setPlaceholderText("Enter your password")
self.password_input.setEchoMode(QLineEdit.Password)
self.form_layout.addRow("Password:", self.password_input)
layout.addLayout(self.form_layout)
self.login_button = QPushButton("Login")
self.login_button.clicked.connect(self.accept)
layout.addWidget(self.login_button)
self.status_label = QLabel("")
self.status_label.setAlignment(Qt.AlignCenter)
self.status_label.setStyleSheet("color: red;")
layout.addWidget(self.status_label)
self.setLayout(layout)
# Allow pressing Enter to submit.
self.password_input.returnPressed.connect(self.login_button.click)
self.username_input.returnPressed.connect(
self.password_input.setFocus
)
def get_credentials(self):
return (
self.username_input.text().strip(),
self.password_input.text(),
)
def set_status(self, message):
self.status_label.setText(message)
This dialog inherits from QDialog, which gives us the modal behavior we need — when shown with .exec_(), it blocks interaction with the rest of the application until the user either logs in or closes the dialog.
The get_credentials method returns the entered username and password as a tuple. The set_status method lets us display error messages (like "Invalid credentials") directly in the dialog.
Creating an Auth Manager
Rather than scattering authentication logic throughout the application, we'll encapsulate it in a dedicated class. This AuthManager handles login requests, stores the token, and provides the user's role.
import requests
class AuthManager:
def __init__(self, base_url="http://localhost:5000"):
self.base_url = base_url
self.token = None
self.username = None
self.role = None
def login(self, username, password):
"""
Attempt to log in. Returns True on success, False on failure.
Raises an exception on network errors.
"""
response = requests.post(
f"{self.base_url}/auth/login",
json={"username": username, "password": password},
timeout=10,
)
if response.status_code == 200:
data = response.json()
self.token = data["token"]
self.username = data["username"]
self.role = data["role"]
return True
return False
def is_authenticated(self):
return self.token is not None
def get_auth_header(self):
"""Return headers dict with the Bearer token for API requests."""
if self.token:
return {"Authorization": f"Bearer {self.token}"}
return {}
def has_role(self, role):
return self.role == role
def logout(self):
self.token = None
self.username = None
self.role = None
The get_auth_header method is especially useful. Once a user has logged in, you can include this header in any subsequent API call to prove that the request is coming from an authenticated user:
response = requests.get(
"http://localhost:5000/some/protected/endpoint",
headers=auth_manager.get_auth_header(),
timeout=10,
)
Wiring Up the Login Flow
Now we connect the login dialog to the auth manager. The pattern is: show the dialog, grab the credentials, try to authenticate, and either proceed to the main window or show an error.
import sys
from PyQt6.QtWidgets import QApplication, QMessageBox
def attempt_login(auth_manager):
"""
Show the login dialog repeatedly until the user either
successfully authenticates or cancels.
Returns True on successful login, False if cancelled.
"""
dialog = LoginDialog()
while True:
result = dialog.exec_()
if result != QDialog.Accepted:
# User closed the dialog or pressed Cancel.
return False
username, password = dialog.get_credentials()
if not username or not password:
dialog.set_status("Please enter both fields.")
continue
try:
if auth_manager.login(username, password):
return True
else:
dialog.set_status("Invalid username or password.")
except requests.exceptions.ConnectionError:
dialog.set_status("Cannot connect to server.")
except requests.exceptions.Timeout:
dialog.set_status("Connection timed out.")
except requests.exceptions.RequestException as e:
dialog.set_status(f"Error: {e}")
This function keeps showing the login dialog until either the login succeeds or the user dismisses it. Network errors are caught and displayed in the dialog, so the user gets useful feedback without the app crashing.
Building the Main Window with Role-Based Access
The main window of our application will show different features depending on the user's role. Admin users see everything; viewers have a restricted experience.
from PyQt6.QtWidgets import (
QAction,
QMainWindow,
QMenu,
QMenuBar,
QStatusBar,
QTextEdit,
QToolBar,
)
class MainWindow(QMainWindow):
def __init__(self, auth_manager):
super().__init__()
self.auth_manager = auth_manager
self.setWindowTitle("My Application")
self.setMinimumSize(600, 400)
# Central widget.
self.text_edit = QTextEdit()
self.setCentralWidget(self.text_edit)
# Menu bar.
menu_bar = self.menuBar()
file_menu = menu_bar.addMenu("&File")
self.save_action = QAction("&Save", self)
self.save_action.triggered.connect(self.save_document)
file_menu.addAction(self.save_action)
file_menu.addSeparator()
logout_action = QAction("&Logout", self)
logout_action.triggered.connect(self.handle_logout)
file_menu.addAction(logout_action)
quit_action = QAction("&Quit", self)
quit_action.triggered.connect(self.close)
file_menu.addAction(quit_action)
# Admin-only menu.
self.admin_menu = menu_bar.addMenu("&Admin")
manage_users_action = QAction("&Manage Users", self)
manage_users_action.triggered.connect(self.manage_users)
self.admin_menu.addAction(manage_users_action)
server_settings_action = QAction("&Server Settings", self)
server_settings_action.triggered.connect(self.server_settings)
self.admin_menu.addAction(server_settings_action)
# Status bar.
self.status_bar = QStatusBar()
self.setStatusBar(self.status_bar)
# Apply role-based restrictions.
self.apply_permissions()
def apply_permissions(self):
"""Enable or disable UI elements based on the user's role."""
role = self.auth_manager.role
username = self.auth_manager.username
self.status_bar.showMessage(
f"Logged in as {username} ({role})"
)
if role == "admin":
# Admins get full access.
self.admin_menu.setEnabled(True)
self.save_action.setEnabled(True)
self.text_edit.setReadOnly(False)
elif role == "viewer":
# Viewers can see content but not edit or access admin.
self.admin_menu.setEnabled(False)
self.save_action.setEnabled(False)
self.text_edit.setReadOnly(True)
self.text_edit.setPlaceholderText(
"You have read-only access."
)
else:
# Unknown role: disable everything as a safe default.
self.admin_menu.setEnabled(False)
self.save_action.setEnabled(False)
self.text_edit.setReadOnly(True)
def save_document(self):
QMessageBox.information(
self, "Save", "Document saved (placeholder)."
)
def manage_users(self):
QMessageBox.information(
self, "Admin", "User management (placeholder)."
)
def server_settings(self):
QMessageBox.information(
self, "Admin", "Server settings (placeholder)."
)
def handle_logout(self):
self.auth_manager.logout()
self.close()
The apply_permissions method is where authorization happens. After a successful login, we check the user's role and adjust the UI accordingly. Disabled menu items are grayed out and non-clickable, and the text editor is set to read-only for viewers.
This approach — enabling and disabling widgets based on roles — is the standard pattern for authorization in desktop apps. You can extend it as far as you need: hide entire toolbar sections, show different pages in a stacked widget, or restrict access to specific actions.
Making Authenticated API Requests
Once a user is logged in, you'll often need to make further API calls — fetching data, submitting forms, etc. Each of these requests should include the authentication token so the server can verify the user.
Here's how you might fetch some protected data:
def fetch_protected_data(auth_manager):
"""Example of making an authenticated API request."""
try:
response = requests.get(
f"{auth_manager.base_url}/auth/verify",
headers=auth_manager.get_auth_header(),
timeout=10,
)
if response.status_code == 200:
return response.json()
elif response.status_code == 401:
# Token expired or invalid — user needs to log in again.
return None
except requests.exceptions.RequestException:
return None
If the server responds with a 401 Unauthorized, that means the token has expired or been revoked. You should handle this gracefully — for example, by showing the login dialog again.
Handling Token Expiration
Tokens expire. When they do, your app needs to respond appropriately rather than silently failing. A common approach is to wrap your API calls in a method that checks for 401 responses and triggers a re-login:
def authenticated_request(auth_manager, method, url, **kwargs):
"""
Make an HTTP request with authentication.
Returns the response, or None if re-authentication fails.
"""
kwargs.setdefault("headers", {})
kwargs["headers"].update(auth_manager.get_auth_header())
kwargs.setdefault("timeout", 10)
try:
response = requests.request(method, url, **kwargs)
if response.status_code == 401:
# Token expired — try to re-authenticate.
if attempt_login(auth_manager):
kwargs["headers"].update(
auth_manager.get_auth_header()
)
response = requests.request(method, url, **kwargs)
else:
return None
return response
except requests.exceptions.RequestException:
return None
This function automatically retries the request with a new token if the first attempt gets a 401. The user sees the login dialog, re-enters their credentials, and the request proceeds as if nothing happened.
To try it out:
- Start the auth server in one terminal:
python auth_server.py - Run the client application in another terminal:
python app.py - Log in as
admin/admin123to see full access, orviewer/viewer123to see restricted access.
Try logging in with the wrong password — the dialog stays open and shows an error. Close the dialog without logging in and the app exits cleanly.
Security Considerations
A few things to keep in mind when implementing auth in a desktop application:
Never store passwords in the client. Your app should only ever send credentials to the server and receive a token back. The token is what you store (in memory, or securely on disk if you want "remember me" functionality).
Use HTTPS in production. Our example uses plain HTTP because it's running locally. In a real deployment, all communication between the client and server should be encrypted with TLS. The requests library handles HTTPS transparently — just change the URL to https://.
Tokens are temporary. JWTs (and most authentication tokens) have an expiration time. Design your app to handle expired tokens gracefully, as shown in the token expiration section above.
Client-side checks are not enough. Disabling a button in the UI doesn't prevent a technically savvy user from calling the underlying function. Any action that matters should be validated on the server side too. The client-side restrictions are a UX convenience, not a security boundary.
Store tokens securely. If you implement a "remember me" feature that persists the token between sessions, use your platform's secure storage — keyring is a good cross-platform Python library for this. Don't write tokens to plain text files.
Packaging Python Applications with PyInstaller by Martin Fitzpatrick
This step-by-step guide walks you through packaging your own Python applications from simple examples to complete installers and signed executables.
