DocsGuidesAccess control

Access control

Two independent, per-tunnel controls, both enforced at the edge before a request or connection ever reaches your local app: HTTP basic auth gates ngstone port tunnels, and source-IP allowlisting gates both ngstone port and ngstone tcp.

HTTP basic auth#

Require a username and password before the edge forwards anything:

$ ngstone port 3000 --basic-auth alice:secret
https://amber-fox-42.example.com (basic auth: 1 credential)

Repeat the flag for multiple valid credentials — any one of them succeeds:

$ ngstone port 3000 --basic-auth alice:secret --basic-auth bob:hunter2

Load credentials from a file instead — one user:pass pair per line, blank lines and lines starting with # ignored:

creds.txttext
# staging credentials
alice:secret
bob:hunter2
$ chmod 600 creds.txt
$ ngstone port 3000 --basic-auth-file creds.txt

Or set NGSTONE_BASIC_AUTH, one credential per line, same as the file format:

$ export NGSTONE_BASIC_AUTH=$'alice:secret\nbob:hunter2'
$ ngstone port 3000
--basic-authstring
user:pass. Repeatable for multiple credentials.
--basic-auth-filestring
Path to a file with one user:pass credential per line.
NGSTONE_BASIC_AUTHenv
One user:pass credential per line.

Credential precedence#

Only one source is used — they don't merge. The first one present wins:

1. --basic-authhighest precedence
Any use of the flag, even once, takes over completely and ignores the other two sources.
2. --basic-auth-file
Used if --basic-auth was never passed.
3. NGSTONE_BASIC_AUTHlowest precedence
Used only if neither flag was passed.

IP allowlisting#

Restrict a tunnel to a set of source CIDRs — works for both HTTP and raw TCP tunnels:

$ ngstone tcp 22 --allow-cidr 203.0.113.0/24
tcp://amber-fox-42.example.com:14201 -> 127.0.0.1:22

Comma-separate multiple ranges:

$ ngstone port 3000 --allow-cidr 203.0.113.0/24,198.51.100.42/32
--allow-cidrstring
Comma-separated CIDRs allowed to reach the tunnel. Empty allows any source.

A connection from outside every listed range is rejected before it reaches your app: 403 Forbidden for HTTP, a closed connection for TCP.

Combining both#

Both controls can apply to the same HTTP tunnel at once. The edge checks the source IP first, then basic auth — a request that fails the allowlist never gets a chance to present credentials:

$ ngstone port 3000 --allow-cidr 203.0.113.0/24 --basic-auth alice:secret
Basic auth is HTTP-only. ngstone tcp accepts --allow-cidr but rejects --basic-authat bind time — there's no HTTP request to attach credentials to inside a raw TCP stream.

Traffic policies#

Add request-level rules to an HTTP tunnel with a strict JSON policy file. Rules can allow, deny or redirect a request, rewrite request and response headers, and the policy can answer CORS at the edge:

traffic-policy.jsonjson
{
"default_action": "deny",
"rules": [
{"action": "redirect", "path_prefix": "/old", "redirect_url": "/new$path", "redirect_status": 308},
{"action": "allow", "path_prefix": "/public"},
{"action": "allow", "method": "GET", "path_prefix": "/preview", "header": "X-Preview", "header_value": "yes"},
{"action": "transform", "path_prefix": "/public",
"request_headers": {"set": {"X-Env": "preview"}, "remove": ["X-Debug"]},
"response_headers": {"set": {"Cache-Control": "no-store"}, "remove": ["Server"]}}
],
"cors": {
"allowed_origins": ["https://app.example.com"],
"allowed_methods": ["GET", "POST"],
"allowed_headers": ["Content-Type"],
"allow_credentials": true,
"max_age": 600
}
}
$ ngstone port 3000 --policy-file traffic-policy.json
$ ngstone preview 3000 --ttl 30m --policy-file traffic-policy.json

allow, deny and redirect rules are evaluated in order and the first match wins. transform rules never decide: every matching transform rule applies, in file order, to requests that are proxied. All rules match against the request as the client sent it, so a transform cannot make another rule match.

default_actionstringdefault: allow
Action for requests that match no deciding rule: allow or deny.
actionstringrequired
allow, deny, redirect or transform. A denied request receives 403 Forbidden and is never forwarded.
methodstring
Optional HTTP method match, such as GET or POST.
path_prefixstring
Optional URL-path prefix. Prefixes respect path boundaries, so /api matches /api/users but not /apian.
header, header_valuestring
Optional case-insensitive header name and exact value. Omit header_value to match header presence.
redirect_urlstring
Required for redirect. An absolute path or an http(s) URL. $path (or ${path}) expands to the request path with the rule's path_prefix removed, so /old/a/b becomes /new/a/b above. The request query string is appended only when redirect_url has no query of its own, and $path after a ? is query-escaped. Redirect rules are not checked for loops: a rule whose target matches the rule itself redirects repeatedly until the browser stops.
redirect_statusintdefault: 302
301, 302, 307 or 308.
request_headers, response_headersobject
Only on transform rules. Each holds remove (a list of names), set (replace) and add (append) maps, applied in that order. Request headers change before the request reaches the agent, so your app and the inspector see the result; response headers change after the agent answers, and the inspector shows what your app sent.
corsobject
allowed_origins (exact scheme://host[:port] origins, or ["*"] without credentials), allowed_methods (default GET, HEAD, POST), allowed_headers (["*"] echoes the requested headers), exposed_headers, allow_credentials and max_age in seconds (max 86400).
--policy-filestring
Load the policy for port or preview. In ngstone.json, use policy_file; relative paths resolve from the project file directory.

CORS at the edge

Preflight requests (OPTIONS with Origin and Access-Control-Request-Method) are answered with 204, after the CIDR allow list and the per-IP rate limit but before basic auth, visitor login and rules, because browsers never send credentials on a preflight; they never reach your app. On proxied responses the edge drops any Access-Control-* headers your app set and adds its own for allowed origins. * is accepted in allowed_origins and allowed_headers only as the whole entry and is rejected in allowed_methods.

Reserved headers

Header actions cannot change hop-by-hop headers (Connection, Keep-Alive, TE, Trailer, Transfer-Encoding, Upgrade, Proxy-*) or headers the edge owns: Host, Content-Length, Authorization, Forwarded, X-Real-IP, X-Forwarded-* and X-Ngstone-*. With cors set, Access-Control-* response headers belong to it. Such a policy is rejected when the tunnel starts.

Policies are not authentication

A policy can hide paths or restrict methods, but it does not identify callers. Combine it with --basic-auth, --allow-cidr, or --oidc when the tunnel must be private. Policies are HTTP-only; TCP tunnels reject them.

OIDC visitor login#

Require visitors to sign in with your identity provider (Google, Keycloak, Okta, Auth0, Dex in front of GitHub, and so on) before the edge forwards anything to an HTTP tunnel:

$ ngstone port 3000 --oidc --oidc-allow-domain example.com --oidc-allow-email contractor@gmail.com
--oidcbooldefault: false
Turn on the login wall. Without an allow list, any account the provider authenticates is let in.
--oidc-allow-emailstring
Verified emails allowed in. Comma-separated or repeatable.
--oidc-allow-domainstring
Email domains allowed in. Exact domain match only, so subdomains do not match. Comma-separated or repeatable.
oidc, oidc_allow_email, oidc_allow_domainproject keys
The same settings in ngstone.json and ngstone.yml. HTTP tunnels only; kind: tcp rejects them.

A browser GET without a session is redirected to /.ngstone/auth/start on the apex host. Other requests get 401. After the provider calls back to the apex host, the edge checks the allow list and returns the browser to the tunnel with a one-minute, single-use ticket. The tunnel host then sets an encrypted, host-only ngstone_visitor_session cookie. The edge strips that cookie before proxying. It also deletes any X-Ngstone-User-* header the client sent and sets X-Ngstone-User-Email, X-Ngstone-User-Subject, and X-Ngstone-User-Name for your app. Sign out at /.ngstone/auth/logout.

Trust those headers only when your app is reachable solely through the tunnel. All tunnels share one registrable domain, so SameSite=Lax does not separate sibling tunnels and your app still needs its own CSRF and Origin checks. One identity provider client is shared by all tunnel owners, so an owner can learn the email, subject, and name of anyone who follows a link to their walled tunnel. Sessions are stateless and cannot be revoked before they expire.

The edge operator configures one dedicated OIDC client for visitors, separate from the ops-dashboard login:

export NGSTONE_VISITOR_OIDC_ISSUER=https://accounts.google.com
export NGSTONE_VISITOR_OIDC_CLIENT_ID=ngstone-visitors
export NGSTONE_VISITOR_OIDC_CLIENT_SECRET='provider-client-secret'
export NGSTONE_VISITOR_OIDC_COOKIE_SECRET="$(openssl rand -base64 32)"
# register https://example.com/.ngstone/auth/callback with the provider
ngstoned -domain example.com -cert-email you@example.com

Order of checks

Source CIDR, then the per-IP rate limit, then basic auth, then the login wall, then the traffic policy. Policies see the verified X-Ngstone-User-Email header, so a policy rule can limit a path to specific people.

Security notes#

Prefer the file or the env var over the flag

Command-line arguments are visible to any other local user for the lifetime of the process — via ps or /proc/<pid>/cmdline on Linux. On a shared or multi-tenant machine, --basic-auth leaks your credentials to anyone who can run ps auxww. Use --basic-auth-file (mode 0600) or NGSTONE_BASIC_AUTH instead.

Credentials never cross the wire in plaintext. The agent hashes each user:pass pair with SHA-256 before sending it in the Bind message, and the edge stores and compares only that digest — it never sees or stores your password.

Digests are unsalted

Identical credentials always hash to the same digest. That's fine against a passive eavesdropper, but a captured digest is still subject to an offline dictionary or rainbow-table attack against common user:pass combinations. Use strong, unique passwords, not a reused low-entropy one.

--allow-cidrtrusts whatever the edge believes is the connection's source IP. Behind a front proxy with -proxy-protocol, that means trusting the PROXY header the proxy attaches — and the edge must be told which peers are allowed to send one, with -proxy-protocol-trusted <CIDRs> on ngstoned. Without that, or without firewalling the public port to the proxy alone, a direct client can open a raw connection, forge its own PROXY header, and spoof an allowed source IP straight past the allowlist. See Behind an existing reverse proxy.

Once the edge has verified basic auth for a request, it deletes the Authorization header before forwarding — your local app and the request inspector never see the credential. If no basic auth is configured for that tunnel, Authorization passes through untouched, exactly like every other header.

Requires protocol v2#

Access control is carried in wire protocol v2. If an agent requests --basic-auth, --allow-cidr, or a traffic policy and the edge only negotiates v1, the agent refuses to bind — it fails closed rather than silently opening an unprotected tunnel:

ngstone: edge does not support access control or traffic policies (negotiated protocol v1); upgrade ngstoned

Upgrade ngstoned to a version that offers protocol 2 to use either flag. See Versioning in the wire protocol reference.