Single sign-on (SSO) puts a sign-in page in front of an HTTP tunnel. Visitors sign in with an identity provider you choose, such as Google, GitHub, Microsoft or GitLab, or with a username and password you define, before any request reaches your service.
When to use it #
Until you protect it, an HTTP tunnel is open to anyone who has its address. SSO is the right protection when people open the tunnel in a browser and you want to decide who they are: an admin panel, a dashboard, an internal tool, a staging site. Your service does not change and never sees a password.
SSO is made for browsers. A request that does not carry the sign-in cookie is redirected to the sign-in page, so scripts, webhooks and API clients cannot pass. For those, protect only some paths (see Sign-in paths) or use the options in Access control.
How it works #
- A visitor opens the tunnel URL. A request over HTTP is redirected to HTTPS first.
- The visitor is not signed in yet, so the Localtonet server redirects the browser to the sign-in page on
auth.localtonet.com. The page has the heading Sign in to continue and offers the providers you turned on for this tunnel. - The visitor chooses a provider and signs in there. For a username and password provider, the form is on the sign-in page itself.
- Localtonet checks your access rules and sends the visitor back to the address they asked for. The sign-in is kept in a cookie for the tunnel's host name. It is a browser-session cookie, sent over HTTPS only.
- From then on, requests are forwarded to your service as usual. When the sign-in is no longer valid, the visitor is sent to the sign-in page again.
A visitor who signs in but is not allowed by your rules sees 403 - Access Denied with the text "You do not have permission to access this tunnel."
Paths under /.well-known are never put behind the sign-in.
Before you start #
- An HTTP tunnel. See HTTP / HTTPS.
- Balance on your account. Without it, saving a provider or turning on sign-in fails with "You need to purchase balance to use this feature." See Plans and Balance and Pricing.
- For an external provider: an account there that lets you register an OAuth application.
SSO is set up in your personal dashboard. The SSO button and the SSO Providers setting are not shown for team tunnels.
Providers #
These guides cover the most common choices step by step:
The Provider type list in the dashboard contains: Username-Password, Google, GitHub, Microsoft, OpenID Connect, Discord, Twitter (X), Custom, Facebook, Apple, LinkedIn, GitLab, Slack, Spotify, Twitch, Reddit, Bitbucket, Amazon and Yahoo. For every type except Username-Password and Custom, the endpoints are filled in for you. For OpenID Connect the filled-in addresses are examples that you replace with your provider's endpoints.
Set it up #
There are two parts. You add a provider once, and it is then available to all your HTTP tunnels. After that you turn it on for each tunnel you want to protect. A saved provider protects nothing until a tunnel uses it.
-
Add a provider #
Open My Tunnels › HTTP and select SSO at the top of the page (its tooltip reads SSO Provider Settings). The SSO providers dialog opens. Select Add provider, fill in the form and select Save provider. Each provider is saved separately.
Field What it is Notes Provider name A name to identify this provider in your tunnel settings. Required. For example Company Google.Provider type The sign-in method. A new provider starts as Google. Changing the type of a saved provider empties Client ID, so enter the client ID and the client secret again. Active Makes the provider available to tunnels. When you switch a provider to inactive and save, it is also turned off on every tunnel that used it. Client ID The ID of the application you registered at the provider. Required for every type except Username-Password and Custom. Client secret The secret of that application. Never displayed after saving. Leave it blank later to keep the saved secret. Endpoints & callback Authorization endpoint, Token endpoint, User info endpoint and Callback path. Filled in automatically for the standard providers. Change them only when a guide tells you to. Email access rules Allowed email domains, Blocked email domains and Blocked email addresses. Optional. See Access rules. Sign-in users Usernames and passwords. Only for the types Username-Password and Custom. To remove a provider, select Delete provider. This removes it from your account and from the SSO settings of your tunnels.
-
Turn it on for a tunnel #
Under Your tunnels, select Settings on the tunnel. In the Tunnel settings panel, find SSO Providers and select Manage. The Single sign-on dialog opens.
Setting What it does Require sign-in Turns SSO on for this tunnel. Visitors who aren't signed in are sent to the sign-in page first. Providers One switch for each of your active providers. Turn on at least one. If several are on, the visitor chooses on the sign-in page. Who can sign in Optional lists of Email addresses, Email domains and Usernames for this tunnel. Sign-in and sign-out paths Optional Sign-in paths and a Sign-out path. Select Save.
-
Test it #
Open the tunnel URL in a private browser window. You should arrive on the Sign in to continue page, and after signing in, on your service.
The redirect URI #
An external provider asks where it may send people after they sign in. For every tunnel this is an address on Localtonet's sign-in host, not the address of your tunnel. Register exactly this value:
http://auth.localtonet.com/auth/callbackEach provider guide tells you where to enter it.
| Value | Where it goes |
|---|---|
| The redirect URI above | At the provider: Authorized redirect URIs (Google), Authorization callback URL (GitHub), Redirect URI (Microsoft, GitLab). |
Callback path, for example /auth/callback/google | In Localtonet, under Endpoints & callback. It is filled in for you. Leave it as it is. |
The provider compares the redirect URI with the registered value exactly, so copy it as it is shown here.
Access rules #
Signing in proves who a visitor is. The rules decide whether that person may open the tunnel. There are two levels, and both apply.
| Where | List | What the dashboard says |
|---|---|---|
| Provider | Allowed email domains | Leave blank for no domain restriction. Wildcards depend on the provider. |
| Provider | Blocked email domains | Block sign-ins from these email domains. |
| Provider | Blocked email addresses | Block these individual email addresses. |
| Tunnel | Email addresses, Email domains, Usernames | Leave a list empty to skip that check. The lists apply to all providers turned on for the tunnel. |
Enter one item per line, or separate items with commas. A domain is entered without @, for example example.com.
After you change a rule, a visitor who was already let in can keep access for up to five minutes. A visitor who was refused is checked again after one minute.
Sign-in paths and sign-out path #
| Setting | Behaviour | Example |
|---|---|---|
| Sign-in paths | Empty: every path of the tunnel needs sign-in. Filled: only requests whose path starts with one of the entries need sign-in. | /admin covers /admin and /admin/users, not /administrator. |
| Sign-out path | Opening it removes the sign-in for this tunnel and sends the visitor to the start page of the tunnel, or to the address in a returnUrl query value. | /sso/logout |
Paths start with a slash. Upper and lower case make no difference.
A filled Sign-in paths list opens everything else. With /admin in the list, only /admin is protected and all other paths are reachable without sign-in. Leave the list empty to protect the whole tunnel.
The sign-out path signs the visitor out of the tunnel only. It does not sign them out of Google, GitHub or another identity provider.
Troubleshooting #
"You need to purchase balance to use this feature."
SSO needs Balance. Add Balance, then save again. Without Balance you can still open the dialog and turn Require sign-in off.
"Add a provider before you turn on sign-in."
You have no active provider yet. Select Add a provider in the dialog, or use the SSO button at the top of the HTTP page.
"Turn on at least one provider, or turn off sign-in."
Require sign-in is on but no provider switch is on. A provider that you set to inactive is turned off on its tunnels and no longer listed.
The sign-in page says "No authentication providers are currently configured for this tunnel."
Sign-in is required, but no provider is turned on for this tunnel. Open SSO Providers › Manage on the tunnel and turn one on.
The tunnel opens without asking for sign-in
Check that Require sign-in is on and saved. If Sign-in paths is filled, only those paths are protected. Also test in a private window: your own browser may still be signed in.
"403 - Access Denied" after signing in
The sign-in worked, but a rule refused the account. Check the provider's Email access rules and the tunnel's Who can sign in lists. After you correct a rule, wait a minute and reload.
A webhook or API client gets a redirect instead of an answer
Requests without the sign-in cookie are redirected to the sign-in page. Put only the pages meant for people in Sign-in paths, or use a separate tunnel for machine traffic.
Automation #
Providers and tunnel SSO settings can also be managed through the API, under /api/v2/sso-providers, and through the MCP server.
