Basic Auth

Q: How do I password protect a tunnel?

Open the tunnel's Settings , turn on Basic Authentication under HTTP Protection , enter a username and password, and save. Visitors get a browser login prompt before any request reaches your app, and nothing in your code changes.

Q: What happens if my app already uses the Authorization header?

A client can send one Authorization header, and with basic authentication on it carries the tunnel's username and password, so your application receives those in place of its own bearer token or API key. Cookie and session sign-in is unaffected. Where your app needs that header, restrict the tunnel with an IP allowlist or Remote Access .

Q: Can I use basic auth from curl or a script?

Yes. It is standard HTTP authentication, so curl -u user:password https://example.eu.localport.dev works, as does the equivalent in any HTTP client library.

Summary

Basic Authentication puts a username and password in front of an HTTP tunnel. Visitors get a browser login prompt, and no request reaches your local service until the username and password match. Your application is unchanged, and the password applies from the moment you save.

How basic authentication works#

Basic authentication is the HTTP scheme defined in RFC 7617. A client sends an Authorization header carrying Basic followed by username:password encoded in base64, and Localport compares that against the username and password set on the tunnel. A request without a valid username and password is refused before it reaches your local service.

The check applies to HTTP and HTTPS traffic. A TCP or TLS tunnel carries raw bytes with no request headers, so there is nothing for the check to read.

A fleet carries the same setting, applied once to the whole fleet, and it covers every device reached over HTTP.

Enable basic authentication#

Turn on Basic Authentication, then enter a username and password.

1. Open the tunnel's Settings and find HTTP Protection.

2. Turn on Basic Authentication.

3. Enter a Username and a Password.

4. Click Save.

Both fields are required. Editing the setting requires the Admin role.

Conflicts with application-level authentication#

Localport reads the Authorization header to run the check and forwards it to your service unchanged. That header is the only part of the request the check looks at. The body is never read, and the rest of the request is passed through untouched.

Check whether your application already uses this header

A client can send one Authorization header, and with basic authentication on it carries the tunnel's username and password. An application expecting its own bearer token or API key there receives those instead.

Cookie and session sign-in is unaffected.

Where your application needs its own Authorization header, restrict the tunnel with an IP allowlist or with Remote Access instead.

For the same reason, Header Authentication cannot use Authorization while Basic Authentication is on. Saving that combination is refused in both directions.

Force HTTPS#

Force HTTPS sits beside Basic Authentication and is on by default. Leave it on. Basic authentication encodes the username and password in base64 without encrypting them, so a plain http:// request would carry a readable password across the network path. Localport answers a plain http:// request with a redirect before either value is read, so a browser sends them only over TLS.

What a visitor sees#

A request without a valid username and password is answered with 401 Unauthorized and a WWW-Authenticate: Basic header. A browser reads that header and shows its own login dialog. A wrong username or password produces the same response, and the browser asks again.

Anything that speaks HTTP can authenticate:

curl -u admin:PASSWORD https://example.eu.localport.dev

Your application receives the request exactly as it would without a tunnel. There is no middleware to add, and nothing to remove when you turn the setting off.

Changing the username or password#

Type the new value and save. Leaving the password field empty keeps the password already set.

The change applies immediately, with no restart and no reconnection. Every request is checked, so the next request on any connection uses the new username and password, including connections that are already open. A response already in flight finishes.

Limitations#

A tunnel has one username and one password, shared by everyone who opens it.

A webhook provider will not fill in a login prompt. Use Webhook Verification for a provider that signs its requests, or Header Authentication for one that can send a header you name.
A TCP or TLS tunnel has no HTTP request to check. Restrict it with an IP allowlist.
Per-person access, and removing one person without changing what everyone else uses, needs Remote Access, where each caller presents a certificate you issued.

Frequently asked questions#

How do I password protect a tunnel?

Open the tunnel's Settings, turn on Basic Authentication under HTTP Protection, enter a username and password, and save. Visitors get a browser login prompt before any request reaches your app, and nothing in your code changes.

Does basic auth work on TCP tunnels?

No. Basic authentication is part of HTTP, so it applies to HTTP and HTTPS traffic. To restrict a TCP or TLS tunnel, use an IP allowlist, or Remote Access, which checks a client certificate before a byte reaches your service.

What happens if my app already uses the Authorization header?

A client can send one Authorization header, and with basic authentication on it carries the tunnel's username and password, so your application receives those in place of its own bearer token or API key. Cookie and session sign-in is unaffected. Where your app needs that header, restrict the tunnel with an IP allowlist or Remote Access.

Can I set different passwords for different people?

No. A tunnel has one username and one password. For per-person access, an audit trail that names people, and the ability to remove one person's access on its own, use Remote Access.

Will a webhook provider work with basic auth turned on?

Usually not. Most providers send no username and password, so their requests are refused with a 401. Use Webhook Verification for a provider that signs its requests, or Header Authentication for one that can send a header you name.

How is the password stored?

Encrypted at rest, and shown in plain text only on the tunnel's own settings screen.

Does my app need to handle the login?

No. The check runs before the request is routed, so your app receives ordinary requests and needs no middleware, no library and no configuration. Turning the setting off removes the prompt with no code change either.

Can I use basic auth from curl or a script?

Yes. It is standard HTTP authentication, so curl -u user:password https://example.eu.localport.dev works, as does the equivalent in any HTTP client library.

When does a password change take effect?

Immediately on save. Every request is checked, so the next request on any connection uses the new username and password, including connections that are already open. Nothing restarts and no client reconnects.

Does basic auth work on a fleet?

Yes. A fleet has one username and password for the whole fleet, set under HTTP Protection in its settings, and it covers every device reached over HTTP. Devices served over TCP carry no HTTP request, so the check does not reach them.