Heautou

Website

A minimal OpenID Connect provider for self-hosted setups. It gives your apps one shared sign-in ("Sign in with Heautou") without running Keycloak or Authentik.

• An OIDC provider for the authorization code flow, with a client secret or with PKCE. Apps find it through the standard discovery URL.
• A small web UI for adding the apps that sign in (clients) and the people who sign in (users), with groups, invite links, and a page where each user changes their own password.
• Nothing else to run. The data is in PGlite, a Postgres that runs inside the server, in one folder. Point DATABASE_URL at a Postgres server to keep it there instead.

[!WARNING] Heautou is built for a home or office network you trust. The admin UI needs a sign-in, but client secrets and signing keys are plain text in the database unless you set SECRET_KEY, and nothing has been audited. Don't expose it to the internet. See Security.

Quick start (Docker Compose)

1. Make a folder and save this as docker-compose.yml in it:

   services:
     heautou:
       image: ghcr.io/cubicecho/heautou:latest
       restart: unless-stopped
       environment:
         # The address your apps AND your browser use to reach Heautou, followed by /oidc.
         ISSUER_URL: http://192.168.1.10:3000/oidc
       ports:
         - "3000:3000"
       volumes:
         - heautou-data:/data
   
   volumes:
     heautou-data:
   

2. Change ISSUER_URL to this machine's address, such as its LAN IP, hostname or domain, keeping /oidc on the end. Leave it as localhost only if everything runs on one machine.

3. Start it:

   docker compose up -d
   

4. Open http://<your-host>:3000 within 10 minutes of starting it. While there is no admin, Heautou shows a Set up Heautou page: choose a username and password for the first admin, then sign in with them.

   After those 10 minutes, or to make a user that already exists the admin (when upgrading from a version before admin sign-in), the page needs the setup token from Heautou's log:

   docker compose logs heautou | grep setup
   

   The log line holds a link, http://<your-host>:3000/setup#token=…, that fills the token in. The token changes on every restart, so restarting also reopens the 10 minutes. Once there is an admin, the page is closed.

Your clients, users and keys are kept in the heautou-data volume (the database is in /data/pg), so they survive restarts and upgrades. To upgrade, run docker compose pull && docker compose up -d; the new version updates the database as it starts. Upgrading from a version that kept JSON files is covered in Your data.

Without Compose

docker run -d --name heautou --restart unless-stopped \
  -p 3000:3000 -v heautou-data:/data \
  -e ISSUER_URL=http://192.168.1.10:3000/oidc \
  ghcr.io/cubicecho/heautou:latest

On a Postgres server

Set DATABASE_URL to a postgres://user:password@host:5432/database URL (or DATABASE_URL_FILE to a file holding it, such as a Docker secret). Heautou creates its tables on the first start, and waits up to DB_CONNECT_TIMEOUT_MS (60 seconds) for Postgres to answer. To a host off your local network it requires TLS unless the URL sets sslmode.

From a clone of this repository, docker-compose.postgres.yml adds a Postgres of its own:

POSTGRES_PASSWORD=… docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d --build

Only one Heautou may use a database at a time; a second one, or the backup CLI while the server runs, refuses to start.

Connecting an app

1. Add a user. Under Users, choose New user and set a username. Name, email, groups and custom claims are optional; they are put into the user's tokens. Leave the password empty to invite them instead: Heautou gives you a link to send them (see Managing users). Only users in the heautou-admin group can use the admin UI; everyone else can only sign in to your apps.
2. Add a client. Under Clients, choose New client:
   • Name: what the sign-in page shows, such as "Grafana".
   • Redirect URIs: the app's callback URL. The app's OIDC docs give it, and it must match exactly.
   • Client authentication: keep Secret, Basic header unless the app says otherwise. Choose Public (PKCE) for browser-only or mobile apps that cannot keep a secret.
   • Allowed groups: leave empty to let every user in. Otherwise only members of these groups may sign in to the app; anyone else is told it is not for them.
   • Groups claim: the claim the app reads groups from. It is groups unless the app wants another name, such as roles.
   • Client credentials: turn on for a service with no users, such as a backup job, that gets its own token with grant_type=client_credentials. Such a client needs no redirect URI.
   • Allow the device flow: turn on for a device with no browser of its own, such as Home Assistant or a TV, that shows a code for the user to confirm on another device (see Devices). Such a client needs no redirect URI.
3. Copy the settings into the app. Open the client's row on the Clients page:

This is the beginning of the README. Read the rest at the original. Read the full README ↗