Skip to content

USERS.md

Latest commit

 

History

History
293 lines (200 loc) · 10.5 KB

USERS.md

File metadata and controls

293 lines (200 loc) · 10.5 KB
Raw

User Management

aMuTorrent supports multi-user authentication with fine-grained capabilities, trusted proxy SSO, and per-user API keys.

Table of Contents

Overview

aMuTorrent provides flexible authentication options:

  • No authentication — Open access (default)
  • Password protection — Enable auth via the setup wizard or environment variables; an admin user account is created automatically
  • Multi-user — Add more users with individual capabilities through the Settings page
  • Trusted proxy SSO — Automatic login via reverse proxy headers (e.g., Authelia, Authentik)

All modes are configured through the setup wizard or Settings page.

Authentication Modes

No Authentication

The default mode. Anyone who can reach the web UI has full access. Suitable for trusted networks or when aMuTorrent is behind an external authentication layer.

Password Protection (User System)

When authentication is enabled, aMuTorrent always uses its built-in user system. Setting a password in the setup wizard (or via WEB_AUTH_PASSWORD) creates an admin user account automatically. This admin account has full access and a personal API key for external integrations.

You can then add more users through Settings → User Management, each with their own password and capabilities.

When authentication is active:

  • The login page shows username and password fields
  • Each user sees only the features their capabilities allow
  • Download ownership is tracked per user
  • Navigation and actions are filtered based on capabilities
  • Each admin user gets a personal API key for Sonarr/Radarr integration

Trusted Proxy SSO

Users are authenticated by a reverse proxy (e.g., Authelia, Authentik) that sets a username header. aMuTorrent trusts this header from allowed IP ranges and automatically creates or logs in the corresponding user.

Enabling Authentication

Via Setup Wizard

  1. On the Security step, enable authentication
  2. Set a password (this creates the admin account)
  3. After setup, go to Settings → User Management to add more users

Via Environment Variables

WEB_AUTH_ENABLED=true
WEB_AUTH_PASSWORD=your_secure_password

Password Requirements:

  • At least 8 characters
  • At least one digit
  • At least one letter
  • At least one special character (any non-alphanumeric character)

User Management

Access user management through Settings → User Management (admin only).

Creating Users

  1. Click Add User
  2. Enter username and password
  3. Select a capability preset or customize individual capabilities
  4. Click Save

Capability Presets

When creating or editing a user, quick presets help configure capabilities:

  • Full Access — All capabilities enabled
  • Read Only — View-only access (search, history, shared files, uploads, statistics, logs, view all downloads)
  • Custom — Automatically detected when individual checkboxes are toggled manually

The admin flag is a separate toggle — admin users bypass all capability checks regardless of which capabilities are selected.

Editing Users

  • Change username, password, admin flag, and capabilities
  • Enable or disable a user account (preserves data but prevents login)
  • When capabilities change, active sessions are invalidated and WebSocket connections are closed

Profile

Users can change their own password via the profile menu (click username in the header).

Capabilities Reference

Capability Description
search Search ED2K network and Prowlarr indexers
add_downloads Add new downloads (ED2K links, magnets, torrents)
remove_downloads Remove/delete downloads
pause_resume Pause, resume, and stop downloads
assign_categories Change the category of a download
move_files Move download files to category paths
rename_files Rename download and shared files
set_comment Set rating and comment on shared files (aMule)
manage_categories Create, edit, and delete categories
view_history View download history
clear_history Delete history entries
view_shared View shared files (aMule)
view_uploads View active uploads
view_statistics View statistics and charts
view_logs View application logs
view_servers View ED2K server list
view_all_downloads See downloads added by other users
edit_all_downloads Modify/delete downloads owned by other users

Note: Admin users bypass all capability checks — they always have full access regardless of assigned capabilities.

Trusted Proxy SSO

Trusted proxy SSO allows a reverse proxy to handle authentication and pass the authenticated username to aMuTorrent via an HTTP header.

How It Works

  1. User authenticates with the reverse proxy (e.g., Authelia)
  2. Proxy forwards the request with a username header (e.g., X-Remote-User)
  3. aMuTorrent reads the header and creates a session for that user
  4. If auto-provisioning is enabled, new users are created automatically

Configuration

Via Settings UI

  1. Go to Settings → Trusted Proxy section
  2. Enable Trusted Proxy SSO
  3. Set the Username Header (e.g., X-Remote-User)
  4. Optionally enable Auto-Provision to create users automatically

Via Environment Variables

TRUSTED_PROXY_ENABLED=true
TRUSTED_PROXY_USERNAME_HEADER=X-Remote-User
TRUSTED_PROXY_AUTO_PROVISION=true

Security

aMuTorrent validates that requests come from trusted IP ranges before accepting the username header. Only the actual TCP peer address (req.socket.remoteAddress) is checked — forwarded headers like X-Forwarded-For are never trusted.

Default trusted IP ranges (when no custom ranges are configured):

Range Description
127.0.0.0/8 IPv4 loopback
10.0.0.0/8 RFC 1918 private
172.16.0.0/12 RFC 1918 private (includes Docker networks)
192.168.0.0/16 RFC 1918 private
::1/128 IPv6 loopback
fc00::/7 IPv6 unique local
fe80::/10 IPv6 link-local

To restrict further, set custom CIDR ranges via TRUSTED_PROXY_IPS or the Settings UI.

Auto-Provisioned User Capabilities

Auto-provisioned SSO users receive a restricted set of capabilities by default (all capabilities except edit_all_downloads, manage_categories, view_servers, and view_logs). An admin can adjust capabilities for any user after provisioning.

Example: Authelia

# authelia configuration.yml (excerpt)
access_control:
  default_policy: deny
  rules:
    - domain: amutorrent.example.com
      policy: one_factor

# nginx reverse proxy
location / {
    proxy_pass http://amutorrent:4000;
    proxy_set_header X-Remote-User $upstream_http_remote_user;

    # Authelia auth_request
    auth_request /authelia;
    auth_request_set $upstream_http_remote_user $upstream_http_remote_user;
}

Example: Authentik

  1. In Authentik, create a Proxy Provider for aMuTorrent
  2. Under the provider settings, add a custom header mapping that sends the authenticated username as X-Remote-User
  3. Configure your reverse proxy to forward the header:
# nginx reverse proxy for Authentik
location / {
    proxy_pass http://amutorrent:4000;

    # Authentik forward auth
    auth_request /outpost.goauthentik.io/auth/nginx;
    auth_request_set $authentik_username $upstream_http_x_authentik_username;
    proxy_set_header X-Remote-User $authentik_username;
}

location /outpost.goauthentik.io {
    proxy_pass http://authentik-outpost:9000/outpost.goauthentik.io;
}

Per-User API Keys

When authentication is enabled, each admin user gets a unique API key for external API access (Torznab indexer and qBittorrent-compatible API).

Viewing Your API Key

  1. Go to Settings → any integration section that shows API configuration (e.g., Sonarr/Radarr)
  2. Your personal API key is displayed with a copy button

Using API Keys

  • Torznab indexer — Use the API key in the "API Key" field in Sonarr/Radarr
  • qBittorrent-compatible API — Use your username and password, or use the API key as the password

Note: Only admin users have API keys and can access the external APIs. See *arr Integration for full setup instructions.

Download Ownership

When authentication is active, aMuTorrent tracks which user added each download.

How It Works

  • When a user adds a download through the web UI, their user ID is recorded
  • Downloads added via the qBittorrent-compatible API (e.g., Sonarr/Radarr) are attributed to the authenticated API user

Visibility

  • view_all_downloads controls whether a user sees all downloads or only their own
  • edit_all_downloads controls whether a user can modify/delete all downloads or only their own

Notifications & Scripts

When authentication is active, notifications and custom event scripts include ownership information:

  • Owner — the username who owns the download (from the ownership table)
  • Triggered by — the username who initiated the action (empty for system-detected events like download completion or file move)

For example, if an admin deletes another user's file, the notification shows "👤 john (by admin)".

Custom scripts receive these as EVENT_OWNER and EVENT_TRIGGERED_BY environment variables, and as owner/triggeredBy fields in the JSON payload.

Broadcast Filtering

WebSocket real-time updates respect ownership — users only receive updates for downloads they're allowed to see.

Environment Variables

Variable Default Description
WEB_AUTH_ENABLED false Enable authentication
WEB_AUTH_PASSWORD - Admin password (locks UI editing)
TRUSTED_PROXY_ENABLED false Enable trusted proxy SSO
TRUSTED_PROXY_USERNAME_HEADER - HTTP header containing the username (e.g., X-Remote-User)
TRUSTED_PROXY_AUTO_PROVISION false Automatically create users from proxy header
TRUSTED_PROXY_IPS - Comma-separated CIDR ranges (empty = default private ranges)