RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

robohub-auth

How a RoboHub application signs a person in: the keeper is the authorization
server, and the application accepts the session the keeper issues for it. The
plugin itself carries no code; the request middleware is generated by the
toolchain from the application's auth middleware in project.yml. Mesh,
aquarium and energy use it.

Using it

Declare the plugin under deps.robohub and name it in the manifest's
plugins: block:

deps:
  robohub:
    robohub-auth: ">=0.1.0"

plugins:
  - name: robohub-auth
    enabled: true

Then put the auth middleware on the application's target in project.yml.
What the applications write today is only the issuer and the public paths:

targets:
  - id: go-server
    middleware:
      - name: same_origin
      - name: auth
        options:
          issuer: keeper
          skip_paths: "/healthz,/auth/login,/assets,/assets/,/i18n,/auth/callback,/static,/ui,/docs"

Everything else follows from the application and the keeper that starts it:

OptionWhen left out
audienceThe application's deploy.service, else its module name: a session issued for another application is refused
cookierho_session_<audience>, so two applications on one host never overwrite each other's session
public_key~/.rho/auth/public.pem; without that file, the issuer's published key (/auth/public-key) is fetched and a copy kept
login_url/auth/login?audience=<audience> on the issuer: RHO_AUTH_URL, else the keeper's port (RHO_KEEPER_PORT, default 19090) on the host the request came to
skip_paths/healthz,/auth/login,/auth/callback,/static

A request with a valid session reaches the handler with X-Rho-Subject,
X-Rho-Scopes and X-Rho-Aud set. A browser without one is sent to the
keeper's login and comes back through /auth/callback with a one-time ticket;
an API caller (a path with /api/, or Accept: application/json) gets 401.
Sessions last eight hours and are kept in the application's workspace
(<workspace>/auth). An application started with RHO_AUTH_STANDALONE=1 has no
issuer and answers requests from its own machine only.

Behind the keeper

The keeper serves every application it runs at /app/<name>/ on its own origin
(unless its keeper.proxy_apps setting is off), so a browser only ever talks
to the keeper's port and the keeper's own cookie never reaches an application.
The keeper's proxy tells the application where it is reached with
X-Forwarded-Prefix (/app/aquarium), X-Forwarded-Host and
X-Forwarded-Proto. The application believes those headers only from the
loopback, where the keeper connects from, and builds its login return address
and callback under that prefix. No option is needed for this: the same build
works at its own port and behind the keeper.

Other deployments

The middleware also reads options for a deployment the keeper does not front.
No RoboHub application sets them today:

OptionWhat it is
mode: proxy, public_url, base_pathA reverse proxy of your own: the public origin and the path the application is served under, used for return addresses and the cookie path
trust_forwarded: "true"Believe X-Forwarded-Host and -Proto from any address (only behind a proxy you control)
schemehttps forces secure cookies and https return addresses; auto (the default) follows the connection
scopesScopes every session must hold, comma-separated
session_fileWhere sessions are kept, instead of the workspace

See architecture/security for how the keeper issues sessions and
grants.

Release history

[0.1.0] - 2026-11-04

The Keeper SSO plugin identity for rho-auth.