TISbackup/docs-sphinx-rst/source/authentication.rst

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