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:
| Option | When left out |
|---|---|
audience | The application's deploy.service, else its module name: a session issued for another application is refused |
cookie | rho_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:
| Option | What it is |
|---|---|
mode: proxy, public_url, base_path | A 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) |
scheme | https forces secure cookies and https return addresses; auto (the default) follows the connection |
scopes | Scopes every session must hold, comma-separated |
session_file | Where 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.