Authentication

HTTP tunnels can enforce authentication at the edge network before a request reaches the upstream service. This is useful when the upstream runs in a private environment, when the upstream service should not implement its own authentication, or when an additional layer of access control is required.

rstream exposes two authentication mechanisms for HTTP tunnels: token authentication and rstream auth. Both mechanisms can be enabled on the same tunnel.

Token authentication

When token authentication is enabled, the engine requires a valid rstream token on every request. The token is read from the Authorization: Bearer <token> header, and if that header is not present the engine checks the rstream.token query parameter.

curl -H "Authorization: Bearer <token>" https://<tunnel-host>/

curl "https://<tunnel-host>/?rstream.token=<token>"

The engine validates the token using the configured authentication backend. In the hosted platform, tokens can be short-lived user tokens, personal access tokens, or application tokens minted from application credentials.

rstream auth

rstream auth is a browser-oriented mechanism. When enabled, the engine can establish a session using a cookie and an interactive flow, then allow requests from authenticated users that are authorized for the tunnel.

In the community edition build, rstream auth is not available and requests are rejected.

Using both mechanisms

When both token authentication and rstream auth are enabled on a tunnel, the engine evaluates token authentication first. If a valid token is present and authorized, the request proceeds. If no token is present, the engine falls back to rstream auth.

This pattern supports mixed environments where automated clients use tokens and interactive users rely on browser sessions.

Fine-grained access with scoped tokens

Fine-grained token scopes can restrict what a token is allowed to do, including which tunnels can be accessed and which HTTP paths are allowed for a token. This is useful when a single upstream service is exposed but different clients should only reach a subset of routes.

See Fine-Grained Tokens for the scope model and examples.