Onion service client authorization is a Tor feature that lets the operator of a hidden service limit which users can even find and reach it. Tor is a network that routes internet traffic through volunteer relays to make it harder for observers to learn who is talking to whom.
Without authorization, anyone who learns an onion address can attempt to connect to it. Client authorization adds a second gate: a visitor must hold a valid private key matching a key the operator has registered. This article explains how that gate works, what it protects, and where its limits lie for everyday readers.
Why Restricting Access to a Hidden Service Matters
Imagine a small nonprofit that runs a private document portal as an onion service. The address is long and random, but addresses can leak through screenshots, chat logs, or careless sharing. Anyone holding the address could knock on the door and try to log in, which invites scanning and guessing.
Client authorization changes that situation. The operator registers a public key for each approved visitor, so the service answers only those who can prove they hold the matching private key. Everyone else receives no meaningful response.
This is a defensive measure rather than a privacy shield for the whole network. It narrows the audience of a service so that discovery of an address does not automatically grant access.
How Key Pairs Make the Gate Work
Client authorization relies on asymmetric cryptography, a method where each user holds a private key kept secret and a public key shared openly. The two keys are mathematically linked, so a signature or proof made with the private key can be checked with the public key without revealing the secret itself.
In practice the visitor generates a key pair on their own device and sends the public half to the operator. The operator adds that public key to the service’s authorized list. When the visitor connects, the Tor client uses the private key to prove possession during the handshake, and the service accepts only proofs that match a registered key.
Because the private key never leaves the visitor’s device, the operator never receives the secret. Losing the private key means losing access, so readers should store it with the same care they would give any important credential.
Key Terms You Will See in Setup Guides
Setup documentation uses several specialized words. Knowing them in advance makes the process far less confusing for non-specialists and reduces mistakes during configuration.
- Onion address: the long, self-certifying name that identifies an onion service on the Tor network.
- Authorized client: a visitor whose public key the operator has registered for access.
- Private key: the secret half of a key pair that the visitor keeps on their own device.
- Public key: the shareable half of a key pair that the operator stores in the authorization list.
- Descriptor: a signed document describing how to reach a service, which can be encrypted so only authorized clients read it.
Each term plays a distinct role. The onion address says where a service is, the public key says who may use it, and the private key proves that a visitor is that person. Keeping these roles straight prevents the common error of sharing the wrong key or publishing material that was meant to stay secret.
What Client Authorization Does and Does Not Protect
Client authorization primarily controls access. It stops unknown parties from using a service even if they learn its address, which is valuable when a service should serve a known group only. It also reduces casual scanning, because an unauthorized probe receives no useful reply from the application.
It does not make a service anonymous to the operator, and it does not hide the fact that the operator and visitors use Tor. Authorized users still need to protect their own devices, accounts, and habits, since a compromised laptop can expose a private key just as easily as a stolen password.
It also does not guarantee that the content behind the service is safe. Authorization decides who gets in, not whether the application itself is well built. Operators should still keep their software updated and apply normal web security practices.
Setting Up Authorization Without Common Mistakes
The first practical step is to decide who really needs access and to collect their public keys through a channel that verifies identity. Sending keys over an unverified chat invites impersonation, so operators should confirm each request through a second method when possible.
Next, the operator updates the service configuration so that authorization is enabled and the approved public keys are listed. After a change, restart the service and test with one known account before inviting others. Keep the authorization list tidy by removing keys that belong to people who no longer need access.
Visitors should save their private key in a secure, backed-up location and never share it. If a key is lost or suspected to be exposed, the operator should remove the old entry and issue a new key pair. Documenting each change makes future audits and troubleshooting much easier.
Operating a Restricted Service: Lead Guidance
Running an authorized onion service involves more than a single configuration change. Operators need a repeatable routine for adding users, rotating keys, and confirming that the service still behaves as intended under real conditions.
Managing the Authorized Client List
Treat the authorization list as a living record rather than a one-time setup. Note who each key belongs to, when it was added, and why access was granted. This record lets you answer questions quickly if someone leaves the group or reports a problem.
Review the list on a regular schedule, such as every few months, and remove entries that are no longer needed. A short list is easier to protect and easier to reason about, which lowers the chance of an accidental exposure.
Protecting Keys Across Devices
Private keys are most at risk on the devices that hold them. Encourage authorized users to keep their operating system and Tor software current, to use full disk encryption, and to lock their screens when away. These habits limit the damage if a device is lost or infected.
Avoid storing private keys in cloud folders that sync to many devices or in messages that remain in long chat histories. Where possible, keep a single well-protected copy and a clearly labeled backup stored apart from everyday files.
Testing and Verifying Access
After any change, test the service from an unauthorized context to confirm that it refuses access, and then test from an authorized context to confirm that legitimate use still works. Testing both sides catches mistakes that a single check might miss.
Keep notes on each test, including the date, the account used, and the outcome. Over time these notes reveal patterns, such as keys that stop working after a client update, and help you resolve issues before they disrupt users.
Reading Tor Documentation and Staying Current
The Tor Project publishes documentation on onion services, including the specification for client authorization. Because the network evolves, consult the current official material rather than relying on older blog posts or forum answers that may describe outdated behavior.
Version differences matter. Newer onion service versions use different key formats and descriptor handling than older ones, so confirm that both the service and each visitor’s client support the same version before rolling out access. Mismatched versions are a frequent cause of confusing connection failures.
When documentation is unclear, ask in the official community channels or consult the project’s support resources. Avoid pasting private keys or full configuration files into public forums, since those details can reveal more than you intend.
Legal, Ethical, and Practical Considerations
Tor and onion services are lawful tools in most places, and many organizations use them to protect readers, sources, and staff. Still, the legal rules that apply to the content you host and the data you collect remain in force. Operators should understand their obligations before launching a service.
Authorization should serve legitimate purposes, such as limiting a service to members, staff, or invited collaborators. Using it to hide illegal activity or to evade lawful oversight is not what the feature is designed for, and it can create serious consequences for operators and users alike.
For guidance tailored to your situation, consult a qualified attorney or your organization’s legal counsel. Rules differ across countries and states, and this article is general education rather than legal advice.
Quick Checklist Before You Launch
A short checklist helps catch the most common problems before real users arrive. Work through it once after setup and again after any major change to the service or its keys.
- Confirm that every authorized public key belongs to a person you verified through a second channel.
- Test an unauthorized connection to make sure the service refuses it without returning useful information.
- Test an authorized connection from each device type your group uses, including phones and laptops.
- Store private keys in an encrypted location with a tested backup, and record who holds each key.
- Schedule a recurring review to remove stale entries and confirm that software versions still match.
Running through this list takes little time and prevents most avoidable outages and exposures. Keep a copy with your service documentation so that anyone who takes over administration can follow the same steps without guessing.
Planning Your Next Steps With Restricted Onion Services
If you are new to onion services, begin with a test environment and a single authorized client. Learning the key workflow on low-stakes material builds confidence before you handle sensitive content or invite a larger group. A cautious start is far easier to maintain than a rushed launch.
As your use grows, consider writing a short operating procedure that covers adding users, rotating keys, responding to a lost device, and retiring access. Clear procedures reduce errors when responsibilities change hands and keep the service dependable over time.
Above all, remember that client authorization is one layer among several. Combine it with current software, careful key handling, and honest threat planning, and it becomes a practical way to keep a private service reachable only by the people it was built for.