pyTorrent/auth.md

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

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.

PYTORRENT_AUTH_ENABLE=true
PYTORRENT_AUTH_PROVIDER=local

Password reset example:

python -m pytorrent.cli reset-password admin new_Pass

Tinyauth authentication

Use this when Tinyauth protects pyTorrent before the request reaches the application.

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

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.

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:

PYTORRENT_AUTH_PROXY_AUTO_CREATE_ROLE=admin

3. For non-admin read-write access, use:

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:

PYTORRENT_AUTH_PROXY_USER_HEADER=Remote-User

The configured header must contain a non-empty username.