Access Control for Tor Hidden Services: Building Private .onion Sites 2026

Tor v3 hidden services support client authorization natively. When enabled, only clients with the correct authorization key can connect - unauthorized clients cannot even establish a connection to the introduction points. Setup: on the hidden service server, add HiddenServiceClientAuthDir /path/to/auth_dir/ to the torrc. Create authorized_clients/ subdirectory. For each authorized client: generate a key pair (using mkp224o or a dedicated key generation tool), place the client's public key (as a .auth file) in authorized_clients/. The .auth file format: descriptor:x25519:BASE32_PUBLIC_KEY. Restart Tor. Authorized clients: the client needs the private key in their Tor browser data directory: add the HidServAuth line to the Tor client's torrc (or place .auth_private files in the appropriate directory for Tor Browser). With authorization enabled, unauthorized connections are silently dropped at the introduction point level.

Two layers of access control serve different purposes. Tor-level (client authorization): prevents unauthorized users from even connecting to the service. Strong but operationally complex (requires key distribution and management for each authorized user). Best for: highly sensitive services with a small, known set of authorized users. Application-level (login page): allows any Tor user to connect but requires login credentials to access content. Simpler to manage (add/remove users via application UI). Best for: services with a larger user base, or where the user identity matters (content personalization, user-specific data). Combined: Tor-level authorization for a private community portal, then application-level authentication for individual user sessions within the authorized group.

Nginx Basic Auth provides a simple password gate without application-level implementation. Create password file: htpasswd -c /etc/nginx/.htpasswd username1 (prompts for password). Add to Nginx config: auth_basic 'Private Service'; auth_basic_user_file /etc/nginx/.htpasswd;. This prompts for username/password before serving any content. Limitations: credentials are transmitted in plain HTTP header (Base64 encoded, not encrypted). For HTTP .onion services, the Tor connection encrypts the HTTP traffic, so Basic Auth credentials are encrypted in transit. Not appropriate for clearnet HTTP (would expose credentials). Suitable for: simple private services where all authorized users can share a password, or for protecting admin pages from accidental access.

Invite-only systems restrict new user registration to prevent abuse and maintain community quality. Implementation patterns: invite token table in the database (generated tokens are single-use, expire after 7 days), invite links that include the token (youraddress.onion/join?invite=TOKEN), and token validation at registration (check the token exists and is unused before creating the account). Administrative controls: a designated admin generates invite tokens (not automated bulk generation), monitors token use (knows which invite led to which registration for accountability), and can revoke users (disable account, revoke their invite tokens so they cannot create sub-accounts). For anonymous communities: invite chains (users can generate a limited number of invites for others) balance growth with accountability without requiring real-world identity.

Admin interfaces on hidden services need strong authentication. TOTP (Time-based One-Time Password) adds a second factor beyond password. Implementation: django-two-factor-auth (Django), next-auth with TOTP support (Next.js), or custom TOTP implementation using speakeasy (Node.js) or pyotp (Python). QR code provisioning: on enabling 2FA, display a QR code containing the TOTP secret. The admin scans with Google Authenticator, Aegis (open source), or any TOTP app. Backup codes: generate 10 one-time backup codes at setup. Store these securely (encrypted, offline). If the TOTP device is lost, backup codes provide account recovery. Admin session security: shorter session timeouts for admin sessions (1-4 hours), re-authentication required for high-privilege actions (deleting users, changing security settings), and audit logging of all admin actions.