mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 15:50:36 -05:00
Authentik reference: SSO, forward auth and the unauthenticated URL list
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
14316bb60f
commit
f2e4fd0beb
2 files changed
+118
No files matched your search
@@ -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:
|
||||
|
||||
@@ -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/<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=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/<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 | 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`.
|
||||
Reference in new issue
Block a user