Files
rust-discovery/crates/server/OIDC.md
T
BuTzZ 6c3203d725
Rust development slice / linux (push) Failing after 1m10s
feat: snapshot Linux-first RMM MVP and pause handover
2026-11-12 22:06:25 +01:00

201 lines
12 KiB
Markdown

# Integrated OIDC/OAuth authentication
The server now wires `rmm-oidc-auth` into real browser, HTTP and MCP paths. External
IdP deployment is **not_configured** unless the administrator supplies configuration.
No external-provider interoperability or production/VM acceptance is implied.
## Configuration
Set `RMM_OIDC_CONFIG_FILE` to an absolute, regular non-symlink **0600** JSON file
with a same-owner, non-group/world-writable parent. All secret references are absolute
0600 private files with that same owner and safe parent. Their contents are never
passed as argv, logged, reflected in errors or read as shell. Example (placeholders):
```json
{
"issuer": "https://idp.example/realms/rmm",
"browser_client_id": "rmm-browser",
"client_secret_ref": "/private/rmm/oidc-client-secret-v1",
"redirect_uri": "https://rmm.example/auth/oidc/callback",
"mcp_audience": "https://rmm.example/mcp",
"mcp_client_ids": ["approved-mcp-client"],
"auth_database_url_ref": "/private/rmm/oidc-auth-database-url",
"state_key_ref": "/private/rmm/oidc-state-key-v1",
"extra_ca_file": null,
"testsimulation": false
}
```
`RMM_UI_ORIGIN` must be the exact HTTPS origin without trailing slash. The callback
must equal that origin plus `/auth/oidc/callback`. Normal roots are used; optional
`extra_ca_file` explicitly provisions a private IdP CA, never an insecure TLS mode.
Issuer discovery/JWKS/endpoints use configured-issuer same-origin HTTPS, no redirects,
fixed RS256 and bounded requests. The supported provider profile is documented in
`../oidc-auth/README.md` (PKCE S256, nonce, client_secret_post; RFC9068 access tokens).
`state_key_ref` contains 32 random bytes encoded as unpadded base64url, with an
immutable versioned reference. The package's AES-256-GCM state protection, 300-second
TTL, atomic binding/consume, capacity and drain-before-key-rotation rules remain intact.
Global state cleanup runs in bounded 1,000-row batches every 30 seconds.
Production requires `RMM_PROFILE=production`, `RMM_DEV_AUTH=false`, configured OIDC
and **no** RMM_DEV_USERNAME/PASSWORD, RMM_OPERATOR_A/B or RMM_VIEWER_A/B values.
Production with dev auth is rejected before connecting. `testsimulation=true` is
accepted only in the explicit development profile, never derived from token claims.
Development retains the existing separately credentialed browser/viewer/operator
paths. Neither profile silently falls back after invalid explicit bearer credentials.
Non-OIDC production gaps remain: the local ArtifactStore is still development-only;
artifact-dependent features fail closed until a production adapter is supplied.
Root/APT selected policies remain development-only and unchanged in their authority.
## Migration and provisioning
Normal migration **0011_oidc_auth.sql** creates global encrypted pre-auth state and
the administrator-maintained external identity index, extends membership kind with
`human` and constrains authorization audit pairs to exactly:
- `dev_test_browser_simulation` + `testsimulation=true`
- `human_webui` + `testsimulation=false`
The runtime does **not** create schemas, tables, identities, memberships or roles.
Apply normal migrations without resetting DB/PKI. Provision a separate global-auth
login identity with only schema USAGE and table SELECT/INSERT/DELETE on
`rmm_oidc_auth.login_states`. The server verifies that this pool is neither superuser,
BYPASSRLS, table owner nor schema creator, and cannot SELECT tenant memberships.
The tenant application pool remains `rmm_app`, nonowner and RLS-bound. Neither needs
a general RLS bypass. Do not reuse the tenant application's database URL for auth state.
An administrator explicitly registers each external `(issuer,subject)` in
`public.oidc_principals` and assigns tenant routing references; the principal ID is:
`oidc:` + lowercase SHA-256 hex of compact UTF-8 JSON `[issuer,subject]`.
Rust helper: `oidc::principal_id`. Email/group claims are never identity or membership.
The index is routing metadata only: each chosen tenant still requires a current,
unrevoked `memberships` row with explicit permissions. Browser login additionally
requires membership kind **human**. No auto-registration, tenant or role grants occur.
Disabling the index entry revokes subsequent auth and persisted permission rechecks,
including start-time rights checks for existing plans. Membership revocation is read
on every authenticated HTTP/MCP call, not cached from an ID token or browser session.
Only narrow, fixed-search-path SECURITY DEFINER lookup functions expose identity
routing/enabled status to rmm_app; they do not bypass/query memberships RLS or return
foreign inventory. MCP/HTTP permissions intersect the validated access-token scopes
with current membership. Script/root operations retain their additional permission
and selected-helper checks. Bearers have no interactive session context, even with
an approver membership/scope plus a valid browser cookie.
## UI-compatible routes and cookie contract
- `GET /auth/config`: `{oidc_configured,oidc_login_url,dev_login_enabled}`.
`oidc_login_url` is `/auth/oidc/login` when configured, otherwise null. UI can show
a nonempty configured-provider sign-in link without knowing secrets.
- `GET /auth/oidc/login`: code-flow redirect, binding cookie
`__Host-rmm_oidc_binding`, Secure/HttpOnly/Path=/, **SameSite=Lax**, 300 seconds.
- `GET /auth/oidc/callback`: code + state (optional issuer response check), duplicate
query/cookie rejection, one-use DB state, token exchange and nonce/PKCE/signature
checks, persistent principal/membership mapping. Clears binding on success/failure.
Establishes a new opaque RMM session and redirects only to `/`, never user input.
- `GET /auth/session`: existing DTO retained (`principal`, `tenant_id`, `permissions`,
`roles`, `csrf_token`, `testsimulation`, `approval_origin`). Final cookie remains
`__Host-rmm_session`, Secure/HttpOnly/host-only, **SameSite=Strict**, one hour.
Sessions remain in memory; restart requires fresh OIDC login, not job resubmission.
- `POST /auth/logout`: exact Origin + session CSRF; server-side invalidation and cookie
clearing. Local RMM logout only; no false claim of IdP logout.
All auth responses are no-store/no-referrer. Do not enable callback/query logging,
browser traces, HAR, screenshots or third-party resources on auth pages. Browser
writes and plan authorizations retain exact Origin/CSRF and immutable plan binding.
Tenant selection comes from the API path, overriding an incoming X-RMM-Tenant header;
MCP dispatch selects its explicit tenant_id. X-RMM-Tenant is only a selection hint for
other calls, never authority: it must exist in the mapped index AND current tenant
membership. `/api/v1/tenants` lists current readable memberships using separate RLS
transactions. Foreign tenant/asset paths remain not-found, not token-controlled routing.
## Targeted integration tests
`python3 tests/oidc/server_integration.py` starts an ephemeral native TLS mock IdP
and native loopback API instance against the existing development PostgreSQL. It
provisions/removes only its own synthetic identity/human membership and a distinct
restricted auth-state login role. No approval/job/permit/VM fixture is fabricated.
It uses a private ephemeral CA, real RSA signatures/JWKS, actual one-use code exchange
and PKCE. The Chromium step uses a temporary NSS truststore, no TLS bypass/artifacts,
and actual provider UI navigation/cross-site callback; **no job approval** occurs.
It also starts a configured production-profile API with simulation false to check
the production auth path, not to claim real-provider/human production acceptance.
Credentials are parsed internally from local private development configuration;
never printed, sourced, passed in argv or included in test failure output.
Existing backend contract, transport, pages/catalog, sync and local integration tests
remain required after deployment. Actual commands/counts are returned by the dispatch;
the descriptions here are not presumed successful test results.
## Verified local auth increment (2026-11-12)
- Native server build and `cargo clippy -p rmm-server --all-targets --locked -- -D warnings`
passed; changed server files passed targeted rustfmt checking.
- Targeted Rust tests: server **7**, domain **11**, protocol **3**, persistence **0**;
all passed. Three server tests cover the added cookie/scope/identity contracts.
- Standalone OIDC package: **13** unit tests passed; the ordinary run explicitly
ignores its owner-opt-in database test, then `tests/run_postgres.py` ran that **1**
real PostgreSQL integration test successfully (1/16 consume, 2/8 capacity).
- Integrated native server/real mock TLS/real PostgreSQL/Chromium test:
**35 assertions passed**, including production-profile startup with OIDC configured,
simulation false and dev login absent, and actual MCP tool scope enforcement.
No plan was approved or executed by this increment.
- Python syntax checks and Node browser-script syntax check passed.
Initial build/harness failures were corrected without weakening checks: root Cargo
needed to exclude the nested standalone OIDC workspace; Python environment merging
needed to avoid duplicate keywords; dev login must not register its JSON extractor
route in production; MCP testing must consume a concrete SSE response instead of
waiting for stream closure. A backend regression also exposed that tenant-denied
authentication must preserve NOT_FOUND in the MCP/HTTP structured error code; the
shared mapper now preserves it instead of calling every failure UNAUTHENTICATED.
External IdP configuration and all VM/real-human production-approval acceptance
remain open. The running development deployment intentionally retains its existing
dev identities unless an administrator provisions the OIDC configuration and the
separate state-pool identity; no sample provider is silently enabled there.
### Final deployed backend verification
Normal additive migrations **0009, 0010 and 0011** were applied without DB/PKI
reset; successful migration history is **1 through 11**. Docker release build of
server **and agent** succeeded after adding the exact embedded helper unit
`deploy/linux/rmm-apt-helper.service` to the Docker COPY/context whitelist. The
unit/helper/provider source and its hardening were not altered by this auth work.
`python3 deploy/dev.py up` rebuilt/recreated only the project server/migration service;
existing PostgreSQL stayed running. Final server observation:
- started **2026-11-12T19:12:38.969913632Z**, status running;
- image `sha256:545318218433a5d0be96c9368096cb2850b059be0b690bee5044ab28aad5cb82`;
- published TLS port only `127.0.0.1:18443`; PostgreSQL has no published port;
- actual `/auth/config` returns dev login enabled, OIDC not configured, login URL null.
All five affected backend integration programs then passed against that deployment:
| Program | Actual PASS assertions |
| --- | ---: |
| `tests/backend_contract.py` | 42 |
| `tests/backend_transport.py` | 20 |
| `tests/backend_pages_catalog.py` | 25 |
| `tests/backend_sync.py` | 28 |
| `tests/local_integration.py` | 35 |
| **Total** | **150** |
These are assertion counts in five integration programs, not 150 Rust test cases.
They cover unchanged immutable pending/approval boundaries, mTLS and rotation,
fencing/housekeeping, catalog/pagination/membership, signing-key/bootstrap,
Sync/reconnect/restore denial, extended native inventory and tenant isolation.
The final NOT_FOUND mapper correction passed the previously failing MCP foreign-
tenant contract. Four additional actual database-boundary assertions passed:
rmm_app cannot directly read pre-auth state or the external identity index, the
narrow lookup rejects a missing identity, and rmm_app remains non-superuser/non-BYPASSRLS.
No VM/systemd/root/APT effect, positive plan approval or privileged-helper execution
was performed by this dispatch. Linux-MVP, positive consumed-job/helper SyncAck and
real external-IdP/human production-approval acceptance remain separate gates.