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

```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

# Existing active user used by bypassed requests. Defaults to admin.
PYTORRENT_AUTH_BYPASS_USER=admin
```


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

# Existing active user used by bypassed requests. Defaults to admin.
PYTORRENT_AUTH_BYPASS_USER=admin
```

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;
- `PYTORRENT_AUTH_BYPASS_USER` must point to an existing active user; when unset, pyTorrent uses `admin`;
- if the bypass user is `admin`, profile permissions are ignored because admins can access all profiles;
- when no active profile is saved for the bypass user, pyTorrent opens the profile picker instead of silently selecting the first profile;
- after selecting a profile, the choice is saved in the bypass user's preferences and reused on the next direct-IP visit.

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