10 KiB
RMM OIDC authentication adapter (standalone package)
Optional encrypted SQLx/PostgreSQL login-state storage and its migration/permissions
contract: 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 asCodeExchange; response bodies are not logged. - MCP: RFC 9068 JWT access token with
typ=at+jwt, dedicated resource audience, approvedclient_id, requiredjti, 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 browserazpmust 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
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 Errors, 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)
- 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-storeandReferrer-Policy: no-referreron all auth routes; avoid request/query logging and third-party resources there. - Set
LoginStart.binding_set_cookieverbatim:__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. - 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 withCLEAR_BINDING_COOKIE; failures require fresh login. - 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. - 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.
- Bearer always wins over browser cookies. Use
verify_mcp_beareronly 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. Preservepending_approvaland all immutable plan/attempt bindings. - 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.
- 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
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 atcrates/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.