QDG Identity: operating and deployment workflow

Document version: 1.0.12. 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.

Budget and permanent plan features

Robert confirmed Free for launch, with Essentials as the intended upgrade when capacity or feature needs justify it. The signed-in account shows Free at $0; its Monthly/B2C/500-user Essentials quote is US$35 before tax. Temporary trial features remain available, so subscription and trial observations must be kept separate. No upgrade was purchased.

The core MCP OAuth design has documented support beyond the trial. Prepare the candidate within Free's one-tenant allowance; sharing a tenant for pilot and production is not isolated environments. Preserve the outstanding production MFA and log-retention decisions, and do not assume every future domain or user requirement fits the quoted tier. The Free-first plan review records account evidence, primary sources, limitations and the next configuration checks.

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.

After Robert's restart, a fresh desktop-managed agent directly used all ten attached pilot tools. It created a unique synthetic project/page, validated Markdown, read exact versions back, updated version 1 to 2, rejected a stale update without overwriting, and verified history and search. This was a real attached desktop connection using synthetic data, separate from the earlier independent engine tests and the existing production KB connector.

The older task retains an earlier failed connection although the fresh connection works. Approval UI was not observable during the test, so it is not claimed as verified. Record the remaining approval behavior, desktop application build and connection-recovery/restart observations before closing the whole desktop checkpoint. No repeated login or restart is required just to repeat successful tool checks. Interactive scope upgrade from a read-only token remains separate from the passing current-policy denials. See the live pilot evidence.

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

The new version 1.0.0 deployment handoff now packages the complete reviewed KB 1.2.0 and Identity 0.2.0 runtime with all 32 pinned dependencies. Robert's next command runs Prepare: fetch through RDP, verify the ZIP and every file, preserve earlier reports, collect fresh execution-time drift and missing destination evidence, generate configuration candidates privately on Odin and rehearse an offline installation. It automatically returns a sanitized report. The current KB service continues running throughout this preparation.

The first complete Prepare run has now returned from Odin. Its checksum matched Robert's console receipt. Package integrity, current collection, unchanged-file checks and all 32 offline runtime packages passed. The running KB service was preserved. Candidate generation alone failed because the wrapper supplied live configuration paths to a generator requiring private review snapshots. The earlier synthetic generator test had supplied snapshots, so it missed this integration mismatch.

The worker source is corrected to create protected, byte-identical snapshot copies and check source/copy hashes before generation. A separately pinned targeted repair reuses the downloaded package and successful checks, retries only candidate preparation and returns sanitized evidence. Do not rerun the full Prepare command or replace the immutable bundle to fix this step. The targeted repair has now run: snapshot creation succeeded, then the unchanged IIS baseline guard rejected a route detail. The service transform was not reached. No OAuth cutover has occurred. See the actual preparation review.

The next step is one separately pinned, read-only compatibility inspection of both XML files. It reports every IIS/service condition independently and tries both transforms in memory, so one failure does not hide another. It distinguishes omitted versus explicit attributes and empty rule sections, details the earlier collector did not return. The report contains finite states, booleans, counts and approved failure identifiers; raw XML stays private. It does not generate candidate files, reinstall packages or stop services. Review all returned mismatches before issuing another repair; do not repeat the failed repair unchanged or assume which IIS default caused the mismatch.

The package is built from exact Git archives and contains no personal policy, token, password or executable deployment plan. Literal Windows paths and ZIP separators are handled separately; tests cover spaces, underscores, repeated runs, altered files and failed child commands. Private ordinary-path TEMP/TMP avoids the earlier Windows short-path issue. Returned failures include fixed stage codes while raw configuration and process output remain on the host or are withheld. See the operator handoff guide and the artifact receipt for the exact reviewed command.

prepared_review_required means the report is ready to inspect, not that every check passed or OAuth was deployed. The same handoff supports Preflight and Deploy only with the exact reviewed private plan and its hash. The offline installation and protected preparation workspace are now verified on Odin; effective service permissions and production-client proof remain open.

Robert approved the separate production Auth0 registrations, which are now created in the existing AU tenant. The API protects only the live QDG Knowledge Base MCP audience. Its separate strict native Codex client has the exact callback, explicit read/write permission grant, ten-minute access tokens and rotating refresh tokens with a 24-hour maximum and one-hour idle limit. Offline access was enabled only after the saved renewal limits were verified. Machine access and default third-party grants remain denied.

Saved API/client/grant settings were reloaded and checked. The API comparison found no differences from the approved candidate. The new client has no pilot or Management API permissions and uses the existing dedicated directory with public signup disabled. Tenant resource compatibility remains enabled; dynamic client registration and metadata-document registration remain disabled. No subscription, user password, existing service or token retirement was changed.

The disabled additive Codex connection and private owner-only production entitlement are prepared as release inputs. Do not install the snippet as a replacement for existing configuration or enable it outside the reviewed acceptance sequence. Auth0 documents a public-client default for Dashboard-created native applications; its raw authentication-method field was not separately exposed. Prove this production client's actual PKCE S256 request and secretless exchange during controlled acceptance. The applied configuration record contains the public identifiers and evidence limits.

Registration completion does not establish production readiness. The remaining authentication/MFA, retention, ingress, service-account permissions, audit, deployment and recovery checks still apply. Reusing the current tenant under the Free budget does not waive these checks or migrate another QDG service.

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.