220 lines
6.9 KiB
Markdown
220 lines
6.9 KiB
Markdown
# 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
|
|
|
|
# Optional: trusted direct-IP/local hosts that should skip pyTorrent auth.
|
|
# Use this only on private networks, never on public proxy hostnames.
|
|
PYTORRENT_AUTH_BYPASS_HOSTS=10.11.1.11:8090,10.11.1.11
|
|
```
|
|
|
|
|
|
## Reverse proxy origin checks
|
|
|
|
pyTorrent blocks unsafe API requests when the browser `Origin`/`Referer` does not match the application origin. Behind HTTPS reverse proxy this requires either correct forwarded headers or an explicit API origin allowlist.
|
|
|
|
Recommended variables for reverse proxy mode:
|
|
|
|
```env
|
|
PYTORRENT_PROXY_FIX_ENABLE=true
|
|
PYTORRENT_SESSION_COOKIE_SECURE=true
|
|
PYTORRENT_SOCKETIO_CORS_ALLOWED_ORIGINS=https://pytorrent.example.com
|
|
PYTORRENT_API_ALLOWED_ORIGINS=https://pytorrent.example.com
|
|
```
|
|
|
|
`PYTORRENT_API_ALLOWED_ORIGINS` accepts a comma-separated list, for example:
|
|
|
|
```env
|
|
PYTORRENT_API_ALLOWED_ORIGINS=https://pytorrent.example.com
|
|
```
|
|
|
|
If `PYTORRENT_API_ALLOWED_ORIGINS` is not set, pyTorrent reuses `PYTORRENT_SOCKETIO_CORS_ALLOWED_ORIGINS` for API origin checks.
|
|
|
|
## 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;
|
|
|
|
auth_request_set $redirection_url $upstream_http_x_tinyauth_location;
|
|
auth_request_set $auth_user $upstream_http_remote_user;
|
|
proxy_set_header Remote-User $auth_user;
|
|
|
|
}
|
|
|
|
location /tinyauth {
|
|
proxy_pass http://10.11.1.11: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.example.com/login?redirect_uri=$scheme://$http_host$request_uri;
|
|
}
|
|
```
|
|
|
|
Use `PYTORRENT_AUTH_PROXY_USER_HEADER=Remote-User` when this setup forwards `Remote-User` to pyTorrent.
|
|
|
|
## Direct-IP auth bypass
|
|
|
|
Use this only when pyTorrent is reachable on a trusted private IP and you want:
|
|
|
|
- reverse proxy hostname protected by Tinyauth;
|
|
- direct private IP access without pyTorrent login.
|
|
|
|
Example:
|
|
|
|
```env
|
|
PYTORRENT_AUTH_ENABLE=true
|
|
PYTORRENT_AUTH_PROVIDER=tinyauth
|
|
PYTORRENT_AUTH_BYPASS_HOSTS=10.11.1.11:8090,10.11.1.11
|
|
```
|
|
|
|
Behavior:
|
|
|
|
- requests with `Host: 10.11.1.11:8090` or `Host: 10.11.1.11` use the built-in default admin user;
|
|
- requests through the reverse proxy still require the configured auth provider;
|
|
- profile permissions are ignored for bypassed direct-IP requests because they run as the default admin user.
|
|
|
|
Do not add public domains to this list.
|
|
|
|
## 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`.
|
|
|
|
## Connection badge behind Tinyauth
|
|
|
|
The top-right badge shows Socket.IO connectivity, not REST API health.
|
|
|
|
If the application loads data through REST API but the badge stays `offline`, the most common cause is that the Socket.IO handshake or follow-up events are not authenticated with the same external identity header. pyTorrent resolves external auth during Socket.IO connect/events as well as normal REST requests.
|
|
|
|
For Tinyauth, make sure the same location that proxies pyTorrent also forwards `Remote-User` to all paths, including `/socket.io/`:
|
|
|
|
```nginx
|
|
auth_request_set $auth_user $upstream_http_remote_user;
|
|
proxy_set_header Remote-User $auth_user;
|
|
```
|
|
|
|
No separate badge-disable option is needed. The badge should become `online` when Socket.IO connects correctly.
|
|
|
|
## 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.
|