Registration and login app made using customtkinter with input validation, hashed passwords and Google, Facebook and Discord login.
This includes a sqlite3 database setup with many functions including saving the registration data, logging in with username or email, OAuth login, password reset by email, security questions, country selection, light and dark mode, a profile page, password change, account deletion, and more. Settings can be changed in config.py or in a .env file.
- Screenshots
- Prerequisites
- Features
- Security
- Project Structure
- Installation
- Windows Release (.exe)
- Database Location
- PostgreSQL and MySQL
- Configuration
- OAuth Setup
- Database Functions
- User Functions
- Device and Todo Functions
- OAuth Functions
- Validation Functions
- UI Functions
- Frames
- App and Config
- Upgrading From an Older Version
- Contributing
Before you begin, ensure you have met the following requirements:
Python 3.9+withtkinter: tkinter ships with Python on Windows and macOS. On Linux install it withsudo apt install python3-tk.customtkinter: You can install customtkinter usingpip install customtkinter.pycountry: You can install pycountry usingpip install pycountry.Pillow: You can install Pillow usingpip install Pillow.psutil: You can install psutil usingpip install psutil.
OAuth sign-in uses only the Python standard library, no extra packages are needed.
Optional, only for other databases:
psycopg2-binaryfor PostgreSQL:pip install psycopg2-binaryPyMySQLfor MySQL / MariaDB:pip install PyMySQL
- Login with username or email.
- Google, Facebook and Discord login (OAuth 2.0).
- Registration with password confirmation and password strength bar.
- Forgot password: email, security question, temporary password sent by email.
- New password required after logging in with a temporary password.
- Profile page: Gravatar profile picture, account details, edit name and country.
- Security page: change or set password, delete account.
- Device page: computer name, OS, CPU, memory, disk, uptime, local and public IP, MAC address, OS user and session time.
- Todo list with Today, Upcoming and Archive. The alarm time is picked from a calendar and sends a message to a Discord, Slack or any other webhook.
- Archived tasks (done or from before today) are deleted after 1, 3, 7, 14 or 30 days, you choose.
- Light and dark mode.
- Settings in
config.pyor.env. - SQLite by default, PostgreSQL or MySQL with one setting.
- Builds for Windows, macOS and Linux with GitHub Actions.
- Older databases are upgraded automatically.
- Passwords and security answers are hashed with PBKDF2-SHA256 and a random salt.
- Account is locked for 5 minutes after 5 wrong passwords.
- 3 wrong security answers send the user back to the login screen.
- Temporary passwords are made with
secretsand only saved if the email was sent. - OAuth uses a random
statecheck, PKCE for Google and a local redirect server that closes after a timeout. - A social login is only linked to an existing account if the provider says the email is verified.
- SMTP and OAuth secrets are kept in
.env, which is ignored by git. - All queries use
?parameters.
main.py # Start the app
app.py # MainApp window, switches between frames
frames.py # All screens and UI helper functions
functions.py # User, security, email and validation functions
database.py # Database connection for SQLite, PostgreSQL and MySQL
oauth.py # Google, Facebook and Discord sign-in (OAuth 2.0)
config.py # Every setting, reads .env for values you change
.env.example # Template for your .env file
requirements.txt # Python packages
build.py # Builds the one-file .exe with PyInstaller
build.bat # Windows: double-click to build the .exe
tests/ # Tests, run with: python -m unittest discover -s tests -t .
.github/workflows # Tests and builds on Windows, macOS and Linux
images/ # Login button logos and screenshots
To install CustomTkinter-Login-Registration, follow these steps:
-
Clone this repository:
git clone https://github.com/cfunkz/CustomTkinter-Login-Registration.git cd CustomTkinter-Login-Registration -
Install Imports:
pip install -r requirements.txt
-
Create your settings file (optional, only needed for email and OAuth login):
cp .env.example .env
-
Run the app:
python main.py
The app can be built into one CustomTkinterApp.exe file that runs without Python installed.
- On Windows, install Python 3.9+ from python.org.
- Double-click
build.bat(or runpython build.py). - The release is
dist\CustomTkinterApp.exe.
build.py uses PyInstaller and bundles the images, customtkinter themes, country list and the PostgreSQL / MySQL driver if it is installed. Add images\icon.ico to give the .exe an icon. PyInstaller builds for the system it runs on, so build the Windows .exe on Windows.
To configure the .exe, put a .env file next to it or in the data folder below.
On macOS and Linux run python3 build.py the same way, it makes dist/CustomTkinterApp.app or dist/CustomTkinterApp.
GitHub Actions tests and builds all three on every push, download them from the run's Artifacts. Push a tag like v1.0.0 to add them to a release as CustomTkinterApp-Windows.exe, CustomTkinterApp-macOS.zip and CustomTkinterApp-Linux.tar.gz.
The build is always called CustomTkinterApp, APP_NAME only changes the title shown in the app.
The SQLite database is saved in one fixed folder per user, so it is the same no matter where the app or .exe is started from:
| System | Folder |
|---|---|
| Windows | %APPDATA%\TitlePlacement\user_database.db |
| macOS | ~/Library/Application Support/TitlePlacement/user_database.db |
| Linux | ~/.local/share/TitlePlacement/user_database.db |
Change the folder name with DATA_FOLDER, or use another file with DATABASE_FILE.
SQLite is used by default. To use PostgreSQL or MySQL / MariaDB, install the driver and add the connection to .env. The Users table is created on first start.
PostgreSQL (pip install psycopg2-binary):
DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=user_database
DATABASE_USER=app
DATABASE_PASSWORD=your-passwordMySQL / MariaDB (pip install PyMySQL):
DATABASE_TYPE=mysql
DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_NAME=user_database
DATABASE_USER=app
DATABASE_PASSWORD=your-passwordThe database itself (user_database) must exist, the app only creates the table.
All settings live in config.py. Each value is read in this order:
- Environment variables set in your terminal
- The
.envfile next tomain.pyor the.exe - The
.envfile in the data folder (see Database Location) - The default value in
config.py
Only add the values you want to change to .env. See .env.example for the full list.
| Variable | Default | Description |
|---|---|---|
APP_NAME |
Title Placement |
Name shown in the window title, above the forms and in the sidebar |
APPEARANCE_MODE |
System |
System, Light or Dark |
COLOR_THEME |
blue |
customtkinter theme: blue, green, dark-blue or a .json path |
ACCENT_COLOR / ACCENT_HOVER_COLOR |
#3B82F6 / #2563EB |
Buttons, links and highlights |
DANGER_COLOR / SUCCESS_COLOR |
#EF4444 / #22C55E |
Error and success colors |
FONT_FAMILY |
Segoe UI |
Font used everywhere |
UI_SCALING |
1.0 |
Scale all widgets |
AUTH_WINDOW_SIZE |
520x640 |
Login screens window size |
DASHBOARD_WINDOW_SIZE |
1100x680 |
Dashboard window size |
WINDOW_RESIZABLE |
false |
Allow resizing the window |
DATA_FOLDER |
TitlePlacement |
Name of the data folder for the database and .env |
DATABASE_TYPE |
sqlite |
sqlite, postgres or mysql |
DATABASE_FILE |
data folder user_database.db |
SQLite database file |
DATABASE_HOST / DATABASE_PORT |
localhost / 5432 or 3306 |
PostgreSQL / MySQL server |
DATABASE_NAME |
user_database |
PostgreSQL / MySQL database name |
DATABASE_USER / DATABASE_PASSWORD |
— | PostgreSQL / MySQL login |
MIN_PASSWORD_LENGTH |
8 |
Minimum password length |
MAX_LOGIN_ATTEMPTS |
5 |
Wrong passwords before lockout |
LOCKOUT_MINUTES |
5 |
Lockout length |
MAX_SECURITY_ATTEMPTS |
3 |
Wrong security answers allowed |
HASH_ITERATIONS |
310000 |
PBKDF2 iterations for new hashes |
TEMPORARY_PASSWORD_LENGTH |
12 |
Length of emailed temporary passwords |
SMTP_SERVER / SMTP_PORT |
smtp.gmail.com / 587 |
SMTP server (STARTTLS) |
SMTP_USERNAME / SMTP_PASSWORD |
— | Your Gmail address and app password |
SMTP_TIMEOUT |
15 |
Seconds before an email attempt fails |
SENDER_EMAIL |
SMTP_USERNAME |
The "From" address |
OAUTH_PROVIDERS |
google,facebook,discord |
Social buttons shown, in this order |
OAUTH_REDIRECT_HOST / PORT / PATH |
localhost / 8765 / /callback |
Local redirect URI |
OAUTH_TIMEOUT |
120 |
Seconds to wait for the browser sign-in |
OAUTH_LINK_BY_EMAIL |
true |
Link a social sign-in to an existing account with the same verified email |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
— | Google OAuth client |
FACEBOOK_CLIENT_ID / FACEBOOK_CLIENT_SECRET |
— | Facebook app ID and secret |
FACEBOOK_API_VERSION |
v19.0 |
Facebook Graph API version |
DISCORD_CLIENT_ID / DISCORD_CLIENT_SECRET |
— | Discord application |
Example .env:
APP_NAME=Title Placement
APPEARANCE_MODE=Dark
SMTP_USERNAME=you@gmail.com
SMTP_PASSWORD=your-app-password
GOOGLE_CLIENT_ID=1234.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-secretThe app opens the provider's login page in the browser and waits for it to redirect back to a small local server. Register this redirect URI with every provider:
http://localhost:8765/callback
If you change OAUTH_REDIRECT_HOST, OAUTH_REDIRECT_PORT or OAUTH_REDIRECT_PATH, register the new URI instead.
- Open Google Cloud Console > Credentials.
- Configure the OAuth consent screen, then create an OAuth client ID of type Desktop app.
- Copy the client ID and secret to
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET.
- Create an app at Meta for Developers and add the Facebook Login product.
- Add
http://localhost:8765/callbackto Valid OAuth Redirect URIs. - Copy the App ID and App Secret to
FACEBOOK_CLIENT_IDandFACEBOOK_CLIENT_SECRET.
- Create an application at the Discord Developer Portal.
- Under OAuth2 > Redirects add
http://localhost:8765/callback. - Copy the Client ID and Client Secret to
DISCORD_CLIENT_IDandDISCORD_CLIENT_SECRET.
A provider without a client ID and secret still shows its button, and clicking it explains which values to add. Remove it from OAUTH_PROVIDERS to hide it.
The following functions in database.py open the database and create the tables.
- Imports the driver for
DATABASE_TYPEand explains which package to install if it is missing.
- Opens a SQLite, PostgreSQL or MySQL connection (from
DATABASE_TYPE) and returns the connection and cursor. - The cursor accepts
?placeholders on every database.
- Closes the provided database connection.
- Context manager that opens a connection, commits on success, rolls back on error and always closes it.
- Usage:
with database() as cursor: ...
- Current time as text, stored the same way on every database.
- Creates the
UsersandTodostables once when the app starts.
- Adds columns that an older
UsersorTodostable doesn't have (works on SQLite, PostgreSQL and MySQL).
- Upgrades an older
user_database.dbwith the new columns and case-insensitive indexes.
The following functions in functions.py are used for managing users.
register_user(first_name, last_name, country, username, email, password, security_question, security_answer)
- Registers a new user with the provided information. The password and security answer are hashed.
- Returns
Truefor successful registration, orFalseif the username or email is already in use.
- Checks the username or email and password.
- Returns a tuple
(status, username)where status is"ok","change_password","locked"or"invalid". - Counts failed attempts, locks the account after too many, and upgrades legacy plain-text passwords to hashes.
- Returns how many seconds are left on an account lockout (
0if not locked).
- Logs in or registers a user from a social sign-in profile.
- Returns a tuple
(status, username)where status is"ok","linked"(added to an existing account),"created"(new account) or"email_in_use".
- Turns a name or email into a valid username and adds a number if it is already taken.
- Returns
Trueif the email address is registered.
- Returns
Trueif the username is taken.
- Saves a new hashed password and clears any lockout.
must_change=Truemakes the user choose a new password after the next login.- Returns
Truefor a successful password update, orFalsefor a failure.
- Generates a temporary password, emails it and saves it only if the email was sent.
- Returns
Trueon success, orFalseif the email could not be sent.
- Changes a password after checking the current one. Social sign-in accounts without a password can set one directly.
- Returns a tuple
(success, message).
- Returns a dictionary of the user's profile, sign-in provider, webhook and whether a password is set, or
Noneif not found.
- Updates the user's name and country. Returns
Trueon success.
- Deletes an account after confirming the password (or the username for social sign-in accounts without a password).
- Returns
Trueon success.
- Downloads the user's Gravatar picture, found by the SHA-256 hash of the email.
- Returns the picture bytes, or
Noneif the user has no Gravatar or there is no internet. - The result is kept in memory until the app is closed, so it is only downloaded once.
- Retrieves the security question associated with the given email address.
- Returns the security question or
Noneif the email is not found or the account uses social sign-in.
- Checks if the provided security answer matches the stored (hashed) answer, case and space insensitive.
- Returns
Trueif the security answer matches, orFalseif it does not.
- Hashes a password with PBKDF2-SHA256 and a random salt, stored as
iterations$salt$hash.
- Checks a password against a stored hash in constant time. Also accepts legacy plain-text values.
- Returns
Trueif a stored value is already a hash.
- Lowercases a security answer and collapses extra spaces.
- Generates a cryptographically secure temporary password with at least one letter and one digit (length from
TEMPORARY_PASSWORD_LENGTH).
- Sends a password reset email to the provided email address with the temporary password.
- Returns
Trueif the email was sent, orFalseif SMTP is not configured or on any SMTP or network error.
The following functions in functions.py are used by the Device and Todo pages.
- Returns the computer name, OS, architecture, CPU cores, memory, disk, uptime, Python version, OS user, local IP and MAC address.
- Returns the IP address of this computer on the local network. Nothing is sent, it only picks the network card.
- Returns the IP address the internet sees, from api.ipify.org. Slow, so the Device page calls it in the background.
- Returns the MAC address of the network card, or
"Unknown"if it can't be read.
- Returns a readable OS name like
"Windows 11","macOS 14.5"or"Linux 6.8.0".
- Turns bytes into text like
"15.8 GB".
- Turns seconds into text like
"3h 15m"or"5m 42s", used for uptime and session time.
- Saves a new task, with an optional due time.
- Returns all tasks of a user, sorted by time (tasks without a time last).
- Splits tasks into
Today,Upcoming(later or no time) andArchive(done, or from before today).
- Checks or unchecks a task and saves when it was done.
- Deletes archived tasks that are older than
days. Done tasks count from when they were done.
- Saves after how many days archived tasks are deleted.
- Deletes a task.
- Returns open tasks whose time has come and that haven't been sent yet.
- Marks a task as sent so the alarm only goes off once.
- Saves the user's webhook URL.
- Sends a message to a webhook. Works with Discord, Slack or any URL that accepts a JSON POST.
- Returns
Trueif the message was sent.
The following functions in oauth.py handle social sign-in.
- Runs the full browser sign-in for
"google","facebook"or"discord"and returns the user's profile. - Blocking, the UI runs it in a background thread. Raises
OAuthErrorwith a message for the user.
- Builds the URL of the provider's sign-in page.
- Starts a local server on
127.0.0.1, waits for the redirect and returns the authorization code after checkingstate.
- Trades the authorization code for an access token.
- Reads the signed in user's profile and converts it to the app's format (
id,email,email_verified,first_name,last_name,username,provider).
- Convert each provider's profile into the app's format.
- Sends a request and returns the JSON response.
- Creates a PKCE code verifier and its SHA-256 challenge.
- Returns the redirect URI to register with each provider.
- Returns the providers from
OAUTH_PROVIDERSthat the app supports, in the configured order.
- Returns
Truewhen a provider has a client ID and secret.
- Returns the display name of a provider, e.g.
"google">"Google".
The following functions in functions.py check user input.
- Returns
Trueif the email address looks valid.
- Returns
Trueif the text only has letters, numbers,_and-(used for usernames).
- Same as
is_valid_chars, but spaces are allowed too (used for names).
- Returns
Trueif the password only has printable characters and no spaces.
- Returns
Trueif the password is long enough (MIN_PASSWORD_LENGTH) and has both letters and numbers.
- Returns a score from 0 to 4, shown by the strength bar.
- Returns
Trueif the country is in the country list.
- Return the country names sorted alphabetically, and as a set for fast checks (cached after the first call).
- Shows or hides the text of a password field.
- Prints a message, handy to test a new button.
The following functions in frames.py create the widgets, so every screen has the same look.
- Shared fonts, created once and reused.
- Loads and caches an image (the login button logos).
- Turns the downloaded Gravatar picture into a square image with slightly rounded corners.
- Adds a large title with a muted subtitle.
- Input field.
- Read-only dropdown that matches the input fields.
- Button in
primary,secondary,dangerorghoststyle.
- Clickable text in the accent color.
- Show error, success and info messages under the form.
- Bar and label that show password strength while typing.
- Dropdown to switch between System, Light and Dark mode.
- Card with a heading. Returns the card and the frame to put content in.
- Runs slow tasks (email, OAuth, Gravatar, public IP) in a thread so the window doesn't freeze, then calls
on_done(result, error).
Every screen is a class in frames.py.
- Input dialog that hides what is typed, used to confirm the password before deleting an account.
- Small window to pick a day and a time for a todo. Past days are greyed out.
change_month(step)goes to the previous or next month,select_day(day)picks a day,show_month()draws the days.pick()callson_pick("2024-01-31 18:30")and closes the window,clear()callson_pick("")for no time.
- Shared layout for every login screen: back button, appearance menu and a centered form.
create_footer(text, link_text, command)adds the "No account? Register" line under the form.
- Change password fields, used after a password reset and on the Security page.
handle_change_password()checks the fields and saves the new password.
- The login screen.
setup_login_frame()builds the form,setup_social_buttons(providers)adds the Google, Facebook and Discord buttons.check_login_credentials()logs in with username or email.start_oauth_login(provider)andfinish_oauth_login(result, error)run the browser sign-in in the background.set_social_buttons_state(state)enables or disables the social buttons while signing in.
- The registration screen.
setup_register_frame()builds the form,new_user_data()checks the inputs and saves the user.
- Asks for the email of the account.
handle_reset_password()checks it and opens the security question.
- Asks the security question.
handle_reset_password()checks the answer and emails a temporary password,finish_reset_password(sent, error)shows the result.
- Shown after logging in with a temporary password, the user has to choose a new one.
- The dashboard with the sidebar and the Profile, Security, Device and Todo pages.
setup_loggedin_frame()builds the dashboard and starts loading the Gravatar picture.setup_sidebar()adds the avatar, name, menu, appearance menu and logout button.show_gravatar(data, error)puts the Gravatar picture in the sidebar and on the Profile page.show_page(page)switches between the pages.create_page_header(title)adds the page title.setup_profile_page()shows the picture, account details and the name and country form.save_profile()saves them.create_info_rows(master, rows)shows label and value pairs in three columns.setup_security_page()shows the change password form and the delete button.finish_change_password(message)shows the result,handle_delete_account()asks twice and deletes the account.setup_device_page()shows the computer info.update_session_time()counts the session time every second.setup_todo_page()shows the task list, the archive setting and the webhook.show_todos()deletes old archived tasks and rebuilds the Today, Upcoming and Archive lists,show_todo_row(todo)adds one task.open_calendar()opens the calendar,set_due_time(text)shows the picked time on the time button.save_archive_days(days)saves after how many days archived tasks are deleted.handle_add_todo(),toggle_todo(todo_id, done)andremove_todo(todo_id)add, check and delete tasks.save_webhook()andtest_webhook()save and test the webhook URL.check_todo_alarms()checks every 30 seconds for tasks that are due, shows them and sends them to the webhook.
- The main window.
switch_frame(frame_class, *args)destroys the current frame and shows a new one. open_main_frame(),open_register_frame(),open_forgot_password_frame(),open_forgot_password_frame2(email),open_change_password_frame(username)andopen_loggedin_frame(username)open each screen.change_geometry(size)andchange_title(title)change the window size and title,center_window()moves it to the middle of the screen.destroy_all_frames()removes the current frame.
resource_pathfinds bundled files (images) both from source and from the.exe.get_data_dirreturns the per-user data folder and creates it if needed.
load_env_file(path) and get_env(), get_env_int(), get_env_float(), get_env_bool(), get_env_list() (config.py)
- Read
.envand typed settings, falling back to the default when a value is missing or invalid.
The database now lives in the data folder (see Database Location). To keep your users, move your old user_database.db there, or set DATABASE_FILE to its path.
Your existing user_database.db keeps working. On start the app adds the new columns, and each user's plain-text password and security answer are replaced with a hash the next time they log in or answer their question.
Contributions are welcome! Please feel free to open an issue or create a pull request.







