Skip to main content

OIDC provider

The Suite exposes a standard OpenID Connect authorization-code provider for Harlock and for the Suite itself.

EndpointPurpose
/.well-known/openid-configurationProvider discovery
/api/oidc/jwksCurrent and previous public signing keys
/api/oidc/authorizeAuthorization requests and SSO
/api/oidc/tokenAuthorization-code and refresh-token grants
/api/oidc/userinfoProfile claims for bearer access tokens
/api/oidc/logoutRP-initiated provider-session logout

OIDC_ISSUER is the canonical HTTPS origin used in discovery and every signed token. It is configuration rather than the request Host header, so a forged host cannot change the issuer of a token. NEXT_PUBLIC_SITE_URL is the fallback while the Suite still uses its existing deployment configuration.

Protocol invariants​

Only Authorization Code is supported. Every client, including confidential clients, must use PKCE with S256; there is no plain implementation and no per-client switch that disables PKCE. An authorization code expires after 60 seconds, is consumed once, and is bound to the client, the exact redirect URI used in the request, and the PKCE challenge.

The redirect distinction matters for Harlock. Its registered loopback URI may match ports 17650, 17651, or 17652, but once authorization chooses one port the code can be exchanged only with that exact URI. Registration flexibility does not weaken the code binding.

Access and ID tokens are RS256 JWTs that expire after 10 minutes. Every token carries the active signing-key kid; JWKS publishes the current and previous public keys as described in OIDC signing keys. During the RS256 migration, the previous public key can be ES256 so tokens issued before the upgrade remain verifiable. Authorization codes and refresh tokens are random opaque values, and only their SHA-256 hashes are stored in SQLite.

On an empty environment, the first JWKS or token request creates the initial key inside the Node service. A SQLite uniqueness constraint makes concurrent bootstrap requests converge on one current key. An environment with a legacy ES256 current key performs one automatic transactional upgrade to RS256; later changes remain deliberate operator rotations.

Refresh-token rotation​

Refresh tokens expire after 30 days and rotate on every use. The relationship between predecessor and successor remains in SQLite so replay can revoke the whole family, as required for a public client by OAuth 2.0 Security Best Current Practice.

Harlock gets one narrow exception for an interrupted local save. The immediate predecessor may be retried once within 10 seconds, producing one additional successor. It is no longer eligible once a child has itself been used. A second retry, a retry outside the window, or a retry further back in the chain revokes the entire family.

Temporary-password lifecycle​

An Administrator can issue a system-generated 20-character temporary password from User Management. SQLite stores only its salted PBKDF2 hash and a 30-minute expiry. The plaintext is returned once to the issuing screen and is not written to audit data.

Issuance increments accounts.session_version, revokes every active refresh token for the account, and removes its unconsumed authorization codes. Browser sessions carry the version at which they were created, so the middleware and server authorization guard reject older sessions immediately. Access tokens already issued remain valid only until their normal 10-minute expiry.

A conditional SQLite update consumes the temporary credential on its first valid login. The resulting encrypted browser session lasts 10 minutes and can reach only the password-change flow. The replacement must satisfy the provider password policy and cannot equal the temporary value. Successful replacement clears all temporary-password fields and creates a normal 30-day browser session at the current session version.

The structured auth_audit_logs table records issuance, consumption, and replacement with actor, subject, and timestamp. It intentionally has no free-form or secret-bearing column.

User lifecycle​

User Management provisions accounts directly in SQLite. An administrator-created account receives a temporary credential through the lifecycle above, so its first successful sign-in can reach only the forced password-change screen.

Disabling an account sets accounts.disabled_at, increments its session generation, revokes active refresh tokens, and removes unconsumed authorization codes in one SQLite batch. The account is excluded from provider login, code issue, token exchange, refresh, UserInfo, and server-side session authorization. Re-enabling it increments the generation again: no previous browser session is restored. Deletion removes the account and cascade-owned authentication data; historical lifecycle audit rows remain because they carry no account foreign key.

Every create, profile update, disable, enable, and delete records the actor, subject, event type, and timestamp in auth_audit_logs. The Users page prevents an administrator from disabling or deleting their own active account.

Current deployment state​

The Suite provider is active in test and production. It treats sab_session as its SSO session and authenticates credentials stored in SQLite. User provisioning, temporary-password recovery and account revocation are managed directly by the Suite.

Provisioning and retention​

Migration 0006_harlock_oidc_client.sql registers Harlock as client harlock, public and without a secret, with its loopback redirect. Migration 0021_arcadia_oidc_client.sql registers Arcadia, the multi-vehicle station, as client arcadia on the same terms and ports: a client of its own, so either station can be disabled or revoked without the other. Migration 0007_temporary_passwords.sql adds session generations, one-use consumption, and structured authentication audit events. Migration 0008_user_management.sql adds account status and lifecycle audit events. Migration 0009_oidc_rs256.sql preserves the existing signing key while allowing RS256 and making it the default for new keys. Apply them to test by the manual Oracle SQLite procedure before exercising the related provider flow.

Each environment needs OIDC_KEY_WRAP_SECRET before the first signing key can be created. The private key is generated inside the Node service and stored only in wrapped form; the secret itself never reaches SQLite.

The token endpoint runs purgeExpiredOidcRecords on every exchange. Cleanup is best effort: a retention failure is logged, but does not turn an otherwise valid authorization or refresh grant into an authentication outage.