201 lines
12 KiB
Markdown
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.
|