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