165 lines
10 KiB
Markdown
165 lines
10 KiB
Markdown
# RMM OIDC authentication adapter (standalone package)
|
|
|
|
Optional encrypted SQLx/PostgreSQL login-state storage and its migration/permissions
|
|
contract: **[POSTGRES.md](POSTGRES.md)** (`postgres-state` feature).
|
|
|
|
This crate is **not wired into the server** and does not change the root workspace.
|
|
It authenticates against a configured HTTPS OIDC provider using real RSA signatures,
|
|
discovery, JWKS and authorization-code exchange. It never grants tenant membership,
|
|
roles, approval authority or an RMM session by itself. External IdP configuration is
|
|
currently **not_configured**; no external-provider or VM acceptance is claimed.
|
|
|
|
## Explicit supported provider profile
|
|
|
|
- RS256 only, RSA signing JWKS with unique `kid`, `alg=RS256`, `use=sig`.
|
|
Mixed-algorithm JWKS are deliberately rejected by this initial strict profile.
|
|
- Configured issuer is the only authority. Discovery's issuer must match exactly;
|
|
authorization, token and JWKS endpoints must be HTTPS, same **origin** (including
|
|
port) as that issuer, with no userinfo, fragment or query. Providers using a separate
|
|
CDN/origin for JWKS are not supported, rather than automatically trusted.
|
|
- Normal rustls trust roots, optional explicitly provisioned CA roots; no HTTP,
|
|
insecure certificate mode, HTTP redirects or environment proxy. Administrators
|
|
must restrict configured issuers/network egress; user input cannot choose issuers.
|
|
- Browser: authorization code, `openid`, PKCE S256, random nonce/state/browser binding,
|
|
fixed registered HTTPS callback, `client_secret_post`. The IdP must advertise these
|
|
features. PKCE rejection surfaces as `CodeExchange`; response bodies are not logged.
|
|
- MCP: RFC 9068 JWT **access** token with `typ=at+jwt`, dedicated resource audience,
|
|
approved `client_id`, required `jti`, issuer/signature/expiry/nbf/iat checks, required scopes.
|
|
Opaque/introspected tokens and other JWT access-token profiles are unsupported.
|
|
Browser ID tokens are never accepted as bearer credentials.
|
|
- JWT validity uses zero clock leeway; synchronize clocks. Browser multiple audiences
|
|
require matching `azp`; any supplied browser `azp` must match the browser client ID.
|
|
- JWKS cache TTL 300 seconds; unknown-kid refresh throttled to once per second,
|
|
serialized across callers. A newly rotated key may require retry after one second.
|
|
Invalid JWKS/failed refresh clears the old key cache and fails closed. Revocation of
|
|
a cached key is bounded by the TTL, not instantaneous. Issuer operator must rotate
|
|
to a **new kid** (same-kid replacement is visible on the next TTL refresh).
|
|
- HTTP connect timeout 3 seconds, total request timeout 10 seconds, response 128 KiB,
|
|
JWT 32 KiB, code 4 KiB, maximum 64 signing keys. No refresh-token persistence.
|
|
|
|
## Public integration API
|
|
|
|
```rust,ignore
|
|
let auth = OidcAuth::discover(
|
|
Config {
|
|
issuer: Url::parse("https://idp.example/realms/rmm")?,
|
|
browser_client_id: "rmm-browser".into(),
|
|
client_secret_ref: "secret-store:rmm/oidc-client".into(),
|
|
redirect_uri: Url::parse("https://rmm.example/auth/oidc/callback")?,
|
|
mcp_audience: "https://rmm.example/mcp".into(),
|
|
mcp_client_ids: BTreeSet::from(["approved-mcp-client".into()]),
|
|
},
|
|
Profile::Production,
|
|
persistent_state_store,
|
|
secret_resolver,
|
|
vec![], // normal roots; provision a private CA explicitly if necessary
|
|
).await?;
|
|
let start: LoginStart = auth.login_start().await?;
|
|
// Set start.binding_set_cookie and redirect to start.authorization_url.
|
|
let identity: Identity = auth.callback(Callback {
|
|
code: parsed_query_code,
|
|
state: parsed_query_state,
|
|
browser_binding: parsed_host_binding_cookie,
|
|
}).await?;
|
|
let bearer: BearerIdentity = auth
|
|
.verify_mcp_bearer(raw_bearer, &["inventory:read"]).await?;
|
|
```
|
|
|
|
`SecretResolver::resolve(reference)` returns `secrecy::SecretString`; resolve from an
|
|
authorized secret store, never from a token claim. The adapter exposes only coarse
|
|
typed `Error`s, not reqwest errors (which may contain URLs), codes or token bodies.
|
|
Do not log callback URLs, authorization URLs, cookies, state records, secrets or JWTs.
|
|
Sensitive flow types intentionally do not implement `Debug`.
|
|
|
|
### Required server/cookie adapter work (not implemented here)
|
|
|
|
1. Register login start and **GET** callback routes. Rate-limit both; do not allow
|
|
caller-supplied issuer, audience, scopes, redirect URI or post-login return URL.
|
|
Reject duplicate query/cookie parameters and provider error callbacks. Return
|
|
`Cache-Control: no-store` and `Referrer-Policy: no-referrer` on all auth routes;
|
|
avoid request/query logging and third-party resources there.
|
|
2. Set `LoginStart.binding_set_cookie` verbatim: `__Host-rmm_oidc_binding`, Secure,
|
|
HttpOnly, Path=/, **SameSite=Lax**, Max-Age=300, no Domain. Strict would omit this
|
|
cookie on the cross-site provider callback. Start replaces an outstanding binding;
|
|
multi-tab login is intentionally fail-closed, not a bypass.
|
|
3. Pass only parsed code/state and binding cookie value to `callback`. The store must
|
|
atomically consume state before token exchange. On terminal callback success or
|
|
failure, clear binding with `CLEAR_BINDING_COOKIE`; failures require fresh login.
|
|
4. Resolve `Identity { issuer, subject }` to a persistent principal and **current**
|
|
scoped memberships. Email and untrusted group/role claims are not identity keys or
|
|
memberships (this crate does not expose them). No implicit all-tenant role.
|
|
5. On browser success only, rotate/create a new opaque RMM session, bound to that
|
|
principal, with bounded expiry and the existing Secure/HttpOnly/host-only
|
|
**SameSite=Strict** final session cookie. Keep CSRF token + exact Origin checks
|
|
for writes, authorization checks and explicit UI plan approval. An ID token is
|
|
not an RMM session cookie or permission to approve a plan.
|
|
6. Bearer always wins over browser cookies. Use `verify_mcp_bearer` only for MCP/API
|
|
bearer paths; combine returned scopes with persistent memberships on **every**
|
|
request. Never construct an interactive browser session or approval context from
|
|
a bearer token, even if a principal has an approver membership. Preserve
|
|
`pending_approval` and all immutable plan/attempt bindings.
|
|
7. Logout must invalidate the **server-side RMM session**, clear the final cookie,
|
|
require its normal CSRF/Origin checks and prevent reuse. IdP logout is intentionally
|
|
not implemented or falsely advertised; local logout does not end an IdP session.
|
|
8. Disable dev identities/simulated principals in production independently of this
|
|
crate. Existing dev identity auth is not replaced until the backend is integrated.
|
|
|
|
### Persistent state store port
|
|
|
|
Alternative adapters must implement async `StateStore::{insert, consume}` plus `is_persistent() == true` using
|
|
shared durable storage. Do not merely return true for a memory-backed adapter.
|
|
State lookup keys and browser bindings supplied to the store are SHA-256 base64url
|
|
hashes; records contain nonce, verifier and absolute Unix expiry. Protect record
|
|
contents at rest and restrict database access. `insert` must enforce unique keys,
|
|
bounded capacity and expiry cleanup. `consume` must perform one atomic conditional
|
|
delete/return based on `(state_hash, binding_hash, expires_at > now)`; no read-then-
|
|
delete race, no restoration after exchange/nonce failure. A SQL transaction or
|
|
`DELETE ... WHERE ... RETURNING` is suitable. Store failures must fail closed.
|
|
|
|
`dev::InMemoryStateStore::new(dev::DevTestOnly)` exists only under the explicit
|
|
`dev-memory-store` feature or unit tests. `Profile::Production` rejects it. This is
|
|
not a production SQL adapter. The optional PostgreSQL adapter below supplies durable
|
|
encrypted storage; applying its migration and server wiring remain integration work.
|
|
|
|
## Targeted local verification
|
|
|
|
```sh
|
|
cargo fmt --manifest-path crates/oidc-auth/Cargo.toml --check
|
|
cargo clippy --manifest-path crates/oidc-auth/Cargo.toml --all-targets --all-features -- -D warnings
|
|
cargo test --manifest-path crates/oidc-auth/Cargo.toml --all-features
|
|
```
|
|
|
|
Tests run a native loopback HTTPS OIDC provider with an ephemeral private CA, real
|
|
2048-bit RSA signing keys/JWKS, actual one-use authorization codes, real form-encoded
|
|
token exchange and server-enforced PKCE. The CA is added only to the test clients,
|
|
never to the host truststore. No checked-in private key, external IdP, VM modification,
|
|
host-service installation, Docker/server restart or reboot is needed. The provider
|
|
is a test double, not a claim of external-provider interoperability or VM acceptance.
|
|
Test assertions/counters contain no secret output. Run results are reported separately
|
|
by the implementation dispatch, not presumed by these commands.
|
|
|
|
### Actual local verification (2026-11-12)
|
|
|
|
Executed on the development Linux host, not the Linux test VM:
|
|
|
|
- `cargo fmt --manifest-path crates/oidc-auth/Cargo.toml --check`: passed.
|
|
- `cargo clippy --manifest-path crates/oidc-auth/Cargo.toml --all-targets --all-features -- -D warnings`: passed.
|
|
- `cargo test --manifest-path crates/oidc-auth/Cargo.toml --all-features --locked`:
|
|
**13 passed, 0 failed**; 0 documentation tests. Covers real code exchange,
|
|
browser binding/replay/expiry/concurrency, PKCE failure, nonce/authorized party,
|
|
issuer/audience/expiry/nbf/iat/required claims/scopes, algorithm/signature/ID-token
|
|
confusion, JWKS caching/rotation, actual TLS trust/hostname rejection, discovery
|
|
origin restrictions, HTTP redirect rejection and response/token size limits.
|
|
- `cargo metadata --manifest-path crates/oidc-auth/Cargo.toml --no-deps --format-version 1`:
|
|
independent workspace at `crates/oidc-auth`, exactly one member and own lockfile.
|
|
|
|
Initial build checks found missing URL serde and JWT PEM feature flags; both were
|
|
fixed. Clippy found an unnecessary test `format!`, also fixed. The final commands
|
|
above passed after those corrections. Pinned lockfile resolves jsonwebtoken 10.4.0,
|
|
reqwest 0.12.28 and rustls 0.23.46 on the repository's Rust 1.99.1 toolchain.
|
|
|
|
Not executed in that initial verification: external real-IdP interoperability, production SQL state adapter,
|
|
server routes/cookies/sessions/membership integration, VM execution or browser UI
|
|
login against the running RMM server. Timeout values are configured; a deliberately
|
|
stalling provider timeout test has not been run. No production acceptance claimed.
|