151 lines
4.4 KiB
Markdown
151 lines
4.4 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
|
|
```
|
|
|
|
## 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.
|