# n8n Single Sign-On via Traefik ForwardAuth

## How it works

### Production (real domains)

In production, the app and n8n share a parent domain (e.g., `example.com` and `n8n.example.com`). When a super admin opens an admin tool, the app mints a `vc-admin-token` cookie scoped to `domain=.example.com`, so it's sent to all subdomains. It carries a dedicated ForwardAuth token (1 hour, bound to the minting session), never the app's session token. The flow:

1. User visits `n8n.example.com`
2. Traefik applies `super-admin-auth@file` middleware (ForwardAuth)
3. `verify-role.ts` reads the `vc-admin-token` cookie, looks its hash up in the database together with the session it is bound to, and checks the `super_admin` role
4. On success, Traefik forwards `X-User-Email` header to n8n
5. `hooks.js` middleware reads the header, finds/creates the n8n user, issues `n8n-auth` session cookie
6. User sees the n8n editor — no login page

### Development (localhost)

In dev, `localhost` and `n8n.localhost` are treated as **separate domains** by browsers (`.localhost` is a public suffix). Cookies set on `localhost` are NOT sent to `n8n.localhost`. This means ForwardAuth can't work — the auth cookie never reaches the verify-role endpoint.

Instead, n8n uses its **own built-in auth** in dev:

1. `setup.sh` sidecar gives n8n's owner your admin email and a password hash from `N8N_ADMIN_PASSWORD_HASH`, which only the dev compose override sets (a bcrypt hash of `changeme`)
2. User visits `http://n8n.localhost` → sees n8n's login page
3. Logs in with their admin email and the password `changeme`

In production nothing sets `N8N_ADMIN_PASSWORD_HASH`, so `setup.sh` stores a random value nobody knows. Nobody signs in with a password there: ForwardAuth and `hooks.js` sign super admins in.

The SSO hook (`hooks.js`) is still loaded but has no effect since ForwardAuth headers are absent — it calls `next()` and falls through to n8n's normal auth.

## Architecture

```
Production:
  Browser → Traefik → ForwardAuth (verify-role) → n8n (hooks.js sets cookie)
                           │                            │
                      Reads vc-admin-token         Reads X-User-Email
                      Sets X-User-* headers        Issues n8n-auth cookie

Development:
  Browser → Traefik → n8n (no ForwardAuth, native login)
```

## Components

| Component | File | Purpose |
|-----------|------|---------|
| SSO hook | `volumes/n8n/hooks.js` | Express middleware: reads `X-User-Email`, auto-creates user, issues session cookie |
| DB setup sidecar | `volumes/n8n/scripts/setup.sh` | Sets the skeleton owner's email and password hash in PostgreSQL so the setup wizard is skipped |
| ForwardAuth config (prod) | `volumes/traefik/middlewares.yml` | Chains header stripping → role verification |
| ForwardAuth config (dev) | `volumes/traefik/middlewares.dev.yml` | Same, routes to `host.docker.internal:3000` |
| Verify-role endpoint | `src/server/routes/_internal/verify-role.ts` | Checks the ForwardAuth token and role, sets `X-User-*` headers |
| Compose (dev) | `docker-compose.n8n.yml` | No ForwardAuth middleware on n8n router |
| Compose (prod) | Production overlay adds `super-admin-auth@file` middleware label |

## Key implementation details

### hooks.js (n8n v2.x / Express 5)

- **Export format**: `{ n8n: { ready: [fn] } }` — two-level nested, NOT `{ 'n8n.ready': [fn] }`
- **Router access**: Express 5 uses `app.router.stack` (not `app._router.stack`)
- **Layer creation**: Take the class from an existing layer (`layers[i].constructor`) to create proper Layer instances (plain objects cause `layer.match is not a function`, and `require('router/lib/layer')` fails because n8n's pnpm layout does not hoist `router`)
- **User repository**: Available via `this.dbCollections.User` (provided by hook context)
- **Session cookies**: Use `Container.get(AuthService).issueCookie()` from `@n8n/di` (not `@n8n/api` which doesn't exist)
- **User role column**: n8n v2.x uses `roleSlug` (FK to `role` table), not `role`
- **User lookup**: Must include `relations: ['role']` for `issueCookie()` to work

### setup.sh (n8n v2.x schema)

n8n v2.x auto-creates a skeleton owner row (no email) during migration. The setup script:

1. Waits for n8n's `user` table to exist
2. UPDATEs the skeleton owner to set email, name, password hash, and `lastActiveAt`. The hash is `N8N_ADMIN_PASSWORD_HASH`, or a random value when it is unset (every production deploy)
3. Falls back to INSERT (with `roleSlug`) if no skeleton owner exists
4. Sets `userManagement.isInstanceOwnerSetUp = true` in the `settings` table

psql runs with `ON_ERROR_STOP` in one transaction, so any SQL error exits the script non-zero and success is never logged after one. The same script ships from `services/n8n/scripts/` and `carbon/volumes/n8n/scripts/`, and a unit test keeps the two identical.

All three are required to skip the setup wizard:
- `hasInstanceOwner()` checks: `password IS NOT NULL` OR `lastActiveAt IS NOT NULL`
- `showSetupOnFirstLoad` checks: `!(await hasInstanceOwner())`
- Frontend also checks the `isInstanceOwnerSetUp` setting

### DB password

The n8n compose uses `POSTGRES_PASSWORD` (the project's DB password) for the n8n DB connection. This matches what `n8n-init.sh` sets for the `n8n` PostgreSQL role. Do NOT use a separate `N8N_DB_PASSWORD` with a different default.

## Troubleshooting

### n8n crash loop: "Problem loading external hook file"

Check the export format. n8n's `loadHooks()` expects `{ resource: { operation: [fn] } }`. A flat key like `'n8n.ready'` causes `Spread syntax requires ...iterable[Symbol.iterator]` because it tries to spread a function.

### n8n crash loop: "layer.match is not a function"

The hooks.js spliced a plain object into Express 5's router stack. Build it from an existing layer's class (`layers[i].constructor`) so it is a proper Layer instance.

### Setup wizard still appears

Check all three conditions:
```bash
# 1. Owner has password or lastActiveAt
docker compose exec db psql -U postgres -d n8n -c \
  "SELECT email, password IS NOT NULL, \"lastActiveAt\" FROM \"user\" WHERE \"roleSlug\" = 'global:owner';"

# 2. Setting is true
docker compose exec db psql -U postgres -d n8n -c \
  "SELECT value FROM settings WHERE key = 'userManagement.isInstanceOwnerSetUp';"

# 3. REST API confirms
curl -s http://n8n.localhost/rest/settings | python3 -m json.tool | grep showSetup
```

### "password authentication failed for user n8n"

The n8n compose DB password doesn't match what `n8n-init.sh` set. Both read `N8N_DB_PASSWORD` from `.env.local`; if it changed after the first boot, set it on the role again (`vibecarbon up` locally reruns `n8n-init.sh`; on a server run `\password n8n` in `sh vc-compose exec db psql -U postgres` from the project directory).

### ForwardAuth returns 401 in production

1. Check the `vc-admin-token` cookie is set with the correct domain (`.example.com`); open the tool from the app's admin panel, which mints it
2. Check `authRequestHeaders` includes `Cookie` and `Accept`
3. Check the user's `role` column is `super_admin` (`SELECT role FROM "user" WHERE email = '...'`)
4. With MFA on globally, the minting session must have passed its second factor

### SSO hook doesn't fire (no log output)

1. Verify hooks.js is mounted: `docker exec <n8n> cat /home/node/.n8n/hooks.js`
2. Check `EXTERNAL_HOOK_FILES` env var is set
3. Check for `[hooks.js] ForwardAuth SSO middleware installed` in logs
4. If middleware installed but not firing, check for stale `n8n-auth` cookie (hook skips when present)
