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

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.