QDG Identity: operating and deployment workflow

Document version: 1.0.3. Updated 6 September 2026.

This page describes the current delivery workflow. It does not authorise a production change or claim a completed desktop/Odin proof. The detailed integration procedure for other QDG services will be completed after the first release works.

Stage 1: prove Robert's local connection

Use the separately scoped development Auth0 API and native public client. Finish the eligible login connection, then have Robert sign in through the hosted page. Record the verified issuer/subject and approved actor in protected policy.

Prove the actual Codex desktop flow: discovery, browser login, consent, a permitted read, a permitted synthetic write, rejected stale version, insufficient-scope denial, renewal, client restart and local access removal while an issued token still exists. A CLI authorization request reaching Auth0 is useful diagnostic evidence but does not close the desktop checkpoint.

The local pilot uses bounded synthetic in-memory data and the actual MCP transport. Keep production credentials and content out of the pilot. Follow the local pilot guide, recording actual results separately from its proposed client steps.

Stage 2: collect Odin information once

Use the reviewed Collect-OdinOAuthReadiness.ps1 from the KB MCP repository in elevated 64-bit Windows PowerShell on Odin. The script has fixed KB-only host/path boundaries and writes one new sanitised JSON report. Robert's standard handoff is now a single PowerShell command: fetch the exact reviewed ZIP through the existing RDP drive, verify its pinned SHA-256, clean only matching old collector artifacts, extract, execute with a new full report path and return the report automatically. Previous reports and unrelated configuration scripts are preserved. The handoff source implements this sequence.

The first Odin report was received and its hash matched. Collector 1.0.0 misread ordinary WinSW XML, leaving package and database evidence incomplete. Collector 1.0.1 fixed that parser issue and package-name casing, and checks the output path before probes. Its live handoff has now completed and the corrected report returned automatically, with report identity and source validation. Both reports remain preserved; no repeat collection is needed simply to resolve the earlier gaps.

The corrected report confirms the running service, dedicated account, private Python runtime, loopback listener, existing KB package metadata and restricted database access. The OAuth audit table and INSERT permission, shared Identity package, protected user policy and discovery route are absent. Ingress encryption, logging and effective permissions still need their separate operating review.

It collects service state and identity, configuration/artifact hashes, file and directory permissions, runtime evidence, local/effective IIS route findings, the KB listener, read-only database/schema/grant findings and unauthenticated HTTP status observations. It checks for file/ACL/service changes during collection.

Return only the sanitised report and its displayed SHA-256 for review. Keep database configuration, credentials, user policy, raw XML and private backups on Odin. Unknown or skipped checks remain visible rather than becoming assumed defaults.

The collector makes no service, IIS, network, account or database changes. Its only persistent output is the new report. The collector operating guide contains the exact invocation, supported paths, output handling and limits.

Stage 3: prepare the host-specific release

Review the report and bind the release plan to the exact host, configuration and artifact hashes. Resolve missing runtime, initial policy or database migration prerequisites before preparing the final execution package. The existing cutover controller requires those prerequisites to be present; initial provisioning needs a separately explicit and tested phase within the reviewed workflow. Preserve the original report and record the exact authorised additions and their verified results separately. Do not require operators to edit report findings to make them appear verified.

The deployment package must contain the committed application/shared-package artifacts, complete offline dependency lock, exact configuration candidates, reviewed probes, protected probe-input references and current recovery plan. Credentials stay outside the transferable release bundle.

Some facts require evidence beyond the local collector. Public HTTPS does not prove encryption from an external proxy to Odin. Likewise, local IIS log fields do not prove what every other hop records. Service-account effective permissions require review of the collected access rules. These separately reviewed captures must be bound to the same report/host/candidate and have a validity period.

Stage 4: execute one reviewed deployment invocation

The deployment controller defaults to preflight. Execution is explicit and requires a reviewed plan/hash. Its intended sequence is:

1. Acquire the exclusive KB deployment lock and validate the host, current files, permissions and evidence.
2. Protect backups and the deployment journal.
3. Stage the exact application and dependencies offline without stopping the working service.
4. Verify installed packages and run read-only prerequisite probes; recheck all live baselines.
5. Stop only KB MCP, apply the exact supported service and metadata-route changes, then restart.
6. Run semantic canaries for exact metadata, authentication challenge, rejected invalid/legacy-format credentials, permitted status read, rejected write scope, expected version and public HTTPS.
7. Record success or perform verified OAuth-safe recovery. Refuse to overwrite an intervening website/configuration change.

A first cutover from an old static-token release may have no safe automatic rollback. In that case the controller leaves KB MCP stopped with a recovery journal instead of reopening retired credentials. Existing QDBAuth websites and other services are not migrated or restarted by this workflow.

The controller does not silently create people, broaden grants, migrate other applications, activate emergency access or manufacture proof for missing prerequisites. See the deployment contract; the final host-specific invocation awaits verified initial provisioning, live client proof and the remaining operating evidence.

Stage 5: accept and operate

After Robert's production connection and the release canaries pass, retire only old KB MCP credentials and onboard approved people through individually tested clients. Verify denied access remains denied after recovery.

Rehearse the separate Auth0 outage procedure before relying on it: independent Odin administration, protected temporary activation, Robert-only reads, denied writes, immediate removal, fixed expiry, audit-storage failure and return to normal OAuth.

Keep source tests, installed-package checks, real-client evidence and production recovery evidence distinct. Store protected incident and deployment evidence under the agreed retention policy. Update the Change Log and operating pages after meaningful changes.

Giving and removing KB access

Robert approves the person, supported client and KB permissions. Verify the person's Auth0 issuer and stable subject, then add the explicit service entitlement to protected policy using the reviewed validation and file-permission procedure. Grant both read and write explicitly for an approved writer. Test the resulting allowed and denied operations; a dashboard invitation or successful login alone does not complete onboarding. The shared package guide defines the policy contract.

For KB-only removal, first remove or disable the person's KB entitlement in the current protected policy. Verify that an already issued token is denied, including any active emergency access. Preserve the actor's historical audit attribution. Apply the relevant client/session or refresh-token revocation as part of the reviewed account procedure, but do not rely on an Auth0 account change alone to invalidate every previously signed access token immediately.

Distinguish service removal from organisation-wide offboarding. When other services later share Auth0, disabling the central account can affect those services too; Robert must approve that wider scope. Day-one KB changes do not alter existing QDBAuth accounts or credentials.

Integrating other services later

The later detailed guide will cover selecting a resource/audience, registering clients/callbacks, choosing permissions, integrating the shared verifier, defining current access policy, testing discovery and claims, validating audit/revocation, packaging, staged cutover and support ownership.

The detailed guide is a required completion deliverable after the first verified deployment. Robert owns acceptance. Before presenting it as a procedure other developers can follow, it must contain:

1. The accepted Identity/KB release versions, exact artifacts and tested client versions, with development and production settings clearly separated.
2. Recorded evidence for hosted login, reads/writes, scope denial, renewal, restart, existing-token revocation and rejection of tokens issued for another service.
3. The verified Odin deployment, database audit/grant, ingress, file-permission and recovery procedures, including outage limits and emergency expiry.
4. A worked example for an additional service, tested with synthetic data, showing registration, exact callbacks/resource, shared verifier integration, current permissions and application-specific audit. MCP and website/OIDC session requirements must be distinguished.
5. An operator checklist for onboarding, removal, monitoring, troubleshooting, staged migration and OAuth-safe recovery, with a named service owner and support responsibilities.
6. A walkthrough by another developer or operator, with shortcomings corrected and Robert's acceptance recorded. Pin instructions to reviewed release versions so later changes are traceable.

This checklist records future work; no second service is being migrated now. Those services keep existing authentication until their own reviewed migration. No integration is completed merely by adding a client in Auth0.