.. 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= 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=.apps.googleusercontent.com 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= 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= 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= 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.