QDG Identity: operating and deployment workflow

Document version: 1.0.6. 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. The dedicated QDG-Identity-Pilot-Users login directory is now created, with public signup disabled. Robert created his application account and verified its email; only his exact approved identity is mapped in protected local policy. He uses a separate pilot password, independent of his Auth0 dashboard login and existing QDBAuth services.

The directory is enabled for domain-level login, which makes it available to third-party clients in this Development tenant. That login availability alone does not grant KB access: explicit API/client grants and the MCP's current user policy still control access. The dedicated directory keeps pilot accounts separate from the existing directory. Confirm continuing subscription availability before production; the inspected tenant was still in its trial period.

A separate Codex pilot entry is configured. Robert completed hosted sign-in and consent, and Codex confirmed successful OAuth login. The saved session passed all ten real MCP tools against synthetic data, including create/update/readback, search/history, stable actor attribution and rejection of a stale update. Accepted calls enforce the exact approved identity and service-token contract without reading or publishing token contents.

Current-policy testing passed with that existing login: read-only access rejected a write with HTTP 403, disabled access rejected a read with HTTP 403, and restoration of the exact original policy restored access. The denied write did not change the page. These were temporary local pilot policy changes; other services were not involved. Independent Codex processes reused the saved login successfully, including all ten tools beyond the original token's maximum validity without another browser authorization. Actual desktop tool exposure, its approval interface and desktop restart/reconnection still need their distinct checks. See the live pilot evidence.

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. Controller 1.1.0 now provides an explicit initial-provisioning mode for the confirmed missing audit table/INSERT grant, protected user policy and permitted journal directories. Normal upgrades retain their existing prerequisite requirements. 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.

For initial provisioning, the operator can enter the separately approved database administrator password through a secure prompt on Odin. The helper creates temporary input with private permissions before writing the password, returns only a file reference/hash and removes the unchanged generated input after its last use. It preserves an operator-supplied private credential file. No password is entered into chat, a command argument, Git or the transferable package. This administrator is separate from the restricted KB runtime account; the workflow verifies its authority and metadata visibility without creating or resetting a database account.

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. In the explicitly reviewed first-cutover mode, inspect the existing database, durably record the observed state, create the exact audit table and its sole runtime INSERT grant, then publish the approved initial user policy without replacement. Verify that existing tables and grants remain unchanged.
5. Verify installed packages, database structure, current user policy and all live baselines. The final authentication probe requires at least five minutes of token validity remaining after its database checks.
6. Stop only KB MCP, apply the exact supported service and metadata-route changes, then restart.
7. Run semantic canaries for exact metadata, authentication challenge, rejected invalid/legacy-format credentials, permitted status read, rejected write scope, expected version and public HTTPS.
8. 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.

If initial table/grant preparation fails before the service switch, keep the current service running and preserve the journal and any compatible database additions for review. Database creation and grants cannot be undone as one transaction. A partially completed attempt is not automatically retried, and an existing or later-changed user policy always takes precedence over the proposed initial inventory. See the initial-provisioning contract.

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.