docs: add comprehensive security and authentication documentation
lint / docker (push) Waiting to run
lint / docker (push) Waiting to run
Add new documentation sections covering security best practices and authentication system architecture. Update Sphinx configuration and dependencies to support documentation improvements. Changes include: - New security.rst with SSH key management, network security, secrets management - New authentication.rst documenting pluggable auth system and provider setup - Updated Sphinx config to use Alabaster theme and add sphinx-tabs extension - Added docs extra dependencies in pyproject.toml for documentation builds - Updated example configs to use Ed25519 instead of deprecated DSA keys - Added .python-version file for consistent Python version management - Added CLAUDE.md project instructions for AI-assisted development - Minor Dockerfile cleanup removing commented pip install line 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -0,0 +1,372 @@
|
||||
.. Reminder for header structure:
|
||||
Level 1: ====================
|
||||
Level 2: --------------------
|
||||
Level 3: ++++++++++++++++++++
|
||||
Level 4: """"""""""""""""""""
|
||||
Level 5: ^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. meta::
|
||||
:description: Configuring authentication for TISBackup web interface
|
||||
:keywords: Documentation, TISBackup, authentication, security, OAuth, Flask-Login
|
||||
|
||||
Authentication Configuration
|
||||
============================
|
||||
|
||||
.. _authentication_configuration:
|
||||
|
||||
TISBackup provides a pluggable authentication system for the Flask web interface,
|
||||
supporting multiple authentication methods to suit different deployment scenarios.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The authentication system supports three authentication providers:
|
||||
|
||||
* **Basic Authentication** - Simple HTTP Basic Auth (default)
|
||||
* **Flask-Login** - Session-based authentication with user management
|
||||
* **OAuth2** - Integration with external identity providers
|
||||
|
||||
By default, TISBackup uses Basic Authentication. You can configure the authentication
|
||||
method in the :file:`/etc/tis/tisbackup_gui.ini` configuration file.
|
||||
|
||||
Basic Authentication
|
||||
--------------------
|
||||
|
||||
HTTP Basic Authentication is the simplest method and is enabled by default.
|
||||
|
||||
Configuration via Environment Variables
|
||||
+++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Set the following environment variables:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export TISBACKUP_AUTH_USERNAME="admin"
|
||||
export TISBACKUP_AUTH_PASSWORD="your-secure-password"
|
||||
|
||||
Configuration via INI File
|
||||
++++++++++++++++++++++++++
|
||||
|
||||
Create or edit :file:`/etc/tis/tisbackup_gui.ini`:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=basic
|
||||
username=admin
|
||||
password=your-password
|
||||
use_bcrypt=False
|
||||
realm=TISBackup
|
||||
|
||||
Using Bcrypt Password Hashes (Recommended)
|
||||
+++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
For improved security, use bcrypt-hashed passwords:
|
||||
|
||||
1. Install bcrypt support:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
uv pip install bcrypt
|
||||
|
||||
2. Generate a password hash:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import bcrypt
|
||||
password = b"your-password"
|
||||
hash = bcrypt.hashpw(password, bcrypt.gensalt())
|
||||
print(hash.decode())
|
||||
|
||||
3. Update configuration:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=basic
|
||||
username=admin
|
||||
password_hash=$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5eSZL9fJQp.Ym
|
||||
use_bcrypt=True
|
||||
realm=TISBackup
|
||||
|
||||
Flask-Login Authentication
|
||||
---------------------------
|
||||
|
||||
Session-based authentication with user management and login pages.
|
||||
|
||||
Installation
|
||||
++++++++++++
|
||||
|
||||
Install Flask-Login support:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
uv pip install flask-login bcrypt
|
||||
|
||||
Configuration
|
||||
+++++++++++++
|
||||
|
||||
Create :file:`/etc/tis/tisbackup_gui.ini`:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=flask-login
|
||||
user_file=/etc/tis/tisbackup_users.txt
|
||||
secret_key=<generate-random-secret-key>
|
||||
session_timeout=3600
|
||||
|
||||
Generate a secret key:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python3 -c "import secrets; print(secrets.token_hex(32))"
|
||||
|
||||
User File Format
|
||||
++++++++++++++++
|
||||
|
||||
Create a user file at :file:`/etc/tis/tisbackup_users.txt`:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
admin:$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5eSZL9fJQp.Ym
|
||||
user1:$2b$12$KPOvd2wqZWVIxje1MIBlDPZy7UuyNRKriQ9/MfxZ6fTaM9gKRq.Wm
|
||||
|
||||
Each line is: ``username:bcrypt_password_hash``
|
||||
|
||||
Managing Users
|
||||
++++++++++++++
|
||||
|
||||
Add a new user:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import bcrypt
|
||||
|
||||
username = "newuser"
|
||||
password = b"secure-password"
|
||||
hash = bcrypt.hashpw(password, bcrypt.gensalt()).decode()
|
||||
|
||||
with open("/etc/tis/tisbackup_users.txt", "a") as f:
|
||||
f.write(f"{username}:{hash}\n")
|
||||
|
||||
Ensure proper permissions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
chmod 600 /etc/tis/tisbackup_users.txt
|
||||
chown root:root /etc/tis/tisbackup_users.txt
|
||||
|
||||
OAuth2 Authentication
|
||||
---------------------
|
||||
|
||||
Integrate with external OAuth2 identity providers like Google, GitHub, or GitLab.
|
||||
|
||||
Installation
|
||||
++++++++++++
|
||||
|
||||
Install OAuth support:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
uv pip install authlib requests
|
||||
|
||||
Google OAuth
|
||||
++++++++++++
|
||||
|
||||
1. Create OAuth credentials in Google Cloud Console
|
||||
2. Configure TISBackup:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=oauth
|
||||
provider=google
|
||||
client_id=<your-client-id>.apps.googleusercontent.com
|
||||
client_secret=<your-client-secret>
|
||||
redirect_uri=https://backup.example.com/callback
|
||||
allowed_domains=example.com
|
||||
|
||||
GitHub OAuth
|
||||
++++++++++++
|
||||
|
||||
1. Create OAuth App in GitHub Settings
|
||||
2. Configure TISBackup:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=oauth
|
||||
provider=github
|
||||
client_id=<your-client-id>
|
||||
client_secret=<your-client-secret>
|
||||
redirect_uri=https://backup.example.com/callback
|
||||
allowed_users=user1,user2,user3
|
||||
|
||||
GitLab OAuth
|
||||
++++++++++++
|
||||
|
||||
1. Create OAuth application in GitLab
|
||||
2. Configure TISBackup:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=oauth
|
||||
provider=gitlab
|
||||
client_id=<your-client-id>
|
||||
client_secret=<your-client-secret>
|
||||
redirect_uri=https://backup.example.com/callback
|
||||
gitlab_url=https://gitlab.example.com
|
||||
|
||||
Generic OAuth Provider
|
||||
++++++++++++++++++++++
|
||||
|
||||
For custom OAuth providers:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=oauth
|
||||
provider=generic
|
||||
client_id=<your-client-id>
|
||||
client_secret=<your-client-secret>
|
||||
redirect_uri=https://backup.example.com/callback
|
||||
authorize_url=https://provider.example.com/oauth/authorize
|
||||
token_url=https://provider.example.com/oauth/token
|
||||
userinfo_url=https://provider.example.com/oauth/userinfo
|
||||
|
||||
Advanced Configuration
|
||||
----------------------
|
||||
|
||||
Multiple Authentication Methods
|
||||
++++++++++++++++++++++++++++++++
|
||||
|
||||
You can only use one authentication method at a time. To switch methods,
|
||||
update the ``type`` parameter in the configuration file and restart
|
||||
the TISBackup GUI service.
|
||||
|
||||
Disabling Authentication (Not Recommended)
|
||||
++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
.. warning::
|
||||
|
||||
Disabling authentication is **not recommended** for production environments.
|
||||
Only use this for testing or when the web interface is protected by other means
|
||||
(e.g., VPN, firewall rules).
|
||||
|
||||
To disable authentication:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=none
|
||||
|
||||
Custom Realm
|
||||
++++++++++++
|
||||
|
||||
For Basic Authentication, customize the authentication realm:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=basic
|
||||
realm=My Company Backup System
|
||||
|
||||
Session Timeout
|
||||
+++++++++++++++
|
||||
|
||||
For Flask-Login and OAuth, configure session timeout (in seconds):
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[authentication]
|
||||
type=flask-login
|
||||
session_timeout=7200 # 2 hours
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
Authentication Not Working
|
||||
++++++++++++++++++++++++++
|
||||
|
||||
Check the logs for authentication errors:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
journalctl -u tisbackup_gui -n 100
|
||||
|
||||
Verify configuration file syntax:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python3 -c "from configparser import ConfigParser; cp = ConfigParser(); cp.read('/etc/tis/tisbackup_gui.ini'); print('OK')"
|
||||
|
||||
Random Password Generated
|
||||
++++++++++++++++++++++++++
|
||||
|
||||
If you see a warning about a generated password in the logs:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
WARNING: Generated temporary password for 'admin': abc123xyz
|
||||
|
||||
This means no password was configured. Set ``TISBACKUP_AUTH_PASSWORD`` environment
|
||||
variable or add an ``[authentication]`` section to the configuration file.
|
||||
|
||||
OAuth Callback Error
|
||||
++++++++++++++++++++
|
||||
|
||||
Ensure the redirect URI in your OAuth provider configuration **exactly matches**
|
||||
the ``redirect_uri`` parameter in the TISBackup configuration.
|
||||
|
||||
The redirect URI should be: ``https://your-domain.com/callback``
|
||||
|
||||
User File Not Found
|
||||
+++++++++++++++++++
|
||||
|
||||
For Flask-Login authentication, ensure the user file exists and has proper permissions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ls -l /etc/tis/tisbackup_users.txt
|
||||
# Should show: -rw------- 1 root root ...
|
||||
|
||||
Security Recommendations
|
||||
------------------------
|
||||
|
||||
1. **Use HTTPS**: Always use HTTPS in production (configure via reverse proxy)
|
||||
2. **Strong Passwords**: Use long, random passwords or password hashes
|
||||
3. **Restrict Access**: Use firewall rules to limit access to trusted networks
|
||||
4. **Regular Updates**: Keep authentication dependencies updated
|
||||
5. **Monitor Logs**: Regularly check logs for failed authentication attempts
|
||||
6. **Session Security**: Use short session timeouts for sensitive environments
|
||||
|
||||
For more security best practices, see the **Security Best Practices** section of the documentation.
|
||||
|
||||
Migration Guide
|
||||
---------------
|
||||
|
||||
From No Authentication
|
||||
++++++++++++++++++++++
|
||||
|
||||
If upgrading from a version without authentication:
|
||||
|
||||
1. Add authentication configuration as described above
|
||||
2. Restart the TISBackup GUI service
|
||||
3. Update any automated tools to include authentication credentials
|
||||
|
||||
From Basic to OAuth
|
||||
+++++++++++++++++++
|
||||
|
||||
1. Set up OAuth provider configuration
|
||||
2. Update ``type=oauth`` in configuration file
|
||||
3. Install required dependencies: ``uv pip install authlib requests``
|
||||
4. Restart the service
|
||||
5. Test login with OAuth provider
|
||||
|
||||
Additional Resources
|
||||
--------------------
|
||||
|
||||
For comprehensive authentication setup examples and troubleshooting,
|
||||
see the :file:`AUTHENTICATION.md` file in the TISBackup repository root.
|
||||
Reference in New Issue
Block a user