From f2e4fd0beb1840926fff98366dbb21c045dcdeca Mon Sep 17 00:00:00 2001 From: Rick Barrette Date: Sat, 7 Nov 2026 15:22:44 -0500 Subject: [PATCH] Authentik reference: SSO, forward auth and the unauthenticated URL list Co-Authored-By: Claude Opus 5.5 --- README.md | 2 + docs/authentik.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/authentik.md diff --git a/README.md b/README.md index 7b0082b..3b01c7e 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,8 @@ The app is a standard Rails app. Run `bin/rails db:prepare && bin/thrust bin/rai Other OIDC providers (Keycloak, Google, Entra ID…) work the same way. +To keep the whole app behind Authentik's forward auth (proxy provider) while share links and outside mechanics' signing invitations still work, see [Running behind Authentik](docs/authentik.md): it has the unauthenticated URL list and what each one exposes. + ### Backups SQLite runs in WAL mode, so a plain file copy taken while the app is running can be inconsistent. Use the SQLite backup command instead: diff --git a/docs/authentik.md b/docs/authentik.md new file mode 100644 index 0000000..517b85f --- /dev/null +++ b/docs/authentik.md @@ -0,0 +1,116 @@ +# Running behind Authentik + +This is a reference for putting Simple Aircraft Manager behind [Authentik](https://goauthentik.io). Two separate pieces can be used together: + +1. **Single sign-on (OpenID Connect).** The app's sign-in page gets a **Sign in with Authentik** button, so people sign in with their Authentik account, and its two-factor rules. +2. **Forward auth (proxy provider).** The reverse proxy asks Authentik before letting any request reach the app, so nobody without an Authentik account can even see the app's pages. A short list of addresses is left open for share links and for outside mechanics signing an entry. + +The examples use `https://aircraft.example.com` for the app and `https://auth.example.com` for Authentik. Replace them with your own. + +## 1. Single sign-on + +### In Authentik + +1. **Applications → Providers → Create → OAuth2/OpenID Provider**: + - Client type: **Confidential**. + - Redirect URI (strict): `https://aircraft.example.com/auth/oidc/callback` + - Scopes: `openid`, `email`, `profile`. + - Signing key: any (the default certificate is fine). +2. **Applications → Applications → Create**: name it, pick the provider, and set the launch URL to `https://aircraft.example.com/`. +3. Optional: bind a group or policy to the application to limit who can use it. + +### In the app (environment variables) + +```bash +APP_URL=https://aircraft.example.com +OIDC_ISSUER=https://auth.example.com/application/o// +OIDC_CLIENT_ID=... +OIDC_CLIENT_SECRET=... +OIDC_PROVIDER_NAME=Authentik +# Optional: +OIDC_ADMIN_GROUP=aircraft-admins # members become app admins; others lose admin at sign-in +OIDC_AUTO_CREATE_USERS=true # create an account at first sign-in (new accounts have no aircraft) +``` + +Restart the app. The first SSO sign-in links an existing account with the same email if Authentik marks the email verified. Otherwise sign in with the password and use **Profile → Link Authentik**. + +**Keep password sign-in on** (leave `PASSWORD_LOGIN` unset) if outside mechanics will sign entries through invitations: they get an app account with a password, not an Authentik account. + +SSO sign-ins don't ask for the app's own authenticator code. Require MFA in the Authentik authentication flow instead (for example an authenticator validation stage). + +## 2. Forward auth + +### In Authentik + +1. **Applications → Providers → Create → Proxy Provider**, choose **Forward auth (domain level)** (or **Forward auth (single application)** for this app alone). For domain level, set the authentication URL (`https://auth.example.com`) and the cookie domain (`example.com`). +2. Add the unauthenticated URLs below to the provider's **Unauthenticated URLs** (domain level) or **Unauthenticated Paths** (single application) field. +3. Create an application for the provider and add it to your proxy outpost (**Applications → Outposts**, for example the embedded outpost). + +### In the reverse proxy (Traefik example) + +A forward-auth middleware pointing at the outpost, used on the app's router: + +```yaml +labels: + - traefik.http.middlewares.authentik.forwardauth.address=http://authentik-server:9000/outpost.goauthentik.io/auth/traefik + - traefik.http.middlewares.authentik.forwardauth.trustForwardHeader=true + - traefik.http.middlewares.authentik.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid + - traefik.http.routers.aircraft.rule=Host(`aircraft.example.com`) + - traefik.http.routers.aircraft.middlewares=authentik@docker +``` + +Check the [Authentik documentation for your proxy](https://docs.goauthentik.io/docs/add-secure-apps/providers/proxy/server_traefik) for the outpost routes your setup needs (nginx, Caddy and others work the same way). + +The app doesn't read the `X-authentik-*` headers: people still sign in to the app itself, either with **Sign in with Authentik** (immediate, since they're already signed in to Authentik) or with a password. + +### Unauthenticated URLs + +For domain-level forward auth, Authentik matches each line as a regular expression against the full URL. For single-application mode, drop the `^https://aircraft\.example\.com` part and match the path. + +``` +^https://aircraft\.example\.com/manifest\.json$ +^https://aircraft\.example\.com/service-worker\.js$ +^https://aircraft\.example\.com/offline\.html$ +^https://aircraft\.example\.com/favicon\.svg$ +^https://aircraft\.example\.com/icon(-192|-maskable)?\.(png|svg)$ +^https://aircraft\.example\.com/apple-touch-icon\.png$ +^https://aircraft\.example\.com/assets/.+$ +^https://aircraft\.example\.com/shared/[A-Za-z0-9]{32}(/report)?$ +^https://aircraft\.example\.com/rails/active_storage/(blobs/redirect|disk)/.+$ +^https://aircraft\.example\.com/sign/[A-Za-z0-9_-]{43}(/account)?$ +^https://aircraft\.example\.com/session(/new|/two_factor)?(\?.*)?$ +^https://aircraft\.example\.com/profile/certificates(\?.*)?$ +^https://aircraft\.example\.com/profile/two_factor(/new|/recovery_codes)?(\?.*)?$ +^https://aircraft\.example\.com/help/records$ +``` + +What each group is for: + +| Lines | Needed for | What's exposed | +|---|---|---| +| `manifest.json`, `service-worker.js`, `offline.html`, icons | Installing the app on a phone (the browser fetches these without cookies), and share pages | Static files with no data | +| `/assets/…` | Styles and scripts for share pages and the signing pages | Static files with no data | +| `/shared/`, `/shared//report` | Read-only share links (Access & Sharing) | Only with a valid, unexpired, unrevoked 32-character token, and only what that link's level shows | +| `/rails/active_storage/blobs/redirect/…`, `/rails/active_storage/disk/…` | The aircraft picture and shared documents on share pages | A file only to someone holding its signed link (from a page they could see). Disk links expire after a few minutes; redirect links don't, so a forwarded link keeps working | +| `/sign/`, `/sign//account` | Outside mechanics signing an entry from an emailed invitation | Only with a valid, unused invitation token (43 characters, 14-day expiry, stored as a fingerprint) | +| `/session`, `/session/new`, `/session/two_factor` | The app's own sign-in, for invited mechanics | The sign-in page. Protected by rate limits, the account lockout (10 failures lock an account for 15 minutes) and optional authenticator codes. A signed-in app account still can't reach any other page through the proxy | +| `/profile/certificates` | Invited mechanics adding their certificate before signing | Adding a certificate to their own account; it only returns to a `/sign/…` page | +| `/profile/two_factor…` | Invited mechanics setting up an authenticator app | Their own two-factor setup | +| `/help/records` | The "How signing works" link on the signing form | The signing instructions, for signed-in accounts | + +Leave out lines for features you don't use: without share links drop `/shared` and Active Storage; if mechanics never sign through invitations drop `/sign`, `/session`, `/profile/…` and `/help/records`. + +Everything else stays behind Authentik: the fleet, records, admin pages, the emailed sign-in links and password resets (an invited mechanic who forgets their password asks the administrator, who resets it under Admin → Users or sends a new invitation), and the Google Drive callback (`/admin/offsite_backup/callback`), which comes back to the administrator's own signed-in browser. + +### Checking it + +In a private window: + +1. `https://aircraft.example.com/` should go to Authentik. +2. A share link should open without signing in, styled, with the aircraft picture. +3. A signing invitation should let you create an account (or sign in), add a certificate and sign. +4. After that, `https://aircraft.example.com/aircraft` in the same window should still go to Authentik. + +### Client addresses + +The app's rate limits and logs use the client's IP address. Rails trusts `X-Forwarded-For` from proxies on private networks (Docker networks included), so behind Traefik on the same Docker host the real address comes through. If the proxy reaches the app from a public address, configure `config.action_dispatch.trusted_proxies`.