Authentication

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

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. 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>"

Managed projects accept personal access tokens, application tokens, and short-lived auth tokens. API permissions and tunnel grants still apply. A token can be valid but rejected for a specific HTTP request when its tunnel grants do not include the project, the tunnel, or the requested path.

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 authorized for the project.

rstream Auth is available on managed projects and Enterprise deployments that run the rstream Auth integration. Community Edition deployments do not provide this browser authentication flow.

Using both mechanisms

When both token authentication and rstream Auth are enabled on a tunnel, the engine evaluates token authentication first. If a valid and authorized token is present, 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.

When challenge mode is also enabled, the browser challenge is evaluated before rstream Auth. A valid and authorized bearer token remains the machine-client path and can proceed without the browser challenge. See Challenge Mode for the challenge flow and cookie behavior.

Fine-grained tunnel access

Tunnel grants can restrict HTTP tunnel access beyond token validity. A grant can allow access to one project, one workspace, or a set of HTTP paths. Path restrictions are evaluated by the engine before forwarding the request to the upstream service.

[
  {
    "projects": ["project-id"],
    "scopes": {
      "tunnels": {
        "connect": {
          "params": {
            "path": {
              "regex": "^/api"
            }
          }
        }
      }
    }
  }
]

See Fine-grained tokens for the token and tunnel grants model. See Access policies for project-wide settings such as authenticated public access, trusted IPs, GeoIP restrictions, and minimum TLS version.