auth providers

auth.md

@@ -0,0 +1,150 @@
+# Authentication configuration
+
+## Overview
+
+pyTorrent supports three authentication modes:
+
+- `local` - built-in pyTorrent login screen with username and password.
+- `tinyauth` - external authentication through Tinyauth and a trusted reverse proxy username header.
+- `proxy` - generic external authentication through a trusted reverse proxy username header.
+
+When `tinyauth` or `proxy` is used, pyTorrent does not show the local login form. The reverse proxy must authenticate the request first and pass the authenticated username to pyTorrent in the configured header.
+
+## Environment variables
+
+```env
+PYTORRENT_AUTH_ENABLE=true
+
+# local | tinyauth | proxy
+PYTORRENT_AUTH_PROVIDER=tinyauth
+
+# Header that contains the authenticated username.
+PYTORRENT_AUTH_PROXY_USER_HEADER=Remote-User
+
+# Create a local pyTorrent user when the external user is missing.
+PYTORRENT_AUTH_PROXY_AUTO_CREATE=true
+
+# Role for auto-created external users: user | admin
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=admin
+
+# Permission for auto-created role=user accounts: none | ro | rw | full
+# rw is accepted as an alias of full.
+# Admin users ignore this value and can access all profiles.
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_PERMISSION=rw
+```
+
+## Local authentication
+
+Use this when pyTorrent should manage its own login screen and passwords.
+
+```env
+PYTORRENT_AUTH_ENABLE=true
+PYTORRENT_AUTH_PROVIDER=local
+```
+
+Password reset example:
+
+```bash
+python -m pytorrent.cli reset-password admin new_Pass
+```
+
+## Tinyauth authentication
+
+Use this when Tinyauth protects pyTorrent before the request reaches the application.
+
+```env
+PYTORRENT_AUTH_ENABLE=true
+PYTORRENT_AUTH_PROVIDER=tinyauth
+PYTORRENT_AUTH_PROXY_USER_HEADER=Remote-User
+PYTORRENT_AUTH_PROXY_AUTO_CREATE=true
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=admin
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_PERMISSION=rw
+```
+
+Behavior:
+
+- Tinyauth authenticates the browser request.
+- The reverse proxy forwards the authenticated username in `Remote-User`.
+- pyTorrent reads only that username header.
+- If the username already exists in pyTorrent, that user is used.
+- If the username does not exist and `PYTORRENT_AUTH_PROXY_AUTO_CREATE=true`, pyTorrent creates it.
+- Passwordless external users are synchronized with `PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE` and `PYTORRENT_AUTH_PROXY_AUTO_CREATE_PERMISSION` on login.
+
+## Example Nginx / Nginx Proxy Manager advanced vhost
+
+```nginx
+location / {
+  proxy_pass          $forward_scheme://$server:$port;
+  auth_request        /tinyauth;
+  error_page          401 = @tinyauth_login;
+}
+
+location /tinyauth {
+  proxy_pass http://10.87.7.99:3000/api/auth/nginx;
+  proxy_set_header x-forwarded-proto $scheme;
+  proxy_set_header x-forwarded-host $http_host;
+  proxy_set_header x-forwarded-uri $request_uri;
+}
+
+location @tinyauth_login {
+  return 302 http://auth.linuxiarz.pl/login?redirect_uri=$scheme://$http_host$request_uri;
+}
+```
+
+Use `PYTORRENT_AUTH_PROXY_USER_HEADER=Remote-User` when this setup forwards `Remote-User` to pyTorrent.
+
+## Generic reverse proxy authentication
+
+Use this when another proxy authenticates users and sends a username header.
+
+```env
+PYTORRENT_AUTH_ENABLE=true
+PYTORRENT_AUTH_PROVIDER=proxy
+PYTORRENT_AUTH_PROXY_USER_HEADER=X-Forwarded-User
+PYTORRENT_AUTH_PROXY_AUTO_CREATE=true
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=user
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_PERMISSION=rw
+```
+
+## Auto-created user permissions
+
+`PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=admin`:
+
+- user is created as admin;
+- profile permissions are not needed;
+- all profiles are visible and writable.
+
+`PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=user`:
+
+- `none` - creates the user without profile access;
+- `ro` - grants read-only access to all profiles;
+- `rw` - grants read-write access to all profiles;
+- `full` - same as `rw`.
+
+## Troubleshooting
+
+If the user is created but profiles are missing:
+
+1. Check the created user's role in pyTorrent user management.
+2. For admin access, use:
+
+```env
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=admin
+```
+
+3. For non-admin read-write access, use:
+
+```env
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=user
+PYTORRENT_AUTH_PROXY_AUTO_CREATE_PERMISSION=rw
+```
+
+4. Delete the wrongly auto-created external user or log in again. Passwordless external users are synchronized on login by the current config.
+
+If login fails completely, verify that the configured header reaches pyTorrent:
+
+```env
+PYTORRENT_AUTH_PROXY_USER_HEADER=Remote-User
+```
+
+The configured header must contain a non-empty username.