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

# 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:

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:

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.

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;
  
  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:

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.

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/:

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:

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.

External provider logout

When PYTORRENT_AUTH_PROVIDER=tinyauth or PYTORRENT_AUTH_PROVIDER=proxy is used, pyTorrent does not render an active logout action. The authenticated session is owned by the upstream provider, so logging out must be handled by that provider, for example through the Tinyauth logout endpoint or its own UI.

The /logout route becomes a safe no-op redirect to the main page for external auth providers. Local authentication keeps the original pyTorrent logout behavior.