- Admin → Settings → Who can add aircraft: administrators only (the default) or everyone. Adding an aircraft or importing a .sam.zip makes you its Owner, so this decides who can become one. - A signing invitation from an Owner of the aircraft (or an administrator) lets the outside mechanic create an account for the invited address again, with a password or by signing in with SSO; checked when it's used. Others' signing invitations still need an existing account, and say so. - Docs: who makes accounts, the new setting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.0 KiB
Running behind Authentik
This is a reference for putting Simple Aircraft Manager behind Authentik. Two separate pieces can be used together:
- 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.
- 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
- 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).
- Applications → Applications → Create: name it, pick the provider, and set the launch URL to
https://aircraft.example.com/. - Optional: bind a group or policy to the application to limit who can use it.
In the app (environment variables)
APP_URL=https://aircraft.example.com
OIDC_ISSUER=https://auth.example.com/application/o/<application-slug>/
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=false # true: an account for anyone Authentik lets in, without an invitation
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
- 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). - Add the unauthenticated URLs below to the provider's Unauthenticated URLs (domain level) or Unauthenticated Paths (single application) field.
- 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:
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 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|js)$
^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$
^https://aircraft\.example\.com/calendar/[A-Za-z0-9]{32}\.ics$
What each group is for:
| Lines | Needed for | What's exposed |
|---|---|---|
manifest.json, service-worker.js, offline.html, offline.js, 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/<token>, /shared/<token>/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/<token>, /sign/<token>/account |
Outside mechanics signing an entry from an emailed invitation (creating their account from an Owner's 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 |
/calendar/<token>.ics |
Calendar apps fetching the due-items feed (Profile → Calendar feed) | The due list of that user's aircraft, only with their secret 32-character token; making a new link retires the old one |
New accounts come only from an administrator, an administrator's invitation (opening the link, then Continue with Authentik, makes the account and accepts it) or an Owner's signing invitation (for its address). With OIDC_AUTO_CREATE_USERS=true instead, anyone Authentik lets in gets an account (with no aircraft) without an invitation.
Invitation links (/join/…) are deliberately not on the list: behind forward auth, someone with only an app account still couldn't get past the proxy to use the app, so invited people need an Authentik account anyway. They sign in to Authentik, then open the link and accept it.
Leave out lines for features you don't use: without share links drop /shared and Active Storage; without calendar feeds drop /calendar; 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:
https://aircraft.example.com/should go to Authentik.- A share link should open without signing in, styled, with the aircraft picture.
- An Owner's signing invitation should let you create an account (or sign in), add a certificate and sign.
- After that,
https://aircraft.example.com/aircraftin 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.