TT-auth-system 2.3.5

An authentication system with one-time login links, templated email sending, and SQLite database support

OTC Auth System

The OTC Auth system is a Python package that provides a simple authentication mechanism using one-time login links. Users receive an email containing a unique login link, generated by the package, which allows them to authenticate without a password. This package is intended to be integrated into larger projects, providing reusable authentication functionality.

Installation

To install the package, clone the repository or download the source code. Navigate to the root directory of the package and run:

pip3 install TT_auth_system

This command installs the package and its dependencies.

Setup and Configuration

Environment Variables

The package relies on several environment variables to configure its behavior, particularly for SMTP settings, database access, encryption, and the base URL of the login link. These should be set in a .env file in the root of the main project using the package.

Create a .env file with the following variables:

• SMTP_SERVER: The address of the SMTP server used to send emails (e.g., smtp.example.com).
• SMTP_PORT: The port number for the SMTP server (commonly 587 for TLS or 465 for SSL).
• SMTP_USERNAME: The username for SMTP authentication.
• SMTP_PASSWORD: The password for SMTP authentication.
• LOGIN_LINK_BASE_URL: The base URL for the login link sent to users. This should point to the part of your application that handles login (e.g., https://yourapp.com/login).
• REPLY_TO_ADDR (optional): The reply-to email address for the emails sent. If not provided, no reply-to address will be set.
• FERNET_KEY: A 32-byte base64-encoded key for Fernet encryption. This key is used to encrypt and decrypt codes.
• EXPIRATION_TIME: The time in seconds for which a one-time code remains valid (e.g., 600 seconds for 10 minutes).
• DB_PATH: The path to the SQLite database file used to store user data and codes.

Example .env file:

SMTP Configuration

SMTP_SERVER=smtp.example.com SMTP_PORT=587 SMTP_USERNAME=your_smtp_username SMTP_PASSWORD=your_smtp_password

Base URL for Login Link

LOGIN_LINK_BASE_URL=https://yourapp.com/login BASE_URL=http://yourapp.com

Optional Reply-To Address

REPLY_TO_ADDR=[e-mail]

Encryption Key for Fernet (should be 32 bytes in base64)

FERNET_KEY=your_base64_encoded_key

Expiration Time for Codes (in seconds)

EXPIRATION_TIME=600

Path to SQLite Database File

DB_PATH=users.db

Root User to be added if users table is empty

ROOT_USER=[e-mail]

Lifespan of the HttpOnly cookie in seconds

COOKIE_LIFE=1800

HTML Email Template

The package sends an HTML email containing the login link. The HTML template can be passed as a string to the class, or it can be placed in the templates directory at the root of the main project. If using a file, it should be named otc_email.html.

Directory Structure:

main_project/ ├── .env ├── templates/ │ └── otc_email.html └── main_script.py

Example otc_email.html:

<title>Login Link</title>

Hello, {{ first_name }},

Click the link below to log in:

{{ login_link }}

This link is valid for one-time use only.

Best regards,
Your App Team

The {{ login_link }} and {{ first_name }} placeholders will be replaced with the actual login link and the user’s first name when the email is sent.

Usage

To use the package in your project, create an instance of the OTCAuthSystem class and use its methods for generating and sending emails, validating codes, and managing users:

from TT_auth_system import OTCAuthSystem

Initialize the auth system

auth_system = OTCAuthSystem()

Generate a one-time code and send a login email if the email exists in the database

code = auth_system.generate_and_send_email("[e-mail]")

Validate a code (returns the associated email if valid as well as set an HttpOnly Cookie, None otherwise)

is_valid = auth_system.validate_code(code)

Purge all valid codes from the database

auth_system.purge_valid_codes()

Get all users from the database

all_users = auth_system.get_all_users()

Edit a user in the database by user ID

auth_system.edit_user(user_id=1, FirstName="John", LastName="Doe")

Delete a user from the database by user ID

auth_system.delete_user(user_id=1)

Get a specific user by email

user = auth_system.get_user_by_email("[e-mail]")

Add a full user

new_user = auth_system.add_user(first_name=first_name, last_name=last_name, email_address=email_address, authorized_flag=authorized_flag, admin_flag=admin_flag)

Dependencies

The package depends on the following Python libraries:

• python-dotenv: For loading environment variables from a .env file.
• jinja2: For rendering HTML templates.
• smtplib: Part of Python’s standard library, used for sending emails via SMTP.
• cryptography: For secure encryption and decryption using Fernet.
• sqlalchemy: For interacting with the SQLite database.

These dependencies are automatically installed when you install the package using pip.

Testing

The package includes support for testing with pytest. To facilitate testing, dependencies such as database connections and SMTP clients can be injected, allowing for easy mocking.

License

This project is licensed under the MIT License. See the LICENSE file for details.