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 three authentication mechanisms for HTTP tunnels: token authentication, rstream Auth, and mTLS. A tunnel can enable more than one method so different clients can use different proofs.

Token authentication

When token authentication is enabled, the engine requires a valid rstream token on every request. The canonical form is Authorization: Bearer <token>. A published tunnel also accepts the reserved rstream.token query parameter.

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

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

The query form also separates edge and application authentication. If a request contains both rstream.token and an Authorization header, the engine uses the namespaced query value as the rstream credential, removes it before proxying, and preserves the header for the upstream application.

curl \
  -H "Authorization: Bearer <application-token>" \
  "https://<tunnel-host>/api?rstream.token=<rstream-token>"

Use that form only with a short-lived rstream token restricted to the target tunnel and path. Send it over HTTPS, avoid URL logging, and never put the persistent application credential in the query string. This precedence belongs to published tunnel traffic; Engine API endpoints keep their own query-token restrictions.

The edge credential must appear exactly once and contain a non-empty value. Empty, malformed, or repeated rstream.token parameters are rejected before the upstream is contacted. The engine never treats the application bearer as a fallback edge credential when a reserved query credential is invalid.

Managed projects accept personal access tokens, application tokens, and short-lived auth tokens. API permissions and resources.tunnels boundaries still apply. A token can be valid but rejected for a specific HTTP request when its boundaries 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 private deployments that run the rstream Auth integration. Community Edition deployments do not provide this browser authentication flow.

mTLS

mTLS authenticates the client during the TLS handshake before the HTTP request reaches the upstream service. The client certificate must match an mTLS Client Certificate (MTLS) credential, and the credential's Engine API permissions and resources.tunnels boundaries are applied by the engine.

Use mTLS when access should be tied to a private key held by a machine, service, device, or partner client. It is separate from the agent authentication used by rstream forward or SDK clients. Here, the certificate belongs to the client entering the published tunnel endpoint.

curl \
  --cert ./rstream-client.crt \
  --key ./rstream-client.key \
  https://<tunnel-host>/

See mTLS for credential setup, certificate generation, plan policy, and the distinction between agent authentication and published Tunnel access.

Combining authentication 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. An application bearer preserved behind a valid rstream.token query credential is forwarded data, not a second edge proof.

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

When mTLS is enabled alongside HTTP-layer authentication, each individual request must use one authentication proof. A request with a client certificate and a bearer token is rejected as ambiguous. A request with a client certificate and an rstream Auth session cookie is rejected for the same reason.

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

resources.tunnels boundaries can restrict HTTP tunnel access beyond token validity. A boundary 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 resource-boundary model. See Access policies for project-wide settings such as authenticated public access, trusted IPs, GeoIP restrictions, and minimum TLS version.