docs: add comprehensive security and authentication documentation

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>

docs-sphinx-rst/source/authentication.rst

@@ -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.

docs-sphinx-rst/source/conf.py

@@ -35,6 +35,7 @@ extensions = [
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "sphinx_tabs.tabs",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -124,22 +125,9 @@ todo_include_todos = True
 
 # -- Options for HTML output ----------------------------------------------
 
-try:
-    import sphinx_rtd_theme
-
-    html_theme = "sphinx_rtd_theme"
-    html_favicon = "_static/favicon.ico"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-    html_context = {
-        "css_files": [
-            "_static/css/custom.css",  # overrides for wide tables in RTD theme
-            "_static/css/ribbon.css",
-            "_static/theme_overrides.css",  # override wide tables in RTD theme
-        ],
-    }
-except ImportError as e:  # noqa : F841
-    html_theme = "alabaster"
-    html_theme_path = []
+html_theme = "alabaster"
+html_theme_path = []
+html_favicon = "_static/favicon.ico"
 
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -381,7 +369,9 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
 
 # -- Options for Epub output ----------------------------------------------
 

docs-sphinx-rst/source/configuring_tisbackup.rst

@@ -82,7 +82,7 @@ Backing up a MySQL database
   [srvintranet_mysql_mediawiki]
   type=mysql+ssh
   server_name=srvintranet
-  private_key=/root/.ssh/id_dsa
+  private_key=/root/.ssh/id_ed25519
   db_name=mediawiki
   db_user=user
   db_passwd=password
@@ -141,7 +141,7 @@ Backing up a file server
   type=rsync+ssh
   server_name=srvfiles
   remote_dir=/home
-  private_key=/root/.ssh/id_dsa
+  private_key=/root/.ssh/id_ed25519
   exclude_list=".mozilla",".thunderbird",".x2go","*.avi"
   bwlimit = 100
 

docs-sphinx-rst/source/index.rst

@@ -92,6 +92,13 @@ would have been difficult to develop as an overlay of the existing one:
   configuring_tisbackup.rst
   using_tisbackup.rst
 
+.. toctree::
+  :maxdepth: 2
+  :caption: Security & Authentication
+
+  security.rst
+  authentication.rst
+
 .. toctree::
   :maxdepth: 1
   :caption: Appendix

docs-sphinx-rst/source/installing_tisbackup.rst

@@ -251,14 +251,24 @@ Launching the backup scheduled task
 Generating the public and private certificates
 ++++++++++++++++++++++++++++++++++++++++++++++
 
-* as root:
+* as root, generate an Ed25519 SSH key (modern and secure algorithm):
 
   .. code-block:: bash
 
-    ssh-keygen -t rsa -b 2048
+    ssh-keygen -t ed25519 -C "tisbackup@$(hostname)"
 
 * press :kbd:`Enter` for each one of the steps;
 
+.. note::
+
+  TISBackup supports Ed25519, ECDSA, and RSA key algorithms (in order of preference).
+  DSA keys are no longer supported for security reasons. If you need RSA for compatibility,
+  use at least 4096 bits:
+
+  .. code-block:: bash
+
+    ssh-keygen -t rsa -b 4096 -C "tisbackup@$(hostname)"
+
 |clap| You may now go on to the next step
 and :ref:`configure the backup jobs for your TISBackup<configuring_backup_jobs>`.
 

docs-sphinx-rst/source/security.rst

@@ -0,0 +1,288 @@
+.. Reminder for header structure:
+  Level 1: ====================
+  Level 2: --------------------
+  Level 3: ++++++++++++++++++++
+  Level 4: """"""""""""""""""""
+  Level 5: ^^^^^^^^^^^^^^^^^^^^
+
+.. meta::
+  :description: Security best practices for TISBackup
+  :keywords: Documentation, TISBackup, security, best practices, authentication
+
+Security Best Practices
+=======================
+
+.. _security_best_practices:
+
+TISBackup has been designed with security in mind. This section outlines
+the security features and best practices for deploying and maintaining
+a secure backup infrastructure.
+
+SSH Key Algorithm Support
+--------------------------
+
+Modern SSH Key Algorithms
++++++++++++++++++++++++++
+
+TISBackup supports modern SSH key algorithms with the following priority:
+
+1. **Ed25519** (recommended) - Modern, fast, and secure
+2. **ECDSA** - Elliptic curve cryptography
+3. **RSA** - Traditional algorithm (use 4096 bits minimum)
+
+.. warning::
+
+  DSA keys are **no longer supported** due to known security vulnerabilities.
+  If you are using DSA keys, you must migrate to Ed25519, ECDSA, or RSA.
+
+Generating Secure SSH Keys
++++++++++++++++++++++++++++
+
+For new installations, generate an Ed25519 key:
+
+.. code-block:: bash
+
+  ssh-keygen -t ed25519 -C "tisbackup@$(hostname)"
+
+For compatibility with older systems that don't support Ed25519, use RSA with 4096 bits:
+
+.. code-block:: bash
+
+  ssh-keygen -t rsa -b 4096 -C "tisbackup@$(hostname)"
+
+Migrating from DSA Keys
+++++++++++++++++++++++++
+
+If you have existing backup configurations using DSA keys:
+
+1. Generate a new Ed25519 key on the backup server
+2. Copy the new public key to all backup clients
+3. Update the ``private_key`` parameter in all backup sections
+4. Test the backups to ensure they work with the new key
+5. Remove the old DSA keys from both server and clients
+
+Flask Web Interface Security
+-----------------------------
+
+Authentication
+++++++++++++++
+
+The Flask web interface now requires authentication by default.
+TISBackup supports multiple authentication methods:
+
+Basic Authentication (Default)
+"""""""""""""""""""""""""""""""
+
+By default, TISBackup uses HTTP Basic Authentication. Configure it via
+environment variables or the configuration file.
+
+**Environment variables:**
+
+.. code-block:: bash
+
+  export TISBACKUP_AUTH_USERNAME="admin"
+  export TISBACKUP_AUTH_PASSWORD="your-secure-password"
+
+**Configuration file** (:file:`/etc/tis/tisbackup_gui.ini`):
+
+.. code-block:: ini
+
+  [authentication]
+  type=basic
+  username=admin
+  # Bcrypt hash of password (recommended)
+  password_hash=$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5eSZL9fJQp.Ym
+  use_bcrypt=True
+  realm=TISBackup
+
+.. warning::
+
+  If no password is configured, TISBackup will generate a random password
+  and display it in the logs. This is not suitable for production use.
+
+Session-Based Authentication (Flask-Login)
+"""""""""""""""""""""""""""""""""""""""""""
+
+For more advanced deployments, you can use Flask-Login with a user file:
+
+.. code-block:: ini
+
+  [authentication]
+  type=flask-login
+  user_file=/etc/tis/tisbackup_users.txt
+  secret_key=<random-secret-key>
+
+OAuth2 Authentication
+""""""""""""""""""""""
+
+For enterprise deployments, OAuth2 is supported with providers like Google,
+GitHub, and GitLab:
+
+.. code-block:: ini
+
+  [authentication]
+  type=oauth
+  provider=google
+  client_id=<your-client-id>
+  client_secret=<your-client-secret>
+  redirect_uri=http://backup.example.com:8080/callback
+  allowed_domains=example.com
+
+See :file:`AUTHENTICATION.md` in the repository root for detailed
+authentication configuration.
+
+Secret Key Configuration
++++++++++++++++++++++++++
+
+The Flask application requires a secret key for session security.
+
+**Never use the default hardcoded key in production!**
+
+Configure via environment variable:
+
+.. code-block:: bash
+
+  export TISBACKUP_SECRET_KEY="your-random-secret-key-here"
+
+Or in :file:`/etc/tis/tisbackup_gui.ini`:
+
+.. code-block:: ini
+
+  [global]
+  secret_key=your-random-secret-key-here
+
+Generate a secure random key:
+
+.. code-block:: bash
+
+  python3 -c "import secrets; print(secrets.token_hex(32))"
+
+SSL/TLS Configuration
++++++++++++++++++++++
+
+For production deployments, always use HTTPS. Place the Flask application
+behind a reverse proxy like Nginx or Apache:
+
+**Nginx example:**
+
+.. code-block:: nginx
+
+  server {
+      listen 443 ssl http2;
+      server_name backup.example.com;
+
+      ssl_certificate /etc/ssl/certs/backup.crt;
+      ssl_certificate_key /etc/ssl/private/backup.key;
+
+      location / {
+          proxy_pass http://127.0.0.1:8080;
+          proxy_set_header Host $host;
+          proxy_set_header X-Real-IP $remote_addr;
+          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+          proxy_set_header X-Forwarded-Proto $scheme;
+      }
+  }
+
+Database and Backup Security
+-----------------------------
+
+File Permissions
+++++++++++++++++
+
+Ensure proper file permissions on sensitive files:
+
+.. code-block:: bash
+
+  # Configuration files
+  chmod 600 /etc/tis/tisbackup-config.ini
+  chmod 600 /etc/tis/tisbackup_gui.ini
+
+  # SSH keys
+  chmod 600 /root/.ssh/id_ed25519
+  chmod 644 /root/.ssh/id_ed25519.pub
+
+  # Password files (for XenServer, etc.)
+  chmod 600 /root/xen_passwd
+
+  # Backup directory
+  chown -R root:root /backup/data
+  chmod 750 /backup/data
+
+Credential Storage
+++++++++++++++++++
+
+For database credentials and other secrets:
+
+* Use strong, unique passwords for each service
+* Store credentials in configuration files with restricted permissions
+* Consider using a secrets management system for sensitive deployments
+* Rotate credentials regularly
+
+Network Security
+++++++++++++++++
+
+* Restrict SSH access to the backup server IP address
+* Use firewall rules to limit access to the web interface
+* Consider VPN access for remote backup management
+* Enable fail2ban or similar tools to prevent brute-force attacks
+
+Security Monitoring
+-------------------
+
+Log Monitoring
+++++++++++++++
+
+Regularly review TISBackup logs for:
+
+* Failed authentication attempts
+* Backup failures or timeouts
+* Unusual activity patterns
+* SSH connection errors
+
+.. code-block:: bash
+
+  # View recent backup logs
+  journalctl -u tisbackup_gui -n 100
+
+  # Monitor for authentication failures
+  grep "authentication failed" /var/log/tisbackup/*.log
+
+Backup Verification
++++++++++++++++++++
+
+* Regularly test backup restoration
+* Verify backup integrity using checksums
+* Monitor backup sizes for unexpected changes
+* Set up Nagios checks for backup freshness
+
+Security Updates
+++++++++++++++++
+
+* Keep TISBackup updated to the latest version
+* Apply security patches to the host operating system
+* Update Python dependencies regularly:
+
+.. code-block:: bash
+
+  uv sync --upgrade
+
+Additional Security Recommendations
+------------------------------------
+
+1. **Principle of Least Privilege**: Create dedicated service accounts
+   for backups rather than using root when possible
+
+2. **Network Segmentation**: Place the backup server in a dedicated
+   network segment with restricted access
+
+3. **Backup Encryption**: Consider encrypting backups at rest,
+   especially for sensitive data
+
+4. **Off-site Storage**: Maintain encrypted off-site backups
+   for disaster recovery
+
+5. **Access Auditing**: Maintain logs of who accesses backups
+   and when they are restored
+
+6. **Incident Response**: Have a documented procedure for responding
+   to security incidents involving the backup infrastructure