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


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

location /tinyauth {
  proxy_pass http://10.10.11.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.domian/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.